{ "openapi": "3.0.3", "info": { "title": "Upvest Investment API", "version": "1.140.0", "description": "Upvest Investment API.", "contact": { "name": "Upvest API Support", "email": "api@upvest.co", "url": "https://docs.upvest.co" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0" } }, "tags": [ { "name": "Access Tokens", "description": "All authentication related paths." }, { "name": "Files", "description": "All files API related paths." }, { "name": "Webhooks", "description": "All webhook related paths." }, { "name": "Webhook Subscriptions", "description": "All webhook subscriptions related paths." }, { "name": "Users", "description": "All user related paths." }, { "name": "User Identifiers", "description": "All user identifiers related paths." }, { "name": "User Checks", "description": "All user checks related paths." }, { "name": "Accounts", "description": "All accounts related paths" }, { "name": "Tax Exemptions", "description": "All tax exemptions related paths" }, { "name": "Tax Wrappers", "description": "All tax wrappers related paths" }, { "name": "Tax Collections", "description": "All tax collections related paths" }, { "name": "Account Groups", "description": "All account groups related paths" }, { "name": "Reference Accounts", "description": "All reference account related paths" }, { "name": "Mandates", "description": "All direct debit mandates related paths" }, { "name": "Direct Debits", "description": "All direct debits related paths" }, { "name": "Credit Fundings", "description": "All credit fundings related paths" }, { "name": "Top-ups", "description": "All top-ups related paths" }, { "name": "Cash Balance Transfers", "description": "All cash balance transfer related paths" }, { "name": "Withdrawals", "description": "All withdrawals related paths" }, { "name": "Virtual Bank Accounts", "description": "All virtual bank accounts related paths" }, { "name": "Cash Balances", "description": "All cash balance related paths" }, { "name": "Instruments", "description": "All instrument related paths." }, { "name": "Price Data", "description": "All price data related paths." }, { "name": "Orders", "description": "All order related paths." }, { "name": "Executions", "description": "All execution related paths." }, { "name": "Positions", "description": "All positions related paths." }, { "name": "Treasury Reports", "description": "All treasury reports related paths." }, { "name": "Reports", "description": "All reports related paths." }, { "name": "Tax Residencies", "description": "All tax residencies related paths." }, { "name": "Transactions", "description": "All transactions related paths." }, { "name": "Fees", "description": "All fees related paths." }, { "name": "Fees Configurations", "description": "All fees configurations related paths." }, { "name": "Transaction Fees", "description": "All transaction fees related paths." }, { "name": "Transaction Fees Models", "description": "All transaction fees models related paths." }, { "name": "Portfolios", "description": "All portfolios related paths." }, { "name": "Portfolios Rebalancing", "description": "All portfolios rebalancing related paths." }, { "name": "Valuations", "description": "All valuations related paths." }, { "name": "Liquidations", "description": "All accounts liquidations related paths." }, { "name": "Returns", "description": "All accounts returns related paths." }, { "name": "Virtual Cash Balances", "description": "All virtual cash balances related paths" }, { "name": "Savings Plans", "description": "All savings plans related paths." }, { "name": "Tests", "description": "All test related paths." }, { "name": "Corporate Actions", "description": "All Corporate Action related paths." }, { "name": "Securities Transfers", "description": "All Securities Transfers related paths." }, { "name": "Account Transfers", "description": "All Accounts Transfers related paths." }, { "name": "ISA Transfers", "description": "All ISA Transfers related paths." }, { "name": "Businesses", "description": "All Businesses related paths." }, { "name": "Business Checks", "description": "All Business Checks related paths." }, { "name": "Roles", "description": "All Roles related paths." } ], "x-tagGroups": [ { "name": "Authentication", "tags": [ "Access Tokens" ] }, { "name": "Users and Businesses", "tags": [ "Users", "User Identifiers", "User Checks", "Businesses", "Business Checks", "Roles", "Tax Residencies" ] }, { "name": "Account Management", "tags": [ "Accounts", "Account Groups" ] }, { "name": "Corporate Actions", "tags": [ "Corporate Actions" ] }, { "name": "Tax Wrappers", "tags": [ "Tax Wrappers", "ISA Transfers" ] }, { "name": "Taxes", "tags": [ "Tax Exemptions", "Tax Collections" ] }, { "name": "Instruments & Price Data", "tags": [ "Instruments", "Price Data" ] }, { "name": "Orders", "tags": [ "Orders" ] }, { "name": "Investment Solutions", "tags": [ "Portfolios", "Portfolios Rebalancing", "Savings Plans", "Liquidations" ] }, { "name": "Payments", "tags": [ "Direct Debits", "Top-ups", "Withdrawals", "Cash Balance Transfers", "Reference Accounts", "Mandates", "Virtual Bank Accounts", "Credit Fundings" ] }, { "name": "Balances", "tags": [ "Cash Balances", "Positions", "Valuations", "Returns", "Virtual Cash Balances" ] }, { "name": "Fees", "tags": [ "Fees", "Fees Configurations" ] }, { "name": "Transaction Fees", "tags": [ "Transaction Fees Models" ] }, { "name": "Reporting", "tags": [ "Reports", "Treasury Reports", "Transactions", "Files" ] }, { "name": "Securities Transfers", "tags": [ "Account Transfers", "Securities Transfers" ] }, { "name": "Webhooks", "tags": [ "Webhook Subscriptions" ] }, { "name": "Tests", "tags": [ "Tests" ] } ], "servers": [ { "url": "https://sandbox.upvest.co", "description": "Sandbox environment" }, { "url": "https://api.upvest.co", "description": "Live environment" } ], "paths": { "/auth/token": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "post": { "operationId": "issue_token", "summary": "Get an access token for requested scopes", "description": "Get an access token to use with the API with specified scopes.\n\nYou should _always_ scope your access tokens. You get one for read-access and separate ones for updating, creating or deleting resources.", "tags": [ "Access Tokens" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "title": "Request - Auth - Request Access Token", "type": "object", "description": "Schema for access token request.", "properties": { "client_id": { "type": "string", "format": "uuid", "description": "Client ID given during onboarding." }, "client_secret": { "type": "string", "maxLength": 1000, "description": "Client Secret given during onboarding." }, "grant_type": { "type": "string", "default": "client_credentials", "description": "This must always be `client_credentials`." }, "scope": { "type": "string", "maxLength": 1000, "description": "List of space delimited scopes to request for this access token." } }, "required": [ "client_id", "client_secret", "grant_type", "scope" ], "additionalProperties": false }, "example": { "client_id": "363f3305-7ab0-4e82-a158-f9d382ad08b6", "client_secret": "WHIW1yic-ouct3sceh", "grant_type": "client_credentials", "scope": "users:read" } } } }, "responses": { "200": { "description": "Access token successfully generated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Auth - Access Token", "type": "object", "description": "Schema for an access token response.", "properties": { "access_token": { "type": "string", "maxLength": 1000, "description": "The generated access token." }, "expires_in": { "type": "integer", "description": "How many seconds the access token is valid for." }, "token_type": { "type": "string", "default": "bearer", "description": "This is always 'bearer'." }, "scope": { "type": "string", "maxLength": 1000, "description": "List of space delimited scopes requested for this access token." } }, "required": [ "access_token", "expires_in", "token_type", "scope" ], "additionalProperties": false }, "example": { "access_token": "token.signature", "expires_in": 1800, "token_type": "bearer", "scope": "users:read" } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/auth/verify_keys": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "get_jwks", "summary": "Get signing keys", "description": "Returns a list of signing keys used to verify webhooks.", "tags": [ "Webhook Subscriptions" ], "security": [ { "oauth-client-credentials": [ "webhooks:read", "webhooks:admin" ] } ], "responses": { "200": { "description": "JWKS signing public keys", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Auth - Verification keys", "type": "object", "description": "Webhooks verification keys.", "properties": { "keys": { "type": "array", "description": "List of verification keys", "items": { "type": "object", "properties": { "kid": { "type": "string", "format": "uuid", "description": "Key ID" }, "kty": { "type": "string", "enum": [ "EC" ], "default": "EC", "description": "Cryptographic algorithm family used with the key.\n* EC - " }, "crv": { "type": "string", "description": "Elliptic curve family.\n* P-521 - ", "enum": [ "P-521" ], "default": "P-521" }, "x": { "type": "string", "description": "Curve parameter" }, "y": { "type": "string", "description": "Curve parameter" } } } } }, "required": [ "keys" ], "additionalProperties": false }, "example": { "keys": [ { "kid": "9ed77463-c18e-4794-ab5c-17423f9b801a", "kty": "EC", "crv": "P-521", "x": "AcYAf5Ou0UvtehpeRvyhnvvrUQvjI4B3VCxfSmxK4gqKJGxO_jTB-nTdrHbBfmZpwmwYR86DppMg43E579K5MQ54", "y": "ALkrId77iD0Ye2vBS5bTkLqPH-bo8urTpTXiNc6Ub-VOFbXfJrR0tQ8COvVXXu58BTu8jWV-1mtbjfJpDl3ISbcK" } ] } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/files/{folder}/{file_name}": { "parameters": [ { "name": "folder", "in": "path", "description": "Folder containing the file. Must match the pattern `^[a-z0-9-_\\.]{1,32}$`.", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-_\\.]{1,32}$", "example": "booking_references" } }, { "name": "file_name", "in": "path", "description": "Name of the file to retrieve. Must match the pattern `^[a-z0-9-_\\.]{1,255}$`.", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-_\\.]{1,255}$", "example": "list.txt" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "fetching_file_metadata", "summary": "Retrieve a file metadata", "description": "Retrieve a file metadata", "tags": [ "Files" ], "security": [ { "oauth-client-credentials": [ "files:read" ] } ], "parameters": [ { "name": "redirect", "in": "query", "required": false, "schema": { "type": "string", "default": 0 }, "description": "To enable HTTP redirect." } ], "responses": { "200": { "description": "Returns a files metadata object if a valid name and folder are provided.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Files metadata", "type": "object", "additionalProperties": false, "properties": { "id": { "title": "Metadata ID", "type": "string", "description": "Files metadata identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "signed_url": { "type": "string", "format": "url", "maxLength": 1000, "description": "Files download URL." }, "file_name": { "type": "string", "pattern": "^[a-z0-9-_\\.]{1,32}$", "description": "Name of the file." }, "content_length": { "type": "integer", "description": "Length of the file" }, "checksum": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "CRC32 of the files content" } }, "required": [ "id", "created_at", "updated_at", "file_name", "signed_url", "content_length", "checksum" ] }, "example": { "id": "d588e071-6e02-4ae6-a2b6-a5f08499633b", "created_at": "2024-03-04T08:24:18Z", "updated_at": "2024-03-14T11:18:39Z", "signed_url": "https://storage.googleapis.com/upvest-tooling-datasharing-service-ia-unstable-7263/477ed9c4943c47f235712a1e80c1ef8491768f0a31ed2d81f244dfebe418e909/tats-tests-encrypted-text.txt?Expires=1710415438&GoogleAccessId=tooling-datasharing-service%40ia-unstable-7263.iam.gserviceaccount.com&Signature=cxb7JQXJVfO6ltBK%2FCWJkzoQcONakNiVsitn0nwtLDJmBj4cznBbMnT0yKtIO4v7BjhR92JmUd9wm7MurZYcuxdBPTMk%2BLTl0KN3QMEJ7%2FVjM1zSerIOxQ8OLFWCswt16Fj9%2BpwD7ZMplIrSEBGijPD48gLlZF%2FTW4yPqkLbE6sYn5Kn3K9A%2B3iF7%2BUaljQ2jLTxG9vCapp8WKjGjDyDXRtDDYY7OXJ6aDrjxDEUxO6kkOGzxMEBCALoHjD2lMpkEy5Gp1BkUbPka7hYVrbQrDM1xpBRsq%2F%2FCT%2F%2Bt196e8JP9YGr%2FxeA%2Bqt6ZTTryzGZhHlvHJFjqIqj2Ip7HioFjw%3D%3D", "file_name": "tats-tests-encrypted-text.txt", "content_length": 919, "checksum": "709b190a108791217f62d839f85a7a997c2039cc29a737d59fd50454b85b2956" } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/webhooks": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_webhooks", "summary": "List all webhook subscriptions", "description": "Returns a list of all webhook subscriptions.", "tags": [ "Webhook Subscriptions" ], "security": [ { "oauth-client-credentials": [ "webhooks:read", "webhooks:admin" ] } ], "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "updated_at", "title", "url", "enabled" ], "default": "created_at" }, "description": "Sort the result by `created_at`, `updated_at`, `title`, `url`, or `enabled`." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." } ], "responses": { "200": { "description": "An object with a data property that contains an array of webhook subscription objects.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Webhooks - List - Response", "type": "object", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "items": { "title": "Webhook", "type": "object", "additionalProperties": false, "properties": { "id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "title": { "type": "string", "pattern": "^[a-zA-Z0-9 ()\\[\\]{}.-]{1,32}$", "description": "Title of the webhook for use on tenant side." }, "url": { "type": "string", "format": "url", "maxLength": 1000, "description": "The callback URL to be called by the webhook." }, "enabled": { "type": "boolean", "description": "Enable/disable webhook." }, "type": { "type": "array", "description": "What kind of events to be sent by the webhook.", "default": [ "ALL" ], "items": { "type": "string", "enum": [ "ALL", "BUSINESS", "ROLE", "USER", "USER_CHECK", "ORDER", "ORDER_CANCELLATION", "EXECUTION", "POSITION", "CASH_BALANCE", "ACCOUNT", "ACCOUNT_GROUP", "INSTRUMENT", "REPORT", "TREASURY_REPORT", "DIRECT_DEBIT", "WITHDRAWAL", "PORTFOLIO", "PORTFOLIO_ALLOCATION", "PORTFOLIO_ORDER", "CORPORATE_ACTION", "ACCOUNT_VALUATION", "INTRADAY_ACCOUNT_VALUATION", "CASH_TRANSACTION", "SECURITY_TRANSACTION", "ACCOUNT_LIQUIDATION", "ACCOUNT_RETURNS", "VIRTUAL_CASH_INCREASE", "VIRTUAL_CASH_DECREASE", "FEE_COLLECTION", "SAVINGS_PLAN", "SAVINGS_PLAN_EXECUTION", "REBALANCING_EXECUTION_ORDER", "TAX_EXEMPTION", "TAX_COLLECTION", "ISA_WRAPPER", "ISA_WRAPPER_ALLOWANCE", "CREDIT_FUNDING", "VIRTUAL_BANK_ACCOUNT", "SECURITIES_TRANSFER", "ACCOUNT_TRANSFER", "TOPUP", "ISA_TRANSFER" ] } }, "exclude_type": { "type": "array", "description": "What kind of events to be excluded if subscription type is: ALL.", "items": { "type": "string", "enum": [ "BUSINESS", "ROLE", "USER", "USER_CHECK", "ORDER", "ORDER_CANCELLATION", "EXECUTION", "POSITION", "CASH_BALANCE", "ACCOUNT", "ACCOUNT_GROUP", "INSTRUMENT", "REPORT", "TREASURY_REPORT", "DIRECT_DEBIT", "WITHDRAWAL", "PORTFOLIO", "PORTFOLIO_ALLOCATION", "PORTFOLIO_ORDER", "CORPORATE_ACTION", "ACCOUNT_VALUATION", "INTRADAY_ACCOUNT_VALUATION", "CASH_TRANSACTION", "SECURITY_TRANSACTION", "ACCOUNT_LIQUIDATION", "ACCOUNT_RETURNS", "VIRTUAL_CASH_INCREASE", "VIRTUAL_CASH_DECREASE", "FEE_COLLECTION", "SAVINGS_PLAN", "SAVINGS_PLAN_EXECUTION", "REBALANCING_EXECUTION_ORDER", "TAX_EXEMPTION", "TAX_COLLECTION", "ISA_WRAPPER", "ISA_WRAPPER_ALLOWANCE", "CREDIT_FUNDING", "VIRTUAL_BANK_ACCOUNT", "SECURITIES_TRANSFER", "ACCOUNT_TRANSFER", "TOPUP", "ISA_TRANSFER" ] } }, "config": { "type": "object", "description": "Configuration of webhook packages collection.", "properties": { "delay": { "type": "string", "pattern": "^([1-9]|[12][0-9]|30)s$", "description": "Maximum time of package collection (1s-30s)." }, "max_package_size": { "type": "integer", "minimum": 100, "maximum": 1048576, "description": "Maximum package size (bytes)" } } } }, "required": [ "id", "created_at", "updated_at", "title", "url", "enabled", "type", "config" ] } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "example": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1, "sort": "id", "order": "ASC" }, "data": [ { "id": "a8eb3540-5a84-40f9-b2bb-7f99f282fc5a", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "title": "User webhook", "url": "https://tenant.tld/webhooks/users", "type": [ "USER" ], "enabled": false, "config": { "delay": "5s", "max_package_size": 10240 } } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "post": { "operationId": "create_webhook", "summary": "Create a webhook subscription", "description": "Creates a webhook subscription.", "tags": [ "Webhook Subscriptions" ], "security": [ { "oauth-client-credentials": [ "webhooks:admin" ] } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Create - Request", "type": "object", "properties": { "title": { "type": "string", "pattern": "^[a-zA-Z0-9 ()\\[\\]{}.-]{1,32}$", "description": "Title of the webhook for use on tenant side." }, "url": { "type": "string", "format": "url", "maxLength": 1000, "description": "The callback URL to be called by the webhook." }, "type": { "type": "array", "description": "What kind of events to be sent by the webhook.", "default": [ "ALL" ], "items": { "type": "string", "enum": [ "ALL", "BUSINESS", "ROLE", "USER", "USER_CHECK", "ORDER", "ORDER_CANCELLATION", "EXECUTION", "POSITION", "CASH_BALANCE", "ACCOUNT", "ACCOUNT_GROUP", "INSTRUMENT", "REPORT", "TREASURY_REPORT", "DIRECT_DEBIT", "WITHDRAWAL", "PORTFOLIO", "PORTFOLIO_ALLOCATION", "PORTFOLIO_ORDER", "CORPORATE_ACTION", "ACCOUNT_VALUATION", "INTRADAY_ACCOUNT_VALUATION", "CASH_TRANSACTION", "SECURITY_TRANSACTION", "ACCOUNT_LIQUIDATION", "ACCOUNT_RETURNS", "VIRTUAL_CASH_INCREASE", "VIRTUAL_CASH_DECREASE", "FEE_COLLECTION", "SAVINGS_PLAN", "SAVINGS_PLAN_EXECUTION", "REBALANCING_EXECUTION_ORDER", "TAX_EXEMPTION", "TAX_COLLECTION", "ISA_WRAPPER", "ISA_WRAPPER_ALLOWANCE", "CREDIT_FUNDING", "VIRTUAL_BANK_ACCOUNT", "SECURITIES_TRANSFER", "ACCOUNT_TRANSFER", "TOPUP", "ISA_TRANSFER" ] } }, "exclude_type": { "type": "array", "description": "What kind of events to be excluded if subscription type is: ALL.", "items": { "type": "string", "enum": [ "BUSINESS", "ROLE", "USER", "USER_CHECK", "ORDER", "ORDER_CANCELLATION", "EXECUTION", "POSITION", "CASH_BALANCE", "ACCOUNT", "ACCOUNT_GROUP", "INSTRUMENT", "REPORT", "TREASURY_REPORT", "DIRECT_DEBIT", "WITHDRAWAL", "PORTFOLIO", "PORTFOLIO_ALLOCATION", "PORTFOLIO_ORDER", "CORPORATE_ACTION", "ACCOUNT_VALUATION", "INTRADAY_ACCOUNT_VALUATION", "CASH_TRANSACTION", "SECURITY_TRANSACTION", "ACCOUNT_LIQUIDATION", "ACCOUNT_RETURNS", "VIRTUAL_CASH_INCREASE", "VIRTUAL_CASH_DECREASE", "FEE_COLLECTION", "SAVINGS_PLAN", "SAVINGS_PLAN_EXECUTION", "REBALANCING_EXECUTION_ORDER", "TAX_EXEMPTION", "TAX_COLLECTION", "ISA_WRAPPER", "ISA_WRAPPER_ALLOWANCE", "CREDIT_FUNDING", "VIRTUAL_BANK_ACCOUNT", "SECURITIES_TRANSFER", "ACCOUNT_TRANSFER", "TOPUP", "ISA_TRANSFER" ] } }, "config": { "type": "object", "description": "Configuration of webhook packages collection.", "properties": { "delay": { "type": "string", "pattern": "^([1-9]|[12][0-9]|30)s$", "description": "Maximum time of package collection (1s-30s)." }, "max_package_size": { "type": "integer", "minimum": 100, "maximum": 1048576, "description": "Maximum package size (bytes)" } } } }, "required": [ "title", "url" ], "additionalProperties": false }, "example": { "title": "User webhook", "url": "https://tenant.tld/webhooks/users", "type": [ "USER" ], "config": { "delay": "1s", "max_package_size": 51200 } } } } }, "responses": { "201": { "description": "Returns a webhook subscription object if a valid webhook subscription object ID was provided.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Webhook", "type": "object", "additionalProperties": false, "properties": { "id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "title": { "type": "string", "pattern": "^[a-zA-Z0-9 ()\\[\\]{}.-]{1,32}$", "description": "Title of the webhook for use on tenant side." }, "url": { "type": "string", "format": "url", "maxLength": 1000, "description": "The callback URL to be called by the webhook." }, "enabled": { "type": "boolean", "description": "Enable/disable webhook." }, "type": { "type": "array", "description": "What kind of events to be sent by the webhook.", "default": [ "ALL" ], "items": { "type": "string", "enum": [ "ALL", "BUSINESS", "ROLE", "USER", "USER_CHECK", "ORDER", "ORDER_CANCELLATION", "EXECUTION", "POSITION", "CASH_BALANCE", "ACCOUNT", "ACCOUNT_GROUP", "INSTRUMENT", "REPORT", "TREASURY_REPORT", "DIRECT_DEBIT", "WITHDRAWAL", "PORTFOLIO", "PORTFOLIO_ALLOCATION", "PORTFOLIO_ORDER", "CORPORATE_ACTION", "ACCOUNT_VALUATION", "INTRADAY_ACCOUNT_VALUATION", "CASH_TRANSACTION", "SECURITY_TRANSACTION", "ACCOUNT_LIQUIDATION", "ACCOUNT_RETURNS", "VIRTUAL_CASH_INCREASE", "VIRTUAL_CASH_DECREASE", "FEE_COLLECTION", "SAVINGS_PLAN", "SAVINGS_PLAN_EXECUTION", "REBALANCING_EXECUTION_ORDER", "TAX_EXEMPTION", "TAX_COLLECTION", "ISA_WRAPPER", "ISA_WRAPPER_ALLOWANCE", "CREDIT_FUNDING", "VIRTUAL_BANK_ACCOUNT", "SECURITIES_TRANSFER", "ACCOUNT_TRANSFER", "TOPUP", "ISA_TRANSFER" ] } }, "exclude_type": { "type": "array", "description": "What kind of events to be excluded if subscription type is: ALL.", "items": { "type": "string", "enum": [ "BUSINESS", "ROLE", "USER", "USER_CHECK", "ORDER", "ORDER_CANCELLATION", "EXECUTION", "POSITION", "CASH_BALANCE", "ACCOUNT", "ACCOUNT_GROUP", "INSTRUMENT", "REPORT", "TREASURY_REPORT", "DIRECT_DEBIT", "WITHDRAWAL", "PORTFOLIO", "PORTFOLIO_ALLOCATION", "PORTFOLIO_ORDER", "CORPORATE_ACTION", "ACCOUNT_VALUATION", "INTRADAY_ACCOUNT_VALUATION", "CASH_TRANSACTION", "SECURITY_TRANSACTION", "ACCOUNT_LIQUIDATION", "ACCOUNT_RETURNS", "VIRTUAL_CASH_INCREASE", "VIRTUAL_CASH_DECREASE", "FEE_COLLECTION", "SAVINGS_PLAN", "SAVINGS_PLAN_EXECUTION", "REBALANCING_EXECUTION_ORDER", "TAX_EXEMPTION", "TAX_COLLECTION", "ISA_WRAPPER", "ISA_WRAPPER_ALLOWANCE", "CREDIT_FUNDING", "VIRTUAL_BANK_ACCOUNT", "SECURITIES_TRANSFER", "ACCOUNT_TRANSFER", "TOPUP", "ISA_TRANSFER" ] } }, "config": { "type": "object", "description": "Configuration of webhook packages collection.", "properties": { "delay": { "type": "string", "pattern": "^([1-9]|[12][0-9]|30)s$", "description": "Maximum time of package collection (1s-30s)." }, "max_package_size": { "type": "integer", "minimum": 100, "maximum": 1048576, "description": "Maximum package size (bytes)" } } } }, "required": [ "id", "created_at", "updated_at", "title", "url", "enabled", "type", "config" ] }, "example": { "id": "a8eb3540-5a84-40f9-b2bb-7f99f282fc5a", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "title": "User webhook", "url": "https://tenant.tld/webhooks/users", "type": [ "USER" ], "enabled": false, "config": { "delay": "5s", "max_package_size": 10240 } } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/webhooks/{webhook_id}": { "parameters": [ { "name": "webhook_id", "in": "path", "description": "The unique identifier of the webhook subscription. Universally Unique Identifier (UUID).", "required": true, "schema": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_webhook", "summary": "Retrieve a webhook subscription", "description": "Returns a webhook subscription specified by its ID.", "tags": [ "Webhook Subscriptions" ], "security": [ { "oauth-client-credentials": [ "webhooks:read", "webhooks:admin" ] } ], "responses": { "200": { "description": "Returns a webhook subscription object if a valid webhook subscription object ID was provided.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Webhook", "type": "object", "additionalProperties": false, "properties": { "id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "title": { "type": "string", "pattern": "^[a-zA-Z0-9 ()\\[\\]{}.-]{1,32}$", "description": "Title of the webhook for use on tenant side." }, "url": { "type": "string", "format": "url", "maxLength": 1000, "description": "The callback URL to be called by the webhook." }, "enabled": { "type": "boolean", "description": "Enable/disable webhook." }, "type": { "type": "array", "description": "What kind of events to be sent by the webhook.", "default": [ "ALL" ], "items": { "type": "string", "enum": [ "ALL", "BUSINESS", "ROLE", "USER", "USER_CHECK", "ORDER", "ORDER_CANCELLATION", "EXECUTION", "POSITION", "CASH_BALANCE", "ACCOUNT", "ACCOUNT_GROUP", "INSTRUMENT", "REPORT", "TREASURY_REPORT", "DIRECT_DEBIT", "WITHDRAWAL", "PORTFOLIO", "PORTFOLIO_ALLOCATION", "PORTFOLIO_ORDER", "CORPORATE_ACTION", "ACCOUNT_VALUATION", "INTRADAY_ACCOUNT_VALUATION", "CASH_TRANSACTION", "SECURITY_TRANSACTION", "ACCOUNT_LIQUIDATION", "ACCOUNT_RETURNS", "VIRTUAL_CASH_INCREASE", "VIRTUAL_CASH_DECREASE", "FEE_COLLECTION", "SAVINGS_PLAN", "SAVINGS_PLAN_EXECUTION", "REBALANCING_EXECUTION_ORDER", "TAX_EXEMPTION", "TAX_COLLECTION", "ISA_WRAPPER", "ISA_WRAPPER_ALLOWANCE", "CREDIT_FUNDING", "VIRTUAL_BANK_ACCOUNT", "SECURITIES_TRANSFER", "ACCOUNT_TRANSFER", "TOPUP", "ISA_TRANSFER" ] } }, "exclude_type": { "type": "array", "description": "What kind of events to be excluded if subscription type is: ALL.", "items": { "type": "string", "enum": [ "BUSINESS", "ROLE", "USER", "USER_CHECK", "ORDER", "ORDER_CANCELLATION", "EXECUTION", "POSITION", "CASH_BALANCE", "ACCOUNT", "ACCOUNT_GROUP", "INSTRUMENT", "REPORT", "TREASURY_REPORT", "DIRECT_DEBIT", "WITHDRAWAL", "PORTFOLIO", "PORTFOLIO_ALLOCATION", "PORTFOLIO_ORDER", "CORPORATE_ACTION", "ACCOUNT_VALUATION", "INTRADAY_ACCOUNT_VALUATION", "CASH_TRANSACTION", "SECURITY_TRANSACTION", "ACCOUNT_LIQUIDATION", "ACCOUNT_RETURNS", "VIRTUAL_CASH_INCREASE", "VIRTUAL_CASH_DECREASE", "FEE_COLLECTION", "SAVINGS_PLAN", "SAVINGS_PLAN_EXECUTION", "REBALANCING_EXECUTION_ORDER", "TAX_EXEMPTION", "TAX_COLLECTION", "ISA_WRAPPER", "ISA_WRAPPER_ALLOWANCE", "CREDIT_FUNDING", "VIRTUAL_BANK_ACCOUNT", "SECURITIES_TRANSFER", "ACCOUNT_TRANSFER", "TOPUP", "ISA_TRANSFER" ] } }, "config": { "type": "object", "description": "Configuration of webhook packages collection.", "properties": { "delay": { "type": "string", "pattern": "^([1-9]|[12][0-9]|30)s$", "description": "Maximum time of package collection (1s-30s)." }, "max_package_size": { "type": "integer", "minimum": 100, "maximum": 1048576, "description": "Maximum package size (bytes)" } } } }, "required": [ "id", "created_at", "updated_at", "title", "url", "enabled", "type", "config" ] }, "example": { "id": "a8eb3540-5a84-40f9-b2bb-7f99f282fc5a", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "title": "User webhook", "url": "https://tenant.tld/webhooks/users", "type": [ "USER" ], "enabled": true, "config": { "delay": "5s", "max_package_size": 1024 } } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "delete": { "operationId": "delete_webhook", "summary": "Delete a webhook subscription", "description": "Deletes a webhook subscription specified by its ID.", "tags": [ "Webhook Subscriptions" ], "security": [ { "oauth-client-credentials": [ "webhooks:admin" ] } ], "responses": { "204": { "description": "Request has been processed successfully.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "patch": { "operationId": "update_webhook", "summary": "Update a webhook subscription", "description": "Updates a webhook subscription specified by its ID.", "tags": [ "Webhook Subscriptions" ], "security": [ { "oauth-client-credentials": [ "webhooks:admin" ] } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Update - Request", "type": "object", "properties": { "title": { "type": "string", "pattern": "^[a-zA-Z0-9 ()\\[\\]{}.-]{1,32}$", "description": "Title of the webhook for use on tenant side." }, "url": { "type": "string", "format": "url", "maxLength": 1000, "description": "The callback URL to be called by the webhook." }, "enabled": { "type": "boolean", "description": "Enable/disable webhook." }, "type": { "type": "array", "description": "What kind of events to be sent by the webhook.", "default": [ "ALL" ], "items": { "type": "string", "enum": [ "ALL", "BUSINESS", "ROLE", "USER", "USER_CHECK", "ORDER", "ORDER_CANCELLATION", "EXECUTION", "POSITION", "CASH_BALANCE", "ACCOUNT", "ACCOUNT_GROUP", "INSTRUMENT", "REPORT", "TREASURY_REPORT", "DIRECT_DEBIT", "WITHDRAWAL", "PORTFOLIO", "PORTFOLIO_ALLOCATION", "PORTFOLIO_ORDER", "CORPORATE_ACTION", "ACCOUNT_VALUATION", "INTRADAY_ACCOUNT_VALUATION", "CASH_TRANSACTION", "SECURITY_TRANSACTION", "ACCOUNT_LIQUIDATION", "ACCOUNT_RETURNS", "VIRTUAL_CASH_INCREASE", "VIRTUAL_CASH_DECREASE", "FEE_COLLECTION", "SAVINGS_PLAN", "SAVINGS_PLAN_EXECUTION", "REBALANCING_EXECUTION_ORDER", "TAX_EXEMPTION", "TAX_COLLECTION", "ISA_WRAPPER", "ISA_WRAPPER_ALLOWANCE", "CREDIT_FUNDING", "VIRTUAL_BANK_ACCOUNT", "SECURITIES_TRANSFER", "ACCOUNT_TRANSFER", "TOPUP", "ISA_TRANSFER" ] } }, "exclude_type": { "type": "array", "description": "What kind of events to be excluded if subscription type is: ALL.", "items": { "type": "string", "enum": [ "BUSINESS", "ROLE", "USER", "USER_CHECK", "ORDER", "ORDER_CANCELLATION", "EXECUTION", "POSITION", "CASH_BALANCE", "ACCOUNT", "ACCOUNT_GROUP", "INSTRUMENT", "REPORT", "TREASURY_REPORT", "DIRECT_DEBIT", "WITHDRAWAL", "PORTFOLIO", "PORTFOLIO_ALLOCATION", "PORTFOLIO_ORDER", "CORPORATE_ACTION", "ACCOUNT_VALUATION", "INTRADAY_ACCOUNT_VALUATION", "CASH_TRANSACTION", "SECURITY_TRANSACTION", "ACCOUNT_LIQUIDATION", "ACCOUNT_RETURNS", "VIRTUAL_CASH_INCREASE", "VIRTUAL_CASH_DECREASE", "FEE_COLLECTION", "SAVINGS_PLAN", "SAVINGS_PLAN_EXECUTION", "REBALANCING_EXECUTION_ORDER", "TAX_EXEMPTION", "TAX_COLLECTION", "ISA_WRAPPER", "ISA_WRAPPER_ALLOWANCE", "CREDIT_FUNDING", "VIRTUAL_BANK_ACCOUNT", "SECURITIES_TRANSFER", "ACCOUNT_TRANSFER", "TOPUP", "ISA_TRANSFER" ] } }, "config": { "type": "object", "description": "Configuration of webhook packages collection.", "properties": { "delay": { "type": "string", "pattern": "^([1-9]|[12][0-9]|30)s$", "description": "Maximum time of package collection (1s-30s)." }, "max_package_size": { "type": "integer", "minimum": 100, "maximum": 1048576, "description": "Maximum package size (bytes)" } } } }, "additionalProperties": false }, "example": { "url": "https://tenant.tld/webhooks/users", "type": [ "USER" ] } } } }, "responses": { "200": { "description": "Returns a webhook subscription object if a valid webhook subscription object ID was provided.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Webhook", "type": "object", "additionalProperties": false, "properties": { "id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "title": { "type": "string", "pattern": "^[a-zA-Z0-9 ()\\[\\]{}.-]{1,32}$", "description": "Title of the webhook for use on tenant side." }, "url": { "type": "string", "format": "url", "maxLength": 1000, "description": "The callback URL to be called by the webhook." }, "enabled": { "type": "boolean", "description": "Enable/disable webhook." }, "type": { "type": "array", "description": "What kind of events to be sent by the webhook.", "default": [ "ALL" ], "items": { "type": "string", "enum": [ "ALL", "BUSINESS", "ROLE", "USER", "USER_CHECK", "ORDER", "ORDER_CANCELLATION", "EXECUTION", "POSITION", "CASH_BALANCE", "ACCOUNT", "ACCOUNT_GROUP", "INSTRUMENT", "REPORT", "TREASURY_REPORT", "DIRECT_DEBIT", "WITHDRAWAL", "PORTFOLIO", "PORTFOLIO_ALLOCATION", "PORTFOLIO_ORDER", "CORPORATE_ACTION", "ACCOUNT_VALUATION", "INTRADAY_ACCOUNT_VALUATION", "CASH_TRANSACTION", "SECURITY_TRANSACTION", "ACCOUNT_LIQUIDATION", "ACCOUNT_RETURNS", "VIRTUAL_CASH_INCREASE", "VIRTUAL_CASH_DECREASE", "FEE_COLLECTION", "SAVINGS_PLAN", "SAVINGS_PLAN_EXECUTION", "REBALANCING_EXECUTION_ORDER", "TAX_EXEMPTION", "TAX_COLLECTION", "ISA_WRAPPER", "ISA_WRAPPER_ALLOWANCE", "CREDIT_FUNDING", "VIRTUAL_BANK_ACCOUNT", "SECURITIES_TRANSFER", "ACCOUNT_TRANSFER", "TOPUP", "ISA_TRANSFER" ] } }, "exclude_type": { "type": "array", "description": "What kind of events to be excluded if subscription type is: ALL.", "items": { "type": "string", "enum": [ "BUSINESS", "ROLE", "USER", "USER_CHECK", "ORDER", "ORDER_CANCELLATION", "EXECUTION", "POSITION", "CASH_BALANCE", "ACCOUNT", "ACCOUNT_GROUP", "INSTRUMENT", "REPORT", "TREASURY_REPORT", "DIRECT_DEBIT", "WITHDRAWAL", "PORTFOLIO", "PORTFOLIO_ALLOCATION", "PORTFOLIO_ORDER", "CORPORATE_ACTION", "ACCOUNT_VALUATION", "INTRADAY_ACCOUNT_VALUATION", "CASH_TRANSACTION", "SECURITY_TRANSACTION", "ACCOUNT_LIQUIDATION", "ACCOUNT_RETURNS", "VIRTUAL_CASH_INCREASE", "VIRTUAL_CASH_DECREASE", "FEE_COLLECTION", "SAVINGS_PLAN", "SAVINGS_PLAN_EXECUTION", "REBALANCING_EXECUTION_ORDER", "TAX_EXEMPTION", "TAX_COLLECTION", "ISA_WRAPPER", "ISA_WRAPPER_ALLOWANCE", "CREDIT_FUNDING", "VIRTUAL_BANK_ACCOUNT", "SECURITIES_TRANSFER", "ACCOUNT_TRANSFER", "TOPUP", "ISA_TRANSFER" ] } }, "config": { "type": "object", "description": "Configuration of webhook packages collection.", "properties": { "delay": { "type": "string", "pattern": "^([1-9]|[12][0-9]|30)s$", "description": "Maximum time of package collection (1s-30s)." }, "max_package_size": { "type": "integer", "minimum": 100, "maximum": 1048576, "description": "Maximum package size (bytes)" } } } }, "required": [ "id", "created_at", "updated_at", "title", "url", "enabled", "type", "config" ] }, "example": { "id": "a8eb3540-5a84-40f9-b2bb-7f99f282fc5a", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "title": "User webhook", "url": "https://tenant.tld/webhooks/users", "type": [ "USER" ], "enabled": true, "config": { "delay": "1s", "max_package_size": 51200 } } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/webhooks/{webhook_id}/test": { "parameters": [ { "name": "webhook_id", "in": "path", "description": "The unique identifier of the webhook subscription. Universally Unique Identifier (UUID).", "required": true, "schema": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "post": { "operationId": "test_webhook", "summary": "Test a webhook subscription", "description": "Tests a webhook subscription specified by its ID.", "tags": [ "Webhook Subscriptions" ], "security": [ { "oauth-client-credentials": [ "webhooks:admin" ] } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "response": { "type": "object", "properties": { "status": { "type": "integer" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "body": { "type": "string" }, "error": { "type": "string" } }, "required": [ "status", "headers", "body" ] } }, "required": [ "url", "response" ] }, "example": { "url": "https://api.example.com/test", "response": { "status": 200, "headers": { "Content-Type": "application/json", "X-Request-ID": "abc123" }, "body": "" } } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/users": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_users", "summary": "Get all users", "description": "Returns a paginated list of users.\n\nUse the `offset` and `limit` query parameters to page through results; `meta.total_count` gives the total number of matching users. Use `sort`/`order` to control ordering by `created_at` or `updated_at`.\n\nSee the User onboarding guide ([TOL](https://docs.upvest.co/products/tol/guides/users/users_onboarding_overview) / [BYOL](https://docs.upvest.co/products/byol/guides/users/users_onboarding_overview)) for the user lifecycle.", "tags": [ "Users" ], "security": [ { "oauth-client-credentials": [ "users:read", "users:admin" ] } ], "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "updated_at" ], "default": "created_at" }, "description": "Sort the result by `created_at`, `updated_at`." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Users - List - Response", "type": "object", "description": "Paginated response containing the list of all users.", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "description": "List of the requested users", "oneOf": [ { "anyOf": [ { "title": "Users (BYOL) - List", "type": "array", "minItems": 1, "items": { "title": "User (BYOL)", "type": "object", "description": "A user onboarded under the Bring Your Own Licence (BYOL) operating model, where the client holds the regulatory licence.", "properties": { "id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "first_name": { "type": "string", "maxLength": 100, "minLength": 2, "description": "First name(s) of the user. Please include all first and middle names of the user." }, "last_name": { "type": "string", "maxLength": 100, "minLength": 1, "description": "Last name of the user." }, "salutation": { "type": "string", "description": "Salutation of the user used in reports and statements.\n* (empty string) - \n* SALUTATION_MALE - \n* SALUTATION_FEMALE - \n* SALUTATION_FEMALE_MARRIED - \n* SALUTATION_DIVERSE - ", "enum": [ "", "SALUTATION_MALE", "SALUTATION_FEMALE", "SALUTATION_FEMALE_MARRIED", "SALUTATION_DIVERSE" ], "default": "" }, "title": { "type": "string", "description": "Title of the user used in reports and statements.\n* (empty string) - \n* DR - Doctor\n* PROF - Professor\n* PROF_DR - \n* DIPL_ING - Graduate engineer (Diplom-Ingenieur)\n* MAGISTER - ", "enum": [ "", "DR", "PROF", "PROF_DR", "DIPL_ING", "MAGISTER" ], "default": "" }, "birth_date": { "type": "string", "format": "date", "description": "Birth date of the user in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" }, "birth_city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 }, "birth_country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "birth_name": { "type": "string", "maxLength": 100, "description": "If applicable, birth name of the user." }, "decease_date": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "date", "description": "The user's date of death in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" } ] }, "nationalities": { "type": "array", "items": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "minItems": 1, "description": "Nationalities of the user. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)." }, "address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, "postal_address": { "description": "User postal address. Needs to be specified if different to the residential address, otherwise it is automatically populated.", "oneOf": [ { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, { "type": "null" } ] }, "status": { "type": "string", "description": "Status of the user.\n* ACTIVE - \n* INACTIVE - \n* OFFBOARDING - \n* OFFBOARDED - ", "enum": [ "ACTIVE", "INACTIVE", "OFFBOARDING", "OFFBOARDED" ] }, "email": { "type": "string", "format": "email", "maxLength": 100, "description": "Email of the user. Must be a valid email address." }, "branch_id": { "title": "Branch unique identifier.", "type": "string", "description": "Unique identifier of the market the user is onboarded on. Only relevant if the client is operating in different markets and the client is configured accordingly", "format": "uuid" }, "gender": { "title": "Gender", "type": "string", "description": "Gender of the user. Required for users applying for the German pension government bonus.\n* (empty string) - \n* MALE - \n* FEMALE - \n* DIVERSE - ", "enum": [ "", "MALE", "FEMALE", "DIVERSE" ], "default": "" }, "social_security_number": { "title": "Social security number", "type": "string", "description": "The user's assigned social security number (German social insurance number, e.g. `25300972S014`). Required for users applying for the German pension government bonus.", "pattern": "^(\\d{2}(0[1-9]|[12]\\d|3[01])(0[1-9]|1[0-2])\\d{2}[A-Z]\\d{3})?$" }, "tags": { "title": "Tags", "type": "array", "items": { "type": "string", "enum": [ "CLIENT_EMPLOYEE" ] }, "uniqueItems": true, "description": "Labels applied to the user by the tenant. Omitted for users that have no tags.\n* CLIENT_EMPLOYEE - The user is an employee of the tenant.\n\nProviding this field in a data change request replaces the full set of tags; send an empty array to remove all tags." } }, "required": [ "id", "created_at", "updated_at", "first_name", "last_name", "birth_date", "nationalities", "address", "status" ], "additionalProperties": false } }, { "title": "Users (TOL) - List", "type": "array", "minItems": 1, "items": { "title": "User (TOL)", "type": "object", "description": "A user onboarded under the Take Our Licence (TOL) operating model, where Upvest holds the regulatory licence. Includes the details collected during onboarding.", "properties": { "id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "first_name": { "type": "string", "maxLength": 100, "minLength": 2, "description": "First name(s) of the user. Please include all first and middle names of the user." }, "last_name": { "type": "string", "maxLength": 100, "minLength": 1, "description": "Last name of the user." }, "salutation": { "type": "string", "description": "Salutation of the user used in reports and statements.\n* (empty string) - \n* SALUTATION_MALE - \n* SALUTATION_FEMALE - \n* SALUTATION_FEMALE_MARRIED - \n* SALUTATION_DIVERSE - ", "enum": [ "", "SALUTATION_MALE", "SALUTATION_FEMALE", "SALUTATION_FEMALE_MARRIED", "SALUTATION_DIVERSE" ], "default": "" }, "title": { "type": "string", "description": "Title of the user used in reports and statements.\n* (empty string) - \n* DR - Doctor\n* PROF - Professor\n* PROF_DR - \n* DIPL_ING - Graduate engineer (Diplom-Ingenieur)\n* MAGISTER - ", "enum": [ "", "DR", "PROF", "PROF_DR", "DIPL_ING", "MAGISTER" ], "default": "" }, "birth_date": { "type": "string", "format": "date", "description": "Birth date of the user in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" }, "birth_city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 }, "birth_country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "birth_name": { "type": "string", "maxLength": 100, "description": "If applicable, birth name of the user." }, "decease_date": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "date", "description": "The user's date of death in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" } ] }, "nationalities": { "type": "array", "items": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "minItems": 1, "description": "Nationalities of the user. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)." }, "address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, "postal_address": { "description": "User postal address. Needs to be specified if different to the residential address, otherwise it is automatically populated.", "oneOf": [ { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, { "type": "null" } ] }, "status": { "type": "string", "description": "Status of the user.\n* ACTIVE - \n* INACTIVE - \n* OFFBOARDING - \n* OFFBOARDED - ", "enum": [ "ACTIVE", "INACTIVE", "OFFBOARDING", "OFFBOARDED" ] }, "email": { "type": "string", "format": "email", "maxLength": 100, "description": "Email of the user. Must be a valid email address." }, "phone_number": { "type": "string", "pattern": "^([0-9]{8,15})?$", "description": "Phone number of the user. [Phone number E.164 format](https://en.wikipedia.org/wiki/E.164)." }, "fatca": { "type": "object", "description": "The user's FATCA status and when it was confirmed", "properties": { "status": { "type": "boolean", "description": "The user’s FATCA status is true if the user is subject to paying taxes in the US, otherwise it can be set to false." }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp at which the user confirmed their FATCA status. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" } }, "required": [ "status", "confirmed_at" ] }, "terms_and_conditions": { "description": "Terms & Conditions will be needed for all users unless they are a child user or only a user on a business.", "type": "object", "properties": { "consent_document_id": { "title": "Consent unique identifier.", "type": "string", "description": "Consent unique identifier.", "format": "uuid" }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp at which the user consented to the terms & conditions. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" } }, "required": [ "consent_document_id", "confirmed_at" ] }, "data_privacy_and_sharing_agreement": { "description": "Data privacy agreement will be needed for all users unless they are a child user or only a user on a business.", "type": "object", "properties": { "consent_document_id": { "title": "Consent unique identifier.", "type": "string", "description": "Consent unique identifier.", "format": "uuid" }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp at which the user consented to the data sharing agreement. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" } }, "required": [ "consent_document_id", "confirmed_at" ] }, "branch_id": { "title": "Branch unique identifier.", "type": "string", "description": "Unique identifier of the market the user is onboarded on. Only relevant if the client is operating in different markets and the client is configured accordingly", "format": "uuid" }, "gender": { "title": "Gender", "type": "string", "description": "Gender of the user. Required for users applying for the German pension government bonus.\n* (empty string) - \n* MALE - \n* FEMALE - \n* DIVERSE - ", "enum": [ "", "MALE", "FEMALE", "DIVERSE" ], "default": "" }, "social_security_number": { "title": "Social security number", "type": "string", "description": "The user's assigned social security number (German social insurance number, e.g. `25300972S014`). Required for users applying for the German pension government bonus.", "pattern": "^(\\d{2}(0[1-9]|[12]\\d|3[01])(0[1-9]|1[0-2])\\d{2}[A-Z]\\d{3})?$" }, "tags": { "title": "Tags", "type": "array", "items": { "type": "string", "enum": [ "CLIENT_EMPLOYEE" ] }, "uniqueItems": true, "description": "Labels applied to the user by the tenant. Omitted for users that have no tags.\n* CLIENT_EMPLOYEE - The user is an employee of the tenant.\n\nProviding this field in a data change request replaces the full set of tags; send an empty array to remove all tags." } }, "required": [ "id", "created_at", "updated_at", "first_name", "last_name", "birth_date", "nationalities", "address", "status" ], "additionalProperties": false } } ] }, { "title": "empty Users - List", "description": "For empty lists, JSON schema's 'oneOf' matches both 'Users (BYOL) - List' *and* 'Users (TOL) - List' and hence fails. So we need this extra 'oneOf' branch specifically for empty lists, distinguished by 'minItems' and 'maxItems'.", "type": "array", "maxItems": 0, "items": { "description": "All items on list responses must be objects.", "type": "object", "properties": {} } } ] } }, "required": [ "meta", "data" ], "additionalProperties": false }, "examples": { "BYOL": { "summary": "BYOL users", "value": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1, "sort": "created_at", "order": "ASC" }, "data": [ { "id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be202", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "first_name": "Karl", "last_name": "Schmidt", "email": "karl.schmidt@example.com", "salutation": "SALUTATION_MALE", "title": "DR", "birth_date": "1972-09-30", "birth_city": "Berlin", "birth_country": "DE", "birth_name": "Schmidt", "decease_date": null, "nationalities": [ "DE", "AU" ], "postal_address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "status": "ACTIVE" }, { "id": "287673ef-1bae-4d8a-9e78-8ddaae249d72", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "salutation": "SALUTATION_MALE", "title": "PROF_DR", "birth_date": "1970-10-01", "birth_city": "Berlin", "birth_country": "DE", "birth_name": "Schmidt", "nationalities": [ "DE", "AU" ], "decease_date": "2026-02-27", "postal_address": null, "address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "status": "ACTIVE" } ] } }, "BYOL With Branch ID": { "summary": "BYOL users with branch ID", "value": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1, "sort": "created_at", "order": "ASC" }, "data": [ { "id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be202", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "first_name": "Karl", "last_name": "Schmidt", "salutation": "SALUTATION_MALE", "title": "DR", "birth_date": "1972-09-30", "birth_city": "Berlin", "birth_country": "DE", "birth_name": "Schmidt", "decease_date": null, "nationalities": [ "DE", "AU" ], "postal_address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "status": "ACTIVE", "branch_id": "e6373bfa-ff12-4004-8de9-747ac96764da" }, { "id": "287673ef-1bae-4d8a-9e78-8ddaae249d72", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "first_name": "John", "last_name": "Doe", "salutation": "SALUTATION_MALE", "title": "PROF_DR", "birth_date": "1970-10-01", "birth_city": "Berlin", "birth_country": "DE", "birth_name": "Schmidt", "decease_date": null, "nationalities": [ "DE", "AU" ], "postal_address": null, "address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "status": "ACTIVE", "branch_id": "e6373bfa-ff12-4004-8de9-747ac96764da" } ] } }, "TOL": { "summary": "TOL users", "value": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1, "sort": "created_at", "order": "ASC" }, "data": [ { "id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be202", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "first_name": "Karl", "last_name": "Schmidt", "email": "karl.schmidt@example.com", "salutation": "SALUTATION_MALE", "title": "DR", "birth_date": "1972-09-30", "birth_city": "Berlin", "birth_country": "DE", "birth_name": "Schmidt", "decease_date": null, "nationalities": [ "DE", "AU" ], "phone_number": "4930901820", "postal_address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "fatca": { "status": false, "confirmed_at": "2020-08-24T14:15:22Z" }, "terms_and_conditions": { "consent_document_id": "d0b83880-3809-4eee-b0df-ca50db84c15a", "confirmed_at": "2020-08-24T14:14:22Z" }, "data_privacy_and_sharing_agreement": { "consent_document_id": "7ab0fc5c-8157-4acd-b02d-6ccda0e81dec", "confirmed_at": "2020-08-24T14:16:22Z" }, "status": "ACTIVE" }, { "id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be202", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "first_name": "Karl", "last_name": "Schmidt", "email": "karl.schmidt@example.com", "salutation": "SALUTATION_MALE", "title": "DR", "birth_date": "1972-09-30", "birth_city": "Berlin", "birth_country": "DE", "birth_name": "Schmidt", "nationalities": [ "DE", "AU" ], "phone_number": "4930901820", "decease_date": "2026-02-27", "postal_address": null, "address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "fatca": { "status": false, "confirmed_at": "2020-08-24T14:15:22Z" }, "terms_and_conditions": { "consent_document_id": "a8a87268-4f3c-4de2-abb9-a553a3bb7608", "confirmed_at": "2020-08-24T14:14:22Z" }, "data_privacy_and_sharing_agreement": { "consent_document_id": "fb1827c3-2b29-47e1-84da-996d09517edc", "confirmed_at": "2020-08-24T14:16:22Z" }, "status": "ACTIVE" } ] } }, "TOL With Branch ID": { "summary": "TOL users with branch ID", "value": { "meta": { "offset": 0, "limit": 100, "count": 2, "total_count": 2, "sort": "created_at", "order": "ASC" }, "data": [ { "id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be202", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "first_name": "Karl", "last_name": "Schmidt", "email": "karl.schmidt@example.com", "salutation": "SALUTATION_MALE", "title": "DR", "birth_date": "1972-09-30", "birth_city": "Berlin", "birth_country": "DE", "birth_name": "Schmidt", "decease_date": null, "nationalities": [ "DE", "AU" ], "phone_number": "4930901820", "postal_address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "fatca": { "status": false, "confirmed_at": "2020-08-24T14:15:22Z" }, "terms_and_conditions": { "consent_document_id": "d0b83880-3809-4eee-b0df-ca50db84c15a", "confirmed_at": "2020-08-24T14:14:22Z" }, "data_privacy_and_sharing_agreement": { "consent_document_id": "7ab0fc5c-8157-4acd-b02d-6ccda0e81dec", "confirmed_at": "2020-08-24T14:16:22Z" }, "status": "ACTIVE", "branch_id": "e6373bfa-ff12-4004-8de9-747ac96764da" }, { "id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be202", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "first_name": "Karl", "last_name": "Schmidt", "email": "karl.schmidt@example.com", "salutation": "SALUTATION_MALE", "title": "DR", "birth_date": "1972-09-30", "birth_city": "Berlin", "birth_country": "DE", "birth_name": "Schmidt", "decease_date": null, "nationalities": [ "DE", "AU" ], "phone_number": "4930901820", "postal_address": null, "address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "fatca": { "status": false, "confirmed_at": "2020-08-24T14:15:22Z" }, "terms_and_conditions": { "consent_document_id": "a8a87268-4f3c-4de2-abb9-a553a3bb7608", "confirmed_at": "2020-08-24T14:14:22Z" }, "data_privacy_and_sharing_agreement": { "consent_document_id": "fb1827c3-2b29-47e1-84da-996d09517edc", "confirmed_at": "2020-08-24T14:16:22Z" }, "status": "ACTIVE", "branch_id": "e6373bfa-ff12-4004-8de9-747ac96764da" } ] } }, "empty": { "summary": "Empty users list", "value": { "meta": { "offset": 0, "limit": 100, "count": 0, "total_count": 0, "sort": "created_at", "order": "ASC" }, "data": [] } } } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "post": { "operationId": "create_user", "summary": "Create a user", "description": "Creates a user.\n\nThe user must complete identity checks and provide any required identifiers before activation.\n\nSee the Creating a user guide ([TOL](https://docs.upvest.co/products/tol/guides/users/users_onboarding_create) / [BYOL](https://docs.upvest.co/products/byol/guides/users/users_onboarding_create)) for the full onboarding flow.", "tags": [ "Users" ], "security": [ { "oauth-client-credentials": [ "users:admin" ] } ], "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$", "example": "ccb07f42-4104-44ad-8e1f-c660bb7b269c" }, "description": "A UUID to be used as an idempotency key. This prevents a duplicate request from being replayed.\nhttps://docs.upvest.co/documentation/concepts/api_concepts/idempotency\n" } ], "requestBody": { "content": { "application/json": { "schema": { "title": "User - Create - Request", "description": "Request payload for creating a user. The required fields depend on the operating model (TOL or BYOL).", "anyOf": [ { "title": "User (BYOL) - Create - Request", "type": "object", "description": "Request payload for creating a user.", "properties": { "first_name": { "type": "string", "maxLength": 100, "minLength": 2, "description": "First name(s) of the user. Please include all first and middle names of the user." }, "last_name": { "type": "string", "maxLength": 100, "minLength": 1, "description": "Last name of the user." }, "email": { "type": "string", "format": "email", "maxLength": 100, "description": "Email of the user. Must be a valid email address." }, "salutation": { "type": "string", "description": "Salutation of the user used in reports and statements.\n* (empty string) - \n* SALUTATION_MALE - \n* SALUTATION_FEMALE - \n* SALUTATION_FEMALE_MARRIED - \n* SALUTATION_DIVERSE - ", "enum": [ "", "SALUTATION_MALE", "SALUTATION_FEMALE", "SALUTATION_FEMALE_MARRIED", "SALUTATION_DIVERSE" ], "default": "" }, "title": { "type": "string", "description": "Title of the user used in reports and statements.\n* (empty string) - \n* DR - Doctor\n* PROF - Professor\n* PROF_DR - \n* DIPL_ING - Graduate engineer (Diplom-Ingenieur)\n* MAGISTER - ", "enum": [ "", "DR", "PROF", "PROF_DR", "DIPL_ING", "MAGISTER" ], "default": "" }, "birth_date": { "type": "string", "format": "date", "description": "Birth date of the user in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" }, "birth_city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 }, "birth_country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "birth_name": { "type": "string", "maxLength": 100, "description": "If applicable, birth name of the user." }, "nationalities": { "type": "array", "items": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "minItems": 1, "description": "Nationalities of the user. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)." }, "address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, "postal_address": { "description": "User postal address. Needs to be specified if different to the residential address, otherwise it is automatically populated.", "oneOf": [ { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, { "type": "null" } ] }, "branch_id": { "title": "Branch unique identifier.", "type": "string", "description": "Unique identifier of the market the user is onboarded on. Only relevant if the client is operating in different markets and the client is configured accordingly", "format": "uuid" }, "gender": { "title": "Gender", "type": "string", "description": "Gender of the user. Required for users applying for the German pension government bonus.\n* (empty string) - \n* MALE - \n* FEMALE - \n* DIVERSE - ", "enum": [ "", "MALE", "FEMALE", "DIVERSE" ], "default": "" }, "social_security_number": { "title": "Social security number", "type": "string", "description": "The user's assigned social security number (German social insurance number, e.g. `25300972S014`). Required for users applying for the German pension government bonus.", "pattern": "^(\\d{2}(0[1-9]|[12]\\d|3[01])(0[1-9]|1[0-2])\\d{2}[A-Z]\\d{3})?$" }, "tags": { "title": "Tags", "type": "array", "items": { "type": "string", "enum": [ "CLIENT_EMPLOYEE" ] }, "uniqueItems": true, "description": "Labels applied to the user by the tenant. Omitted for users that have no tags.\n* CLIENT_EMPLOYEE - The user is an employee of the tenant.\n\nProviding this field in a data change request replaces the full set of tags; send an empty array to remove all tags." } }, "required": [ "first_name", "last_name", "birth_date", "nationalities", "address" ], "additionalProperties": false }, { "title": "User (TOL) - Create - Request", "type": "object", "description": "Request payload for creating a TOL user, including personal details and the consents collected during onboarding.", "properties": { "first_name": { "type": "string", "maxLength": 100, "minLength": 2, "description": "First name(s) of the user. Please include all first and middle names of the user." }, "last_name": { "type": "string", "maxLength": 100, "minLength": 1, "description": "Last name of the user." }, "email": { "type": "string", "format": "email", "maxLength": 100, "description": "Email of the user. Must be a valid email address." }, "salutation": { "type": "string", "description": "Salutation of the user used in reports and statements.\n* (empty string) - \n* SALUTATION_MALE - \n* SALUTATION_FEMALE - \n* SALUTATION_FEMALE_MARRIED - \n* SALUTATION_DIVERSE - ", "enum": [ "", "SALUTATION_MALE", "SALUTATION_FEMALE", "SALUTATION_FEMALE_MARRIED", "SALUTATION_DIVERSE" ], "default": "" }, "title": { "type": "string", "description": "Title of the user used in reports and statements.\n* (empty string) - \n* DR - Doctor\n* PROF - Professor\n* PROF_DR - \n* DIPL_ING - Graduate engineer (Diplom-Ingenieur)\n* MAGISTER - ", "enum": [ "", "DR", "PROF", "PROF_DR", "DIPL_ING", "MAGISTER" ], "default": "" }, "birth_date": { "type": "string", "format": "date", "description": "Birth date of the user in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" }, "birth_city": { "allOf": [ { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 }, { "description": "This field is required except for users of UK TOL" } ] }, "birth_country": { "allOf": [ { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).\n\nThis field is required except for users of UK TOL" } ] }, "birth_name": { "type": "string", "maxLength": 100, "description": "If applicable, birth name of the user." }, "nationalities": { "type": "array", "items": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "minItems": 1, "description": "Nationalities of the user. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)." }, "phone_number": { "type": "string", "pattern": "^([0-9]{8,15})?$", "description": "Phone number of the user. [Phone number E.164 format](https://en.wikipedia.org/wiki/E.164)." }, "address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, "postal_address": { "description": "User postal address. Needs to be specified if different to the residential address, otherwise it is automatically populated.", "oneOf": [ { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, { "type": "null" } ] }, "fatca": { "type": "object", "description": "The user's FATCA status and when it was confirmed", "properties": { "status": { "type": "boolean", "description": "The user’s FATCA status is true if the user is subject to paying taxes in the US, otherwise it can be set to false." }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp at which the user confirmed their FATCA status. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" } }, "required": [ "status", "confirmed_at" ] }, "terms_and_conditions": { "description": "Terms & Conditions will be needed for all users unless they are a child user or only a user on a business.", "type": "object", "properties": { "consent_document_id": { "title": "Consent unique identifier.", "type": "string", "description": "Consent unique identifier.", "format": "uuid" }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp at which the user consented to the terms & conditions. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" } }, "required": [ "consent_document_id", "confirmed_at" ] }, "data_privacy_and_sharing_agreement": { "description": "Data privacy agreement will be needed for all users unless they are a child user or only a user on a business.", "type": "object", "properties": { "consent_document_id": { "title": "Consent unique identifier.", "type": "string", "description": "Consent unique identifier.", "format": "uuid" }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp at which the user consented to the data sharing agreement. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" } }, "required": [ "consent_document_id", "confirmed_at" ] }, "branch_id": { "title": "Branch unique identifier.", "type": "string", "description": "Unique identifier of the market the user is onboarded on. Only relevant if the client is operating in different markets and the client is configured accordingly", "format": "uuid" }, "gender": { "title": "Gender", "type": "string", "description": "Gender of the user. Required for users applying for the German pension government bonus.\n* (empty string) - \n* MALE - \n* FEMALE - \n* DIVERSE - ", "enum": [ "", "MALE", "FEMALE", "DIVERSE" ], "default": "" }, "social_security_number": { "title": "Social security number", "type": "string", "description": "The user's assigned social security number (German social insurance number, e.g. `25300972S014`). Required for users applying for the German pension government bonus.", "pattern": "^(\\d{2}(0[1-9]|[12]\\d|3[01])(0[1-9]|1[0-2])\\d{2}[A-Z]\\d{3})?$" }, "tags": { "title": "Tags", "type": "array", "items": { "type": "string", "enum": [ "CLIENT_EMPLOYEE" ] }, "uniqueItems": true, "description": "Labels applied to the user by the tenant. Omitted for users that have no tags.\n* CLIENT_EMPLOYEE - The user is an employee of the tenant.\n\nProviding this field in a data change request replaces the full set of tags; send an empty array to remove all tags." } }, "required": [ "first_name", "last_name", "email", "birth_date", "nationalities", "address", "fatca" ], "additionalProperties": false } ] }, "examples": { "BYOL": { "summary": "BYOL user", "value": { "first_name": "Karl", "last_name": "Schmidt", "email": "karl.schmidt@example.com", "salutation": "SALUTATION_MALE", "title": "DR", "birth_date": "1972-09-30", "birth_city": "Berlin", "birth_country": "DE", "birth_name": "Schmidt", "nationalities": [ "DE", "AU" ], "postal_address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "tags": [ "CLIENT_EMPLOYEE" ] } }, "BYOL User with Branch ID": { "summary": "BYOL User with branch ID", "value": { "first_name": "Karl", "last_name": "Schmidt", "salutation": "SALUTATION_MALE", "title": "DR", "birth_date": "1972-09-30", "birth_city": "Berlin", "birth_country": "DE", "birth_name": "Schmidt", "nationalities": [ "DE", "AU" ], "postal_address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "branch_id": "e6373bfa-ff12-4004-8de9-747ac96764da" } }, "TOL": { "summary": "TOL user", "value": { "first_name": "Karl", "last_name": "Schmidt", "email": "karl.schmidt@example.com", "salutation": "SALUTATION_MALE", "title": "DR", "birth_date": "1972-09-30", "birth_city": "Berlin", "birth_country": "DE", "birth_name": "Schmidt", "nationalities": [ "DE", "AU" ], "phone_number": "4930901820", "postal_address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "fatca": { "status": false, "confirmed_at": "2020-08-24T14:15:22Z" }, "terms_and_conditions": { "consent_document_id": "d0b83880-3809-4eee-b0df-ca50db84c15a", "confirmed_at": "2020-08-24T14:14:22Z" }, "data_privacy_and_sharing_agreement": { "consent_document_id": "7ab0fc5c-8157-4acd-b02d-6ccda0e81dec", "confirmed_at": "2020-08-24T14:16:22Z" }, "tags": [ "CLIENT_EMPLOYEE" ] } }, "TOL User with Branch ID": { "summary": "TOL User with Branch ID", "value": { "first_name": "Karl", "last_name": "Schmidt", "email": "karl.schmidt@example.com", "salutation": "SALUTATION_MALE", "title": "DR", "birth_date": "1972-09-30", "birth_city": "Berlin", "birth_country": "DE", "birth_name": "Schmidt", "nationalities": [ "DE", "AU" ], "phone_number": "4930901820", "postal_address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "fatca": { "status": false, "confirmed_at": "2020-08-24T14:15:22Z" }, "terms_and_conditions": { "consent_document_id": "d0b83880-3809-4eee-b0df-ca50db84c15a", "confirmed_at": "2020-08-24T14:14:22Z" }, "data_privacy_and_sharing_agreement": { "consent_document_id": "7ab0fc5c-8157-4acd-b02d-6ccda0e81dec", "confirmed_at": "2020-08-24T14:16:22Z" }, "branch_id": "e6373bfa-ff12-4004-8de9-747ac96764da" } }, "TOL User without Consents": { "summary": "TOL user without consents", "value": { "first_name": "Karl", "last_name": "Schmidt", "email": "karl.schmidt@example.com", "salutation": "SALUTATION_MALE", "title": "DR", "birth_date": "1972-09-30", "birth_city": "Berlin", "birth_country": "DE", "birth_name": "Schmidt", "nationalities": [ "DE", "AU" ], "phone_number": "4930901820", "postal_address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "fatca": { "status": false, "confirmed_at": "2020-08-24T14:15:22Z" } } } } } } }, "responses": { "200": { "description": "User created.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "User - Create - Request", "description": "The details of the created user.", "anyOf": [ { "title": "User (BYOL)", "type": "object", "description": "A user onboarded under the Bring Your Own Licence (BYOL) operating model, where the client holds the regulatory licence.", "properties": { "id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "first_name": { "type": "string", "maxLength": 100, "minLength": 2, "description": "First name(s) of the user. Please include all first and middle names of the user." }, "last_name": { "type": "string", "maxLength": 100, "minLength": 1, "description": "Last name of the user." }, "salutation": { "type": "string", "description": "Salutation of the user used in reports and statements.\n* (empty string) - \n* SALUTATION_MALE - \n* SALUTATION_FEMALE - \n* SALUTATION_FEMALE_MARRIED - \n* SALUTATION_DIVERSE - ", "enum": [ "", "SALUTATION_MALE", "SALUTATION_FEMALE", "SALUTATION_FEMALE_MARRIED", "SALUTATION_DIVERSE" ], "default": "" }, "title": { "type": "string", "description": "Title of the user used in reports and statements.\n* (empty string) - \n* DR - Doctor\n* PROF - Professor\n* PROF_DR - \n* DIPL_ING - Graduate engineer (Diplom-Ingenieur)\n* MAGISTER - ", "enum": [ "", "DR", "PROF", "PROF_DR", "DIPL_ING", "MAGISTER" ], "default": "" }, "birth_date": { "type": "string", "format": "date", "description": "Birth date of the user in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" }, "birth_city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 }, "birth_country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "birth_name": { "type": "string", "maxLength": 100, "description": "If applicable, birth name of the user." }, "decease_date": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "date", "description": "The user's date of death in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" } ] }, "nationalities": { "type": "array", "items": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "minItems": 1, "description": "Nationalities of the user. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)." }, "address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, "postal_address": { "description": "User postal address. Needs to be specified if different to the residential address, otherwise it is automatically populated.", "oneOf": [ { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, { "type": "null" } ] }, "status": { "type": "string", "description": "Status of the user.\n* ACTIVE - \n* INACTIVE - \n* OFFBOARDING - \n* OFFBOARDED - ", "enum": [ "ACTIVE", "INACTIVE", "OFFBOARDING", "OFFBOARDED" ] }, "email": { "type": "string", "format": "email", "maxLength": 100, "description": "Email of the user. Must be a valid email address." }, "branch_id": { "title": "Branch unique identifier.", "type": "string", "description": "Unique identifier of the market the user is onboarded on. Only relevant if the client is operating in different markets and the client is configured accordingly", "format": "uuid" }, "gender": { "title": "Gender", "type": "string", "description": "Gender of the user. Required for users applying for the German pension government bonus.\n* (empty string) - \n* MALE - \n* FEMALE - \n* DIVERSE - ", "enum": [ "", "MALE", "FEMALE", "DIVERSE" ], "default": "" }, "social_security_number": { "title": "Social security number", "type": "string", "description": "The user's assigned social security number (German social insurance number, e.g. `25300972S014`). Required for users applying for the German pension government bonus.", "pattern": "^(\\d{2}(0[1-9]|[12]\\d|3[01])(0[1-9]|1[0-2])\\d{2}[A-Z]\\d{3})?$" }, "tags": { "title": "Tags", "type": "array", "items": { "type": "string", "enum": [ "CLIENT_EMPLOYEE" ] }, "uniqueItems": true, "description": "Labels applied to the user by the tenant. Omitted for users that have no tags.\n* CLIENT_EMPLOYEE - The user is an employee of the tenant.\n\nProviding this field in a data change request replaces the full set of tags; send an empty array to remove all tags." } }, "required": [ "id", "created_at", "updated_at", "first_name", "last_name", "birth_date", "nationalities", "address", "status" ], "additionalProperties": false }, { "title": "User (TOL)", "type": "object", "description": "A user onboarded under the Take Our Licence (TOL) operating model, where Upvest holds the regulatory licence. Includes the details collected during onboarding.", "properties": { "id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "first_name": { "type": "string", "maxLength": 100, "minLength": 2, "description": "First name(s) of the user. Please include all first and middle names of the user." }, "last_name": { "type": "string", "maxLength": 100, "minLength": 1, "description": "Last name of the user." }, "salutation": { "type": "string", "description": "Salutation of the user used in reports and statements.\n* (empty string) - \n* SALUTATION_MALE - \n* SALUTATION_FEMALE - \n* SALUTATION_FEMALE_MARRIED - \n* SALUTATION_DIVERSE - ", "enum": [ "", "SALUTATION_MALE", "SALUTATION_FEMALE", "SALUTATION_FEMALE_MARRIED", "SALUTATION_DIVERSE" ], "default": "" }, "title": { "type": "string", "description": "Title of the user used in reports and statements.\n* (empty string) - \n* DR - Doctor\n* PROF - Professor\n* PROF_DR - \n* DIPL_ING - Graduate engineer (Diplom-Ingenieur)\n* MAGISTER - ", "enum": [ "", "DR", "PROF", "PROF_DR", "DIPL_ING", "MAGISTER" ], "default": "" }, "birth_date": { "type": "string", "format": "date", "description": "Birth date of the user in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" }, "birth_city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 }, "birth_country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "birth_name": { "type": "string", "maxLength": 100, "description": "If applicable, birth name of the user." }, "decease_date": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "date", "description": "The user's date of death in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" } ] }, "nationalities": { "type": "array", "items": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "minItems": 1, "description": "Nationalities of the user. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)." }, "address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, "postal_address": { "description": "User postal address. Needs to be specified if different to the residential address, otherwise it is automatically populated.", "oneOf": [ { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, { "type": "null" } ] }, "status": { "type": "string", "description": "Status of the user.\n* ACTIVE - \n* INACTIVE - \n* OFFBOARDING - \n* OFFBOARDED - ", "enum": [ "ACTIVE", "INACTIVE", "OFFBOARDING", "OFFBOARDED" ] }, "email": { "type": "string", "format": "email", "maxLength": 100, "description": "Email of the user. Must be a valid email address." }, "phone_number": { "type": "string", "pattern": "^([0-9]{8,15})?$", "description": "Phone number of the user. [Phone number E.164 format](https://en.wikipedia.org/wiki/E.164)." }, "fatca": { "type": "object", "description": "The user's FATCA status and when it was confirmed", "properties": { "status": { "type": "boolean", "description": "The user’s FATCA status is true if the user is subject to paying taxes in the US, otherwise it can be set to false." }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp at which the user confirmed their FATCA status. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" } }, "required": [ "status", "confirmed_at" ] }, "terms_and_conditions": { "description": "Terms & Conditions will be needed for all users unless they are a child user or only a user on a business.", "type": "object", "properties": { "consent_document_id": { "title": "Consent unique identifier.", "type": "string", "description": "Consent unique identifier.", "format": "uuid" }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp at which the user consented to the terms & conditions. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" } }, "required": [ "consent_document_id", "confirmed_at" ] }, "data_privacy_and_sharing_agreement": { "description": "Data privacy agreement will be needed for all users unless they are a child user or only a user on a business.", "type": "object", "properties": { "consent_document_id": { "title": "Consent unique identifier.", "type": "string", "description": "Consent unique identifier.", "format": "uuid" }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp at which the user consented to the data sharing agreement. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" } }, "required": [ "consent_document_id", "confirmed_at" ] }, "branch_id": { "title": "Branch unique identifier.", "type": "string", "description": "Unique identifier of the market the user is onboarded on. Only relevant if the client is operating in different markets and the client is configured accordingly", "format": "uuid" }, "gender": { "title": "Gender", "type": "string", "description": "Gender of the user. Required for users applying for the German pension government bonus.\n* (empty string) - \n* MALE - \n* FEMALE - \n* DIVERSE - ", "enum": [ "", "MALE", "FEMALE", "DIVERSE" ], "default": "" }, "social_security_number": { "title": "Social security number", "type": "string", "description": "The user's assigned social security number (German social insurance number, e.g. `25300972S014`). Required for users applying for the German pension government bonus.", "pattern": "^(\\d{2}(0[1-9]|[12]\\d|3[01])(0[1-9]|1[0-2])\\d{2}[A-Z]\\d{3})?$" }, "tags": { "title": "Tags", "type": "array", "items": { "type": "string", "enum": [ "CLIENT_EMPLOYEE" ] }, "uniqueItems": true, "description": "Labels applied to the user by the tenant. Omitted for users that have no tags.\n* CLIENT_EMPLOYEE - The user is an employee of the tenant.\n\nProviding this field in a data change request replaces the full set of tags; send an empty array to remove all tags." } }, "required": [ "id", "created_at", "updated_at", "first_name", "last_name", "birth_date", "nationalities", "address", "status" ], "additionalProperties": false } ] }, "examples": { "BYOL": { "summary": "BYOL User", "value": { "id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be202", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "first_name": "Karl", "last_name": "Schmidt", "email": "karl.schmidt@example.com", "salutation": "SALUTATION_MALE", "title": "DR", "birth_date": "1972-09-30", "birth_city": "Berlin", "birth_country": "DE", "birth_name": "Schmidt", "decease_date": null, "nationalities": [ "DE", "AU" ], "postal_address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "status": "ACTIVE" } }, "BYOL with Branch ID": { "summary": "BYOL User with Branch ID", "value": { "id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be202", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "first_name": "Karl", "last_name": "Schmidt", "salutation": "SALUTATION_MALE", "title": "DR", "birth_date": "1972-09-30", "birth_city": "Berlin", "birth_country": "DE", "birth_name": "Schmidt", "decease_date": null, "nationalities": [ "DE", "AU" ], "postal_address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "status": "ACTIVE", "branch_id": "e6373bfa-ff12-4004-8de9-747ac96764da" } }, "TOL": { "summary": "TOL User", "value": { "id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be202", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "first_name": "Karl", "last_name": "Schmidt", "email": "karl.schmidt@example.com", "salutation": "SALUTATION_MALE", "title": "DR", "birth_date": "1972-09-30", "birth_city": "Berlin", "birth_country": "DE", "birth_name": "Schmidt", "decease_date": null, "nationalities": [ "DE", "AU" ], "phone_number": "4930901820", "postal_address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "fatca": { "status": false, "confirmed_at": "2020-08-24T14:15:22Z" }, "terms_and_conditions": { "consent_document_id": "d0b83880-3809-4eee-b0df-ca50db84c15a", "confirmed_at": "2020-08-24T14:14:22Z" }, "data_privacy_and_sharing_agreement": { "consent_document_id": "7ab0fc5c-8157-4acd-b02d-6ccda0e81dec", "confirmed_at": "2020-08-24T14:16:22Z" }, "status": "ACTIVE" } }, "TOL With Branch ID": { "summary": "TOL User with Branch ID", "value": { "id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be202", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "first_name": "Karl", "last_name": "Schmidt", "email": "karl.schmidt@example.com", "salutation": "SALUTATION_MALE", "title": "DR", "birth_date": "1972-09-30", "birth_city": "Berlin", "birth_country": "DE", "birth_name": "Schmidt", "decease_date": null, "nationalities": [ "DE", "AU" ], "phone_number": "4930901820", "postal_address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "fatca": { "status": false, "confirmed_at": "2020-08-24T14:15:22Z" }, "terms_and_conditions": { "consent_document_id": "d0b83880-3809-4eee-b0df-ca50db84c15a", "confirmed_at": "2020-08-24T14:14:22Z" }, "data_privacy_and_sharing_agreement": { "consent_document_id": "7ab0fc5c-8157-4acd-b02d-6ccda0e81dec", "confirmed_at": "2020-08-24T14:16:22Z" }, "status": "ACTIVE", "branch_id": "e6373bfa-ff12-4004-8de9-747ac96764da" } }, "TOL without Consents": { "summary": "TOL User without consents", "value": { "id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be202", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "first_name": "Karl", "last_name": "Schmidt", "email": "karl.schmidt@example.com", "salutation": "SALUTATION_MALE", "title": "DR", "birth_date": "1972-09-30", "birth_city": "Berlin", "birth_country": "DE", "birth_name": "Schmidt", "decease_date": null, "nationalities": [ "DE", "AU" ], "phone_number": "4930901820", "postal_address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "fatca": { "status": false, "confirmed_at": "2020-08-24T14:15:22Z" }, "status": "ACTIVE" } } } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/users/{user_id}": { "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "The unique identifier of the user. Universally Unique Identifier (UUID).", "schema": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_user", "summary": "Get a user by ID", "description": "Returns the user identified by `user_id`, including profile and status details", "tags": [ "Users" ], "security": [ { "oauth-client-credentials": [ "users:read", "users:admin" ] } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "User - Get - Response", "description": "The requested user, in the shape of the client's operating model (TOL or BYOL).", "anyOf": [ { "title": "User (BYOL)", "type": "object", "description": "A user onboarded under the Bring Your Own Licence (BYOL) operating model, where the client holds the regulatory licence.", "properties": { "id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "first_name": { "type": "string", "maxLength": 100, "minLength": 2, "description": "First name(s) of the user. Please include all first and middle names of the user." }, "last_name": { "type": "string", "maxLength": 100, "minLength": 1, "description": "Last name of the user." }, "salutation": { "type": "string", "description": "Salutation of the user used in reports and statements.\n* (empty string) - \n* SALUTATION_MALE - \n* SALUTATION_FEMALE - \n* SALUTATION_FEMALE_MARRIED - \n* SALUTATION_DIVERSE - ", "enum": [ "", "SALUTATION_MALE", "SALUTATION_FEMALE", "SALUTATION_FEMALE_MARRIED", "SALUTATION_DIVERSE" ], "default": "" }, "title": { "type": "string", "description": "Title of the user used in reports and statements.\n* (empty string) - \n* DR - Doctor\n* PROF - Professor\n* PROF_DR - \n* DIPL_ING - Graduate engineer (Diplom-Ingenieur)\n* MAGISTER - ", "enum": [ "", "DR", "PROF", "PROF_DR", "DIPL_ING", "MAGISTER" ], "default": "" }, "birth_date": { "type": "string", "format": "date", "description": "Birth date of the user in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" }, "birth_city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 }, "birth_country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "birth_name": { "type": "string", "maxLength": 100, "description": "If applicable, birth name of the user." }, "decease_date": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "date", "description": "The user's date of death in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" } ] }, "nationalities": { "type": "array", "items": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "minItems": 1, "description": "Nationalities of the user. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)." }, "address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, "postal_address": { "description": "User postal address. Needs to be specified if different to the residential address, otherwise it is automatically populated.", "oneOf": [ { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, { "type": "null" } ] }, "status": { "type": "string", "description": "Status of the user.\n* ACTIVE - \n* INACTIVE - \n* OFFBOARDING - \n* OFFBOARDED - ", "enum": [ "ACTIVE", "INACTIVE", "OFFBOARDING", "OFFBOARDED" ] }, "email": { "type": "string", "format": "email", "maxLength": 100, "description": "Email of the user. Must be a valid email address." }, "branch_id": { "title": "Branch unique identifier.", "type": "string", "description": "Unique identifier of the market the user is onboarded on. Only relevant if the client is operating in different markets and the client is configured accordingly", "format": "uuid" }, "gender": { "title": "Gender", "type": "string", "description": "Gender of the user. Required for users applying for the German pension government bonus.\n* (empty string) - \n* MALE - \n* FEMALE - \n* DIVERSE - ", "enum": [ "", "MALE", "FEMALE", "DIVERSE" ], "default": "" }, "social_security_number": { "title": "Social security number", "type": "string", "description": "The user's assigned social security number (German social insurance number, e.g. `25300972S014`). Required for users applying for the German pension government bonus.", "pattern": "^(\\d{2}(0[1-9]|[12]\\d|3[01])(0[1-9]|1[0-2])\\d{2}[A-Z]\\d{3})?$" }, "tags": { "title": "Tags", "type": "array", "items": { "type": "string", "enum": [ "CLIENT_EMPLOYEE" ] }, "uniqueItems": true, "description": "Labels applied to the user by the tenant. Omitted for users that have no tags.\n* CLIENT_EMPLOYEE - The user is an employee of the tenant.\n\nProviding this field in a data change request replaces the full set of tags; send an empty array to remove all tags." } }, "required": [ "id", "created_at", "updated_at", "first_name", "last_name", "birth_date", "nationalities", "address", "status" ], "additionalProperties": false }, { "title": "User (TOL)", "type": "object", "description": "A user onboarded under the Take Our Licence (TOL) operating model, where Upvest holds the regulatory licence. Includes the details collected during onboarding.", "properties": { "id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "first_name": { "type": "string", "maxLength": 100, "minLength": 2, "description": "First name(s) of the user. Please include all first and middle names of the user." }, "last_name": { "type": "string", "maxLength": 100, "minLength": 1, "description": "Last name of the user." }, "salutation": { "type": "string", "description": "Salutation of the user used in reports and statements.\n* (empty string) - \n* SALUTATION_MALE - \n* SALUTATION_FEMALE - \n* SALUTATION_FEMALE_MARRIED - \n* SALUTATION_DIVERSE - ", "enum": [ "", "SALUTATION_MALE", "SALUTATION_FEMALE", "SALUTATION_FEMALE_MARRIED", "SALUTATION_DIVERSE" ], "default": "" }, "title": { "type": "string", "description": "Title of the user used in reports and statements.\n* (empty string) - \n* DR - Doctor\n* PROF - Professor\n* PROF_DR - \n* DIPL_ING - Graduate engineer (Diplom-Ingenieur)\n* MAGISTER - ", "enum": [ "", "DR", "PROF", "PROF_DR", "DIPL_ING", "MAGISTER" ], "default": "" }, "birth_date": { "type": "string", "format": "date", "description": "Birth date of the user in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" }, "birth_city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 }, "birth_country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "birth_name": { "type": "string", "maxLength": 100, "description": "If applicable, birth name of the user." }, "decease_date": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "date", "description": "The user's date of death in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" } ] }, "nationalities": { "type": "array", "items": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "minItems": 1, "description": "Nationalities of the user. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)." }, "address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, "postal_address": { "description": "User postal address. Needs to be specified if different to the residential address, otherwise it is automatically populated.", "oneOf": [ { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, { "type": "null" } ] }, "status": { "type": "string", "description": "Status of the user.\n* ACTIVE - \n* INACTIVE - \n* OFFBOARDING - \n* OFFBOARDED - ", "enum": [ "ACTIVE", "INACTIVE", "OFFBOARDING", "OFFBOARDED" ] }, "email": { "type": "string", "format": "email", "maxLength": 100, "description": "Email of the user. Must be a valid email address." }, "phone_number": { "type": "string", "pattern": "^([0-9]{8,15})?$", "description": "Phone number of the user. [Phone number E.164 format](https://en.wikipedia.org/wiki/E.164)." }, "fatca": { "type": "object", "description": "The user's FATCA status and when it was confirmed", "properties": { "status": { "type": "boolean", "description": "The user’s FATCA status is true if the user is subject to paying taxes in the US, otherwise it can be set to false." }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp at which the user confirmed their FATCA status. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" } }, "required": [ "status", "confirmed_at" ] }, "terms_and_conditions": { "description": "Terms & Conditions will be needed for all users unless they are a child user or only a user on a business.", "type": "object", "properties": { "consent_document_id": { "title": "Consent unique identifier.", "type": "string", "description": "Consent unique identifier.", "format": "uuid" }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp at which the user consented to the terms & conditions. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" } }, "required": [ "consent_document_id", "confirmed_at" ] }, "data_privacy_and_sharing_agreement": { "description": "Data privacy agreement will be needed for all users unless they are a child user or only a user on a business.", "type": "object", "properties": { "consent_document_id": { "title": "Consent unique identifier.", "type": "string", "description": "Consent unique identifier.", "format": "uuid" }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp at which the user consented to the data sharing agreement. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" } }, "required": [ "consent_document_id", "confirmed_at" ] }, "branch_id": { "title": "Branch unique identifier.", "type": "string", "description": "Unique identifier of the market the user is onboarded on. Only relevant if the client is operating in different markets and the client is configured accordingly", "format": "uuid" }, "gender": { "title": "Gender", "type": "string", "description": "Gender of the user. Required for users applying for the German pension government bonus.\n* (empty string) - \n* MALE - \n* FEMALE - \n* DIVERSE - ", "enum": [ "", "MALE", "FEMALE", "DIVERSE" ], "default": "" }, "social_security_number": { "title": "Social security number", "type": "string", "description": "The user's assigned social security number (German social insurance number, e.g. `25300972S014`). Required for users applying for the German pension government bonus.", "pattern": "^(\\d{2}(0[1-9]|[12]\\d|3[01])(0[1-9]|1[0-2])\\d{2}[A-Z]\\d{3})?$" }, "tags": { "title": "Tags", "type": "array", "items": { "type": "string", "enum": [ "CLIENT_EMPLOYEE" ] }, "uniqueItems": true, "description": "Labels applied to the user by the tenant. Omitted for users that have no tags.\n* CLIENT_EMPLOYEE - The user is an employee of the tenant.\n\nProviding this field in a data change request replaces the full set of tags; send an empty array to remove all tags." } }, "required": [ "id", "created_at", "updated_at", "first_name", "last_name", "birth_date", "nationalities", "address", "status" ], "additionalProperties": false } ] }, "examples": { "BYOL": { "summary": "BYOL user", "value": { "id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be202", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "first_name": "Karl", "last_name": "Schmidt", "email": "karl.schmidt@example.com", "salutation": "SALUTATION_MALE", "title": "DR", "birth_date": "1972-09-30", "birth_city": "Berlin", "birth_country": "DE", "birth_name": "Schmidt", "decease_date": null, "nationalities": [ "DE", "AU" ], "postal_address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "status": "ACTIVE", "tags": [ "CLIENT_EMPLOYEE" ] } }, "BYOL User with Branch ID": { "summary": "BYOL User with Branch ID", "value": { "id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be202", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "first_name": "Karl", "last_name": "Schmidt", "salutation": "SALUTATION_MALE", "title": "DR", "birth_date": "1972-09-30", "birth_city": "Berlin", "birth_country": "DE", "birth_name": "Schmidt", "decease_date": null, "nationalities": [ "DE", "AU" ], "postal_address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "status": "ACTIVE", "branch_id": "e6373bfa-ff12-4004-8de9-747ac96764da" } }, "TOL": { "summary": "TOL user", "value": { "id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be202", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "first_name": "Karl", "last_name": "Schmidt", "email": "karl.schmidt@example.com", "salutation": "SALUTATION_MALE", "title": "DR", "birth_date": "1972-09-30", "birth_city": "Berlin", "birth_country": "DE", "birth_name": "Schmidt", "decease_date": null, "nationalities": [ "DE", "AU" ], "phone_number": "4930901820", "postal_address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "fatca": { "status": false, "confirmed_at": "2020-08-24T14:15:22Z" }, "terms_and_conditions": { "consent_document_id": "d0b83880-3809-4eee-b0df-ca50db84c15a", "confirmed_at": "2020-08-24T14:14:22Z" }, "data_privacy_and_sharing_agreement": { "consent_document_id": "7ab0fc5c-8157-4acd-b02d-6ccda0e81dec", "confirmed_at": "2020-08-24T14:16:22Z" }, "status": "ACTIVE", "tags": [ "CLIENT_EMPLOYEE" ] } }, "TOL User with Branch ID": { "summary": "TOL User with Branch ID", "value": { "id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be202", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "first_name": "Karl", "last_name": "Schmidt", "email": "karl.schmidt@example.com", "salutation": "SALUTATION_MALE", "title": "DR", "birth_date": "1972-09-30", "birth_city": "Berlin", "birth_country": "DE", "birth_name": "Schmidt", "decease_date": null, "nationalities": [ "DE", "AU" ], "phone_number": "4930901820", "postal_address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "fatca": { "status": false, "confirmed_at": "2020-08-24T14:15:22Z" }, "terms_and_conditions": { "consent_document_id": "d0b83880-3809-4eee-b0df-ca50db84c15a", "confirmed_at": "2020-08-24T14:14:22Z" }, "data_privacy_and_sharing_agreement": { "consent_document_id": "7ab0fc5c-8157-4acd-b02d-6ccda0e81dec", "confirmed_at": "2020-08-24T14:16:22Z" }, "status": "ACTIVE", "branch_id": "e6373bfa-ff12-4004-8de9-747ac96764da" } }, "TOL User without Consents": { "summary": "TOL user without consents", "value": { "id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be202", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "first_name": "Karl", "last_name": "Schmidt", "email": "karl.schmidt@example.com", "salutation": "SALUTATION_MALE", "title": "DR", "birth_date": "1972-09-30", "birth_city": "Berlin", "birth_country": "DE", "birth_name": "Schmidt", "decease_date": null, "nationalities": [ "DE", "AU" ], "phone_number": "4930901820", "postal_address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "fatca": { "status": false, "confirmed_at": "2020-08-24T14:15:22Z" }, "status": "ACTIVE" } } } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "delete": { "operationId": "offboard_user", "summary": "Offboard a user", "description": "Starts the user offboarding process in the background.", "tags": [ "Users" ], "security": [ { "oauth-client-credentials": [ "users:admin" ] } ], "responses": { "202": { "description": "The request has been successfully accepted and will be processed asynchronously.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/users/{user_id}/data_change_requests": { "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "The unique identifier of the user. Universally Unique Identifier (UUID).", "schema": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "post": { "operationId": "user_data_change", "summary": "Change user data", "description": "Requests a data change for a user specified by ID.", "tags": [ "Users" ], "security": [ { "oauth-client-credentials": [ "users:admin" ] } ], "requestBody": { "content": { "application/json": { "schema": { "title": "User - Data Change - Request", "description": "Request payload for changing user data. The permitted changes depend on the operating model (TOL or BYOL).", "anyOf": [ { "title": "User (BYOL) - Data Change Request", "type": "object", "description": "Request payload for changing the data of a BYOL user.", "properties": { "first_name": { "type": "string", "maxLength": 100, "minLength": 2, "description": "First name of the user." }, "last_name": { "type": "string", "maxLength": 100, "minLength": 2, "description": "Last name of the user." }, "email": { "type": "string", "format": "email", "maxLength": 100, "description": "Email of the user. Must be a valid email address." }, "salutation": { "type": "string", "description": "Salutation of the user used in reports and statements.\n* (empty string) - \n* SALUTATION_MALE - \n* SALUTATION_FEMALE - \n* SALUTATION_FEMALE_MARRIED - \n* SALUTATION_DIVERSE - ", "enum": [ "", "SALUTATION_MALE", "SALUTATION_FEMALE", "SALUTATION_FEMALE_MARRIED", "SALUTATION_DIVERSE" ], "default": "" }, "title": { "type": "string", "description": "Title of the user used in reports and statements.\n* (empty string) - \n* DR - Doctor\n* PROF - Professor\n* PROF_DR - \n* DIPL_ING - Graduate engineer (Diplom-Ingenieur)\n* MAGISTER - ", "enum": [ "", "DR", "PROF", "PROF_DR", "DIPL_ING", "MAGISTER" ], "default": "" }, "birth_date": { "type": "string", "format": "date", "description": "Birth date of the user in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" }, "birth_city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 }, "birth_country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "birth_name": { "type": "string", "maxLength": 100, "description": "If applicable, birth name of the user." }, "decease_date": { "title": "Decease Date - Change", "type": "string", "pattern": "^$|^\\d{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])$", "description": "The user's date of death in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339). Send an empty string to clear a decease date that was recorded in error." }, "nationalities": { "type": "array", "items": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "minItems": 1, "description": "Nationalities of the user. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)." }, "address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, "postal_address": { "description": "User postal address. Needs to be specified if different to the residential address, otherwise it is automatically populated.", "oneOf": [ { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, { "type": "null" } ] }, "branch_id": { "title": "Branch unique identifier.", "type": "string", "description": "Unique identifier of the market the user is onboarded on. Only relevant if the client is operating in different markets and the client is configured accordingly", "format": "uuid" }, "gender": { "title": "Gender", "type": "string", "description": "Gender of the user. Required for users applying for the German pension government bonus.\n* (empty string) - \n* MALE - \n* FEMALE - \n* DIVERSE - ", "enum": [ "", "MALE", "FEMALE", "DIVERSE" ], "default": "" }, "social_security_number": { "title": "Social security number", "type": "string", "description": "The user's assigned social security number (German social insurance number, e.g. `25300972S014`). Required for users applying for the German pension government bonus.", "pattern": "^(\\d{2}(0[1-9]|[12]\\d|3[01])(0[1-9]|1[0-2])\\d{2}[A-Z]\\d{3})?$" }, "tags": { "title": "Tags", "type": "array", "items": { "type": "string", "enum": [ "CLIENT_EMPLOYEE" ] }, "uniqueItems": true, "description": "Labels applied to the user by the tenant. Omitted for users that have no tags.\n* CLIENT_EMPLOYEE - The user is an employee of the tenant.\n\nProviding this field in a data change request replaces the full set of tags; send an empty array to remove all tags." } }, "minProperties": 1, "additionalProperties": false }, { "title": "User (TOL) - Data Change Request", "description": "Request payload for changing user data. The required proof documents depend on the type of change.", "oneOf": [ { "type": "object", "title": "User (TOL) - Data Change Request: Name change", "properties": { "first_name": { "type": "string", "maxLength": 100, "minLength": 2, "description": "First name(s) of the user. Please include all first and middle names of the user." }, "last_name": { "type": "string", "maxLength": 100, "minLength": 1, "description": "Last name of the user." }, "issuance_date": { "type": "string", "format": "date", "description": "Issuance date in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" }, "data_download_link": { "type": "string", "format": "url", "maxLength": 1000, "description": "Download URL for the document proving the data change. The file size must not exceed 250 MB." }, "document_type": { "type": "string", "description": "The type of document used to prove the data change\n* PASSPORT - Passport\n* ID_CARD - National Identification document", "enum": [ "PASSPORT", "ID_CARD" ] } }, "required": [ "first_name", "last_name", "issuance_date", "data_download_link", "document_type" ], "additionalProperties": false }, { "type": "object", "title": "User (TOL) - Data Change Request: Other", "properties": { "email": { "type": "string", "format": "email", "maxLength": 100, "description": "Email of the user. Must be a valid email address." }, "salutation": { "type": "string", "description": "Salutation of the user used in reports and statements.\n* (empty string) - \n* SALUTATION_MALE - \n* SALUTATION_FEMALE - \n* SALUTATION_FEMALE_MARRIED - \n* SALUTATION_DIVERSE - ", "enum": [ "", "SALUTATION_MALE", "SALUTATION_FEMALE", "SALUTATION_FEMALE_MARRIED", "SALUTATION_DIVERSE" ], "default": "" }, "title": { "type": "string", "description": "Title of the user used in reports and statements.\n* (empty string) - \n* DR - Doctor\n* PROF - Professor\n* PROF_DR - \n* DIPL_ING - Graduate engineer (Diplom-Ingenieur)\n* MAGISTER - ", "enum": [ "", "DR", "PROF", "PROF_DR", "DIPL_ING", "MAGISTER" ], "default": "" }, "phone_number": { "type": "string", "pattern": "^([0-9]{8,15})?$", "description": "Phone number of the user. [Phone number E.164 format](https://en.wikipedia.org/wiki/E.164)." }, "birth_name": { "type": "string", "maxLength": 100, "description": "If applicable, birth name of the user." }, "postal_address": { "description": "User postal address. Needs to be specified if different to the residential address, otherwise it is automatically populated.", "oneOf": [ { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, { "type": "null" } ] }, "branch_id": { "title": "Branch unique identifier.", "type": "string", "description": "Unique identifier of the market the user is onboarded on. Only relevant if the client is operating in different markets and the client is configured accordingly", "format": "uuid" }, "gender": { "title": "Gender", "type": "string", "description": "Gender of the user. Required for users applying for the German pension government bonus.\n* (empty string) - \n* MALE - \n* FEMALE - \n* DIVERSE - ", "enum": [ "", "MALE", "FEMALE", "DIVERSE" ], "default": "" }, "social_security_number": { "title": "Social security number", "type": "string", "description": "The user's assigned social security number (German social insurance number, e.g. `25300972S014`). Required for users applying for the German pension government bonus.", "pattern": "^(\\d{2}(0[1-9]|[12]\\d|3[01])(0[1-9]|1[0-2])\\d{2}[A-Z]\\d{3})?$" }, "tags": { "title": "Tags", "type": "array", "items": { "type": "string", "enum": [ "CLIENT_EMPLOYEE" ] }, "uniqueItems": true, "description": "Labels applied to the user by the tenant. Omitted for users that have no tags.\n* CLIENT_EMPLOYEE - The user is an employee of the tenant.\n\nProviding this field in a data change request replaces the full set of tags; send an empty array to remove all tags." }, "decease_date": { "title": "Decease Date - Change", "type": "string", "pattern": "^$|^\\d{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])$", "description": "The user's date of death in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339). Send an empty string to clear a decease date that was recorded in error." } }, "minProperties": 1, "additionalProperties": false }, { "type": "object", "title": "User (TOL) - Data Change Request: Nationality", "properties": { "nationalities": { "type": "array", "items": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "minItems": 1, "description": "Nationalities of the user. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)." }, "issuance_date": { "type": "string", "format": "date", "description": "Issuance date in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" }, "data_download_link": { "type": "string", "format": "url", "maxLength": 1000, "description": "Download URL for the document proving the data change. The file size must not exceed 250 MB." }, "document_type": { "type": "string", "description": "The type of document used to prove the data change\n* PASSPORT - Passport\n* ID_CARD - National Identification document", "enum": [ "PASSPORT", "ID_CARD" ] } }, "required": [ "nationalities", "issuance_date", "data_download_link", "document_type" ], "additionalProperties": false }, { "type": "object", "title": "User (TOL) - Data Change Request: Address", "properties": { "address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, "issuance_date": { "type": "string", "format": "date", "description": "Issuance date in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" }, "data_download_link": { "type": "string", "format": "url", "maxLength": 1000, "description": "Download URL for the document proving the data change. The file size must not exceed 250 MB." }, "document_type": { "type": "string", "description": "The type of document used to proof data change\n* UTILITY_BILL - Utility bill\n* TELEPHONE_BILL - Telephone bill\n* INTERNET_BILL - Internet bill\n* BANK_STATEMENT - Bank statement\n* REGISTRATION_CERT - Registration certificate\n* RESIDENCE_PERMIT - Residence permit\n* ID_CARD - National Identification document", "enum": [ "UTILITY_BILL", "TELEPHONE_BILL", "INTERNET_BILL", "BANK_STATEMENT", "REGISTRATION_CERT", "RESIDENCE_PERMIT", "ID_CARD" ] } }, "required": [ "address", "issuance_date", "data_download_link", "document_type" ], "additionalProperties": false } ] } ] }, "examples": { "Name": { "summary": "Name", "value": { "first_name": "Karl", "last_name": "Schmidt", "issuance_date": "2030-01-01", "data_download_link": "https://bucket.customer.com/ident/user3.zip", "document_type": "ID_CARD" } }, "TOL User Email": { "summary": "Email", "value": { "email": "max@example.com" } }, "Nationality": { "summary": "Nationality", "value": { "nationalities": [ "DE" ], "issuance_date": "2030-01-01", "data_download_link": "https://bucket.customer.com/ident/user3.zip", "document_type": "ID_CARD" } }, "Address": { "summary": "Address", "value": { "address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "issuance_date": "2020-01-01", "data_download_link": "https://bucket.customer.com/por/user3.zip", "document_type": "UTILITY_BILL" } }, "BYOL User Data Change": { "summary": "BYOL User Data Change", "value": { "first_name": "Karl", "last_name": "Schmidt", "email": "karl.schmidt@example.com", "salutation": "SALUTATION_MALE", "title": "PROF_DR", "birth_date": "1972-01-30", "birth_city": "Berlin", "birth_country": "DE", "birth_name": "Schmidt", "nationalities": [ "DE", "AU" ], "address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "postal_address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" }, "branch_id": "e6373bfa-ff12-4004-8de9-747ac96764da" } }, "TOL User Data Change With Branch ID": { "summary": "Branch ID", "value": { "branch_id": "e6373bfa-ff12-4004-8de9-747ac96764da" } }, "TOL User Decease Date": { "summary": "Decease date", "value": { "decease_date": "2026-02-27" } } } } } }, "responses": { "202": { "description": "The request has been successfully accepted and will be processed asynchronously.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/users/{user_id}/checks": { "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "The unique identifier of the user. Universally Unique Identifier (UUID).", "schema": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_user_checks", "summary": "Get checks for a user", "description": "Lists all checks for a user specified by ID.", "tags": [ "User Checks" ], "security": [ { "oauth-client-credentials": [ "checks:read", "checks:admin" ] } ], "parameters": [ { "name": "list_history", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "If true, return the full history of checks (all records) instead of only the latest check per type." }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "KYC", "INSTRUMENT_FIT", "POR", "COMPLIANCE", "GUARDIAN", "USER_SELF_ASSESSMENT", "US_WITHHOLDING_TAX_STATUS" ] }, "description": "Filter the returned checks to a single allowed check type (e.g. US_WITHHOLDING_TAX_STATUS)." } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "User Check - List - Response", "type": "object", "description": "Response containing the list of all checks conducted for a user.", "properties": { "data": { "type": "array", "description": "List of checks conducted for the user", "items": { "title": "User Check", "description": "A check conducted for a user: KYC, proof of residence, instrument fit, compliance, guardian, or self-assessment.", "oneOf": [ { "title": "User Check - Know your customer", "type": "object", "description": "The KYC (Know your customer) check is completed by the client sharing the valid and relevant KYC data for the user.", "properties": { "id": { "title": "User Check unique identifier", "type": "string", "description": "User Check unique identifier.", "format": "uuid" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "type": { "type": "string", "default": "KYC", "description": "The type of check must be “KYC”." }, "check_confirmed_at": { "type": "string", "format": "date-time", "description": "Completion date and time of the KYC check. Must not be older than 24 months." }, "data_download_link": { "type": "string", "format": "url", "maxLength": 1000, "description": "Download URL for the KYC evidence file. The file size must not exceed 250 MB." }, "document_type": { "type": "string", "description": "The type of document used in the KYC process.\n* PASSPORT - Passport\n* ID_CARD - National Identification document\n* RESIDENCE_PERMIT - Residence Permit\n* DRIVING_LICENSE - Driving License\n* TWO_PLUS_TWO_VERIFICATION_PROOF - Two plus two verification proof (for GB residence users only)\n", "enum": [ "PASSPORT", "ID_CARD", "RESIDENCE_PERMIT", "DRIVING_LICENSE", "TWO_PLUS_TWO_VERIFICATION_PROOF" ] }, "document_expiration_date": { "type": "string", "format": "date", "description": "Expiration date of the document used in KYC process in YYYY-MM-DD format.\n\n**The field is required for the following document types:**\n* PASSPORT\n* ID_CARD\n* RESIDENCE_PERMIT\n* DRIVING_LICENSE\n" }, "nationality": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Issuing country of the document used in the KYC process. [ISO 3166 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).\n\n**The field is required for the following document types:**\n* PASSPORT\n* ID_CARD\n* RESIDENCE_PERMIT\n* DRIVING_LICENSE\n" }, "status": { "type": "string", "description": "Final status of the KYC check.\n* IN_PROGRESS - KYC check is in progress\n* PASSED - KYC check passed\n* FAILED - KYC check failed", "enum": [ "IN_PROGRESS", "PASSED", "FAILED" ] }, "provider": { "type": "string", "maxLength": 100, "description": "Provider that was used to perform the KYC check." }, "method": { "type": "string", "description": "Method used for AML-compliant KYC process\n* VIDEO_ID - Video identification\n* IN_PERSON_ID - In-person identification at the post office or the client's outlet\n* ELECTRONIC_ID - Advanced electronic identification methods (namely German eID)\n* LIVENESS_PHOTO_ID - Photos and security features of the identification document in combination with a video-based liveness check (residence country must not be Germany in this case)\n* QUALIFIED_ELECTRONIC_SIGNATURE_WITH_TX - Qualified electronic signature accompanied by a bank transaction for verification\n* TWO_PLUS_TWO_VERIFICATION - A method of verifying identity by matching at least two personal details from two separate sources (for GB residence users only)\n* ID_COLLECTION - The identification document of the user is collected but has not undergone verification", "enum": [ "VIDEO_ID", "IN_PERSON_ID", "ELECTRONIC_ID", "LIVENESS_PHOTO_ID", "QUALIFIED_ELECTRONIC_SIGNATURE_WITH_TX", "TWO_PLUS_TWO_VERIFICATION", "ID_COLLECTION" ] }, "confirmed_address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, "kyc_update": { "type": "boolean", "description": "Marks this check as a KYC refresh/update as opposed to an initial record." } }, "required": [ "id", "user_id", "type", "check_confirmed_at", "data_download_link", "document_type", "status", "provider", "method" ], "additionalProperties": false }, { "title": "User Check - Proof of Residency", "type": "object", "description": "The PoR (Proof of residency) check is completed by the client sharing a valid PoR document, if not fulfilled by the KYC check.", "properties": { "id": { "title": "User Check unique identifier", "type": "string", "description": "User Check unique identifier.", "format": "uuid" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "type": { "type": "string", "default": "POR", "description": "The type of check must be POR." }, "check_confirmed_at": { "type": "string", "format": "date-time", "description": "Completion date and time of the PoR check." }, "issuance_date": { "type": "string", "format": "date", "description": "Issuance date in YYYY-MM-DD format." }, "data_download_link": { "type": "string", "format": "url", "maxLength": 1000, "description": "Download URL for the PoR evidence file. The file size must not exceed 250 MB." }, "document_type": { "type": "string", "description": "The type of document used in the PoR process. Maximum age of the document is 12 months (stated on the document) applicable for: Utility bills (water, gas, electricity), Telephone bills (only landline), Internet bills, Bank account statements. Documents that need to be still valid - Registration certificate (must be valid and issued within the past 5 years), Residence permit e.g. Blue Card (as long as valid and contains the registration address), ID Card that contains the registration address.\n* UTILITY_BILL - \n* TELEPHONE_BILL - \n* INTERNET_BILL - \n* BANK_STATEMENT - \n* REGISTRATION_CERT - \n* RESIDENCE_PERMIT - \n* ID_CARD - \n* PASSPORT - ", "enum": [ "UTILITY_BILL", "TELEPHONE_BILL", "INTERNET_BILL", "BANK_STATEMENT", "REGISTRATION_CERT", "RESIDENCE_PERMIT", "ID_CARD", "PASSPORT" ] }, "status": { "type": "string", "description": "Final status of the PoR check.\n* IN_PROGRESS - \n* PASSED - \n* FAILED - ", "enum": [ "IN_PROGRESS", "PASSED", "FAILED" ] }, "confirmed_address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] } }, "required": [ "id", "user_id", "type", "check_confirmed_at", "issuance_date", "data_download_link", "document_type", "status", "confirmed_address" ], "additionalProperties": false }, { "title": "User Check - Instrument fit", "type": "object", "description": "Instrument fit check is completed by the client providing the user's answers to the instrument appropriateness or suitability questionnaire.", "properties": { "id": { "title": "User Check unique identifier", "type": "string", "description": "User Check unique identifier.", "format": "uuid" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "type": { "type": "string", "default": "INSTRUMENT_FIT", "description": "The type of check must be INSTRUMENT_FIT." }, "check_confirmed_at": { "type": "string", "format": "date-time", "description": "Completion date and time of the instrument fit check." }, "status": { "type": "string", "description": "Final status of the instrument fit check.\n* IN_PROGRESS - Instrument fit check is in progress\n* PASSED - Instrument fit check passed\n* FAILED - Instrument fit check failed", "enum": [ "IN_PROGRESS", "PASSED", "FAILED" ] }, "instrument_suitability": { "type": "object", "description": "Outcome of the user's instrument suitability assessment.", "properties": { "suitability": { "type": "boolean", "description": "Did the user go through a suitability assessment and the outcome indicated suitability." } }, "required": [ "suitability" ] } }, "required": [ "id", "user_id", "type", "check_confirmed_at", "status", "instrument_suitability" ], "additionalProperties": false }, { "title": "User Check - Compliance", "type": "object", "description": "A compliance check conducted by Upvest for a user, including the check and user identifiers.", "properties": { "id": { "title": "User Check unique identifier", "type": "string", "description": "User Check unique identifier.", "format": "uuid" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "type": { "type": "string", "default": "COMPLIANCE", "description": "The type of check must be COMPLIANCE." }, "status": { "type": "string", "description": "Final status of the COMPLIANCE check.\n* IN_PROGRESS - Compliance check is in progress\n* PASSED - Compliance check passed\n* FAILED - Compliance check failed", "enum": [ "IN_PROGRESS", "PASSED", "FAILED" ] }, "check_confirmed_at": { "type": "string", "format": "date-time", "description": "Completion date and time of the COMPLIANCE check." } }, "required": [ "id", "user_id", "type", "check_confirmed_at" ], "additionalProperties": false }, { "title": "User Check - Guardian", "type": "object", "description": "The Guardian check is completed by the client providing documentation proving the guardian relationship with the child user.", "properties": { "id": { "title": "User Check unique identifier", "type": "string", "description": "User Check unique identifier.", "format": "uuid" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "type": { "type": "string", "default": "GUARDIAN", "description": "The type of check must be “GUARDIAN“." }, "check_confirmed_at": { "type": "string", "format": "date-time", "description": "Completion date and time of the PoR check." }, "role_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the role that this guardian check is associated with." }, "document_type": { "type": "string", "description": "The type of document used in the Guardian check.\n* BIRTH_CERTIFICATE - Birth certificate proving guardian relationship", "enum": [ "BIRTH_CERTIFICATE" ] }, "data_download_link": { "type": "string", "format": "url", "maxLength": 1000, "description": "Download URL for the guardian evidence file. The file size must not exceed 250 MB." }, "status": { "type": "string", "description": "Final status of the Guardian check.\n* IN_PROGRESS - Guardian check is in progress\n* PASSED - Guardian check passed\n* FAILED - Guardian check failed", "enum": [ "IN_PROGRESS", "PASSED", "FAILED" ] } }, "required": [ "id", "user_id", "type", "role_id", "document_type", "data_download_link", "status" ], "additionalProperties": false } ] } } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": [ { "id": "008a82d0-c5a4-4410-9318-d34786429c5a", "user_id": "7b39529a-e68c-4688-8242-7549d10d6084", "type": "KYC", "check_confirmed_at": "2019-08-24T14:15:22Z", "data_download_link": "https://bucket.customer.com/ident/user3.zip", "document_type": "ID_CARD", "document_expiration_date": "2030-01-01", "nationality": "DE", "status": "PASSED", "provider": "KYC provider", "method": "VIDEO_ID", "confirmed_address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" } }, { "id": "a680ff52-3a96-4e82-a2ab-12563bbd1a2e", "user_id": "7b39529a-e68c-4688-8242-7549d10d6084", "type": "INSTRUMENT_FIT", "check_confirmed_at": "2020-08-24T14:15:22Z", "status": "PASSED", "instrument_suitability": { "suitability": true } }, { "id": "b633a915-ed3c-43d7-afb5-a550f26ccb0d", "user_id": "7b39529a-e68c-4688-8242-7549d10d6084", "type": "POR", "check_confirmed_at": "2020-08-24T14:15:22Z", "issuance_date": "2020-01-01", "data_download_link": "https: //bucket.customer.com/por/user3.zip", "document_type": "UTILITY_BILL", "status": "PASSED", "confirmed_address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" } }, { "id": "76aa72aa-3738-4640-bad5-68c1196dc758", "user_id": "7b39529a-e68c-4688-8242-7549d10d6084", "type": "COMPLIANCE", "check_confirmed_at": "2020-08-24T14:15:22Z", "status": "PASSED" }, { "id": "d8f9e2c1-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "user_id": "7b39529a-e68c-4688-8242-7549d10d6084", "type": "GUARDIAN", "role_id": "baf05386-0459-4e8c-9ac9-cd6442f194dd", "document_type": "BIRTH_CERTIFICATE", "data_download_link": "https://bucket.customer.com/guardian/birth_cert.pdf", "status": "PASSED" } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "post": { "operationId": "create_user_check", "summary": "Create a new check for a user", "description": "Creates a new check for a user specified by ID.", "tags": [ "User Checks" ], "security": [ { "oauth-client-credentials": [ "checks:admin" ] } ], "requestBody": { "content": { "application/json": { "schema": { "title": "User Check - Create - Request", "description": "Request payload for creating a user check: KYC, proof of residence, instrument fit, guardian, or self-assessment.", "oneOf": [ { "title": "User Check - Know your customer - Create - Request", "type": "object", "description": "The KYC (Know your customer) check is completed by the client sharing the valid and relevant KYC data for the user.", "properties": { "type": { "type": "string", "default": "KYC", "description": "The type of check must be “KYC”." }, "check_confirmed_at": { "type": "string", "format": "date-time", "description": "Completion date and time of the KYC check. Must not be older than 24 months." }, "data_download_link": { "type": "string", "format": "url", "maxLength": 1000, "description": "Download URL for the KYC evidence file. The file size must not exceed 250 MB." }, "document_type": { "type": "string", "description": "The type of document used in the KYC process.\n* PASSPORT - Passport\n* ID_CARD - National Identification document\n* RESIDENCE_PERMIT - Residence Permit\n* DRIVING_LICENSE - Driving License\n* TWO_PLUS_TWO_VERIFICATION_PROOF - Two plus two verification proof (for GB residence users only)\n", "enum": [ "PASSPORT", "ID_CARD", "RESIDENCE_PERMIT", "DRIVING_LICENSE", "TWO_PLUS_TWO_VERIFICATION_PROOF" ] }, "document_expiration_date": { "type": "string", "format": "date", "description": "Expiration date of the document used in KYC process in YYYY-MM-DD format.\n\n**The field is required for the following document types:**\n* PASSPORT\n* ID_CARD\n* RESIDENCE_PERMIT\n* DRIVING_LICENSE\n" }, "nationality": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Issuing country of the document used in the KYC process. [ISO 3166 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).\n\n**The field is required for the following document types:**\n* PASSPORT\n* ID_CARD\n* RESIDENCE_PERMIT\n* DRIVING_LICENSE\n" }, "provider": { "type": "string", "maxLength": 100, "description": "Provider that was used to perform the KYC check." }, "method": { "type": "string", "description": "Method used for AML-compliant KYC process\n* VIDEO_ID - Video identification\n* IN_PERSON_ID - In-person identification at the post office or the client's outlet\n* ELECTRONIC_ID - Advanced electronic identification methods (namely German eID)\n* LIVENESS_PHOTO_ID - Photos and security features of the identification document in combination with a video-based liveness check (residence country must not be Germany in this case)\n* QUALIFIED_ELECTRONIC_SIGNATURE_WITH_TX - Qualified electronic signature accompanied by a bank transaction for verification\n* TWO_PLUS_TWO_VERIFICATION - A method of verifying identity by matching at least two personal details from two separate sources (for GB residence users only)\n* ID_COLLECTION - The identification document of the user is collected but has not undergone verification", "enum": [ "VIDEO_ID", "IN_PERSON_ID", "ELECTRONIC_ID", "LIVENESS_PHOTO_ID", "QUALIFIED_ELECTRONIC_SIGNATURE_WITH_TX", "TWO_PLUS_TWO_VERIFICATION", "ID_COLLECTION" ] }, "confirmed_address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, "kyc_update": { "type": "boolean", "description": "Marks this check as a KYC refresh/update as opposed to an initial record." } }, "required": [ "type", "check_confirmed_at", "data_download_link", "document_type", "provider", "method" ], "additionalProperties": false }, { "title": "User Check - Proof of Residency - Create - Request", "type": "object", "description": "The PoR (Proof of residency) check is completed by the client sharing a valid PoR document, if not fulfilled by the KYC check.", "properties": { "type": { "type": "string", "default": "POR", "description": "The type of check must be POR." }, "check_confirmed_at": { "type": "string", "format": "date-time", "description": "Completion date and time of the PoR check." }, "issuance_date": { "type": "string", "format": "date", "description": "Issuance date in YYYY-MM-DD format." }, "data_download_link": { "type": "string", "format": "url", "maxLength": 1000, "description": "Download URL for the PoR evidence file. The file size must not exceed 250 MB." }, "document_type": { "type": "string", "description": "The type of document used in the PoR process. Maximum age of the document is 12 months (stated on the document) applicable for: Utility bills (water, gas, electricity), Telephone bills (only landline), Internet bills, Bank account statements. Documents that need to be still valid - Registration certificate (must be valid and issued within the past 5 years), Residence permit e.g. Blue Card (as long as valid and contains the registration address), ID Card that contains the registration address.\n* UTILITY_BILL - \n* TELEPHONE_BILL - \n* INTERNET_BILL - \n* BANK_STATEMENT - \n* REGISTRATION_CERT - \n* RESIDENCE_PERMIT - \n* ID_CARD - ", "enum": [ "UTILITY_BILL", "TELEPHONE_BILL", "INTERNET_BILL", "BANK_STATEMENT", "REGISTRATION_CERT", "RESIDENCE_PERMIT", "ID_CARD" ] }, "confirmed_address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] } }, "required": [ "type", "check_confirmed_at", "issuance_date", "data_download_link", "document_type", "confirmed_address" ], "additionalProperties": false }, { "title": "User Check - Instrument fit - Create - Request", "type": "object", "description": "Instrument fit check is completed by the client providing the user's answers to the instrument appropriateness or suitability questionnaire.", "properties": { "type": { "type": "string", "default": "INSTRUMENT_FIT", "description": "The type of check must be INSTRUMENT_FIT." }, "check_confirmed_at": { "type": "string", "format": "date-time", "description": "Completion date and time of the instrument fit check." }, "instrument_suitability": { "type": "object", "description": "Outcome of the user's instrument suitability assessment.", "properties": { "suitability": { "type": "boolean", "description": "Did the user go through a suitability assessment and the outcome indicated suitability." } }, "required": [ "suitability" ] } }, "required": [ "type", "check_confirmed_at", "instrument_suitability" ], "additionalProperties": false }, { "title": "User Check - Guardian - Create - Request", "type": "object", "description": "The Guardian check is completed by the client providing documentation proving the guardian relationship with the child user.", "properties": { "type": { "type": "string", "default": "GUARDIAN", "description": "The type of check must be “GUARDIAN“." }, "check_confirmed_at": { "type": "string", "format": "date-time", "description": "Completion date and time of the PoR check." }, "role_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the role that this guardian check is associated with." }, "document_type": { "type": "string", "description": "The type of document used in the Guardian check.\n* BIRTH_CERTIFICATE - Birth certificate proving guardian relationship", "enum": [ "BIRTH_CERTIFICATE" ] }, "data_download_link": { "type": "string", "format": "url", "maxLength": 1000, "description": "Download URL for the guardian evidence file. The file size must not exceed 250 MB." } }, "required": [ "type", "check_confirmed_at", "role_id", "document_type", "data_download_link" ], "additionalProperties": false }, { "title": "User Check - User Self Assessment - Create - Request", "type": "object", "description": "The User Self-Assessment check is completed by the client providing self-assessment information about the user for AML risk monitoring.", "properties": { "type": { "type": "string", "default": "USER_SELF_ASSESSMENT", "description": "The type of check must be \"USER_SELF_ASSESSMENT\"." }, "check_confirmed_at": { "type": "string", "format": "date-time", "description": "The date and time when the self assessment information was provided by the end user." }, "user_occupation": { "title": "User Occupation", "type": "string", "description": "The user's employment/occupation status.", "enum": [ "EMPLOYEE", "HOMEMAKER", "PENSIONER", "PUBLIC_OFFICIAL", "UNEMPLOYED", "SELF_EMPLOYED_FREELANCER", "STUDENT", "TRAINEE", "OTHER" ] }, "user_industry": { "title": "User Industry", "type": "string", "description": "The industry the user is professionally active in.", "enum": [ "AGRICULTURE_FORESTRY_AND_FISHING", "MANUFACTURING", "UTILITIES_AND_ENERGY", "WHOLESALE_TRADE", "RETAIL_TRADE", "TRANSPORTATION_AND_LOGISTICS_RAIL_AND_STORAGE", "INFORMATION_TECHNOLOGY_AND_MEDIA_PRINT_PUBLISHING", "ADMIN_AND_SUPPORT_SERVICES_CLEANING_AND_FACILITIES", "EDUCATION_HIGHER_EDUCATION", "ENTERTAINMENT_ARTS_AND_RECREATION_NATURE_AND_ZOOS", "EXTRATERRITORIAL_AND_HOUSEHOLD_ACTIVITIES", "MANUFACTURING_PHARMACEUTICALS", "CONSTRUCTION", "RETAIL_TRADE_SPECIALITY", "WHOLESALE_TRADE_INDUSTRIAL", "TRANSPORTATION_AND_LOGISTICS", "ACCOMMODATION_AND_HOSPITALITY", "INFORMATION_TECHNOLOGY_AND_MEDIA", "REAL_ESTATE", "PROFESSIONAL_AND_TECHNICAL_SERVICES", "ADMIN_AND_SUPPORT_SERVICES", "PUBLIC_ADMINISTRATION", "EDUCATION", "HEALTHCARE", "ENTERTAINMENT_ARTS_AND_RECREATION", "PERSONAL_AND_OTHER_SERVICES", "MINING_AND_QUARRYING", "MANUFACTURING_WEAPONS_AND_HAZARDOUS", "MANUFACTURING_PRECIOUS_METALS_AND_JEWELLERY", "RETAIL_TRADE_SPECIFIC_SECTORS", "WHOLESALE_TRADE_PETROLEUM_AND_CHEMICALS", "WHOLESALE_TRADE_LUXURY_AND_COLLECTIBLES", "INFORMATION_TECHNOLOGY_AND_MEDIA_TELECOMMUNICATIONS", "TRANSPORTATION_AND_LOGISTICS_CRUISE_LINES", "ACCOMMODATION_AND_HOSPITALITY_TIMESHARING", "FOOD_AND_BEVERAGE_SERVICES", "INFORMATION_TECHNOLOGY_AND_MEDIA_ONLINE_GAMING", "FINANCIAL_SERVICES", "REAL_ESTATE_AGENCY_AND_BROKERAGE", "PROFESSIONAL_AND_TECHNICAL_SERVICES_LEGAL_AND_FIDUCIARY", "PROFESSIONAL_AND_TECHNICAL_SERVICES_UNREGULATED", "ADMIN_AND_SUPPORT_SERVICES_SPECIFIC_SECTORS", "ADMIN_AND_SUPPORT_SERVICES_SECURITY_AND_INVESTIGATION", "PUBLIC_ADMINISTRATION_JUDICIAL", "HEALTHCARE_COUNSELLING_AND_SOCIAL_SERVICES", "ENTERTAINMENT_ARTS_AND_RECREATION_SPECIFIC_SECTORS", "PERSONAL_AND_OTHER_SERVICES_NONPROFIT_AND_MEMBERSHIP_ORGANISATIONS", "PERSONAL_AND_OTHER_SERVICES_ADULT_AND_WELLNESS", "OTHER" ] }, "yearly_gross_income": { "title": "Monetary Range", "type": "object", "description": "A monetary range defined by a lower bound and an optional upper bound.", "properties": { "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "lower_bound": { "type": "number", "description": "The lower bound of the monetary range.", "minimum": 0 }, "upper_bound": { "type": "number", "description": "The upper bound of the monetary range.", "minimum": 0 } }, "required": [ "currency", "lower_bound" ], "additionalProperties": false }, "income_sources": { "type": "array", "description": "The user's sources of income. More than one may apply.", "items": { "title": "User Income Source", "type": "string", "description": "Source of user's income.", "enum": [ "EMPLOYMENT_INCOME", "CAPITAL_GAINS_SAVINGS_AND_INVESTMENTS", "INHERITANCE", "SELF_EMPLOYMENT", "REAL_ESTATE_SALE_RENTAL", "DONATIONS", "BUSINESS_ENTERPRISE_REVENUE", "GOVERNMENT_OR_SOCIAL_BENEFITS", "PENSION_RETIREMENT_FUNDS", "SOLE_TRADER", "OTHER", "NONE" ] }, "minItems": 1 } }, "required": [ "type", "check_confirmed_at", "user_occupation", "user_industry", "yearly_gross_income", "income_sources" ], "additionalProperties": false } ] }, "examples": { "KYC": { "summary": "KYC check", "value": { "type": "KYC", "check_confirmed_at": "2019-08-24T14:15:22Z", "data_download_link": "https://bucket.customer.com/ident/user3.zip", "document_type": "ID_CARD", "document_expiration_date": "2030-01-01", "nationality": "DE", "provider": "KYC provider", "method": "VIDEO_ID", "confirmed_address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" } } }, "INSTRUMENT_FIT": { "summary": "Instrument fit check", "value": { "type": "INSTRUMENT_FIT", "check_confirmed_at": "2020-08-24T14:15:22Z", "instrument_suitability": { "suitability": true } } }, "POR": { "summary": "PoR check", "value": { "type": "POR", "check_confirmed_at": "2020-08-24T14:15:22Z", "issuance_date": "2020-01-01", "data_download_link": "https://bucket.customer.com/por/user3.zip", "document_type": "UTILITY_BILL", "confirmed_address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" } } }, "GUARDIAN": { "summary": "Guardian check", "value": { "type": "GUARDIAN", "check_confirmed_at": "2020-08-24T14:15:22Z", "role_id": "baf05386-0459-4e8c-9ac9-cd6442f194dd", "document_type": "BIRTH_CERTIFICATE", "data_download_link": "https://bucket.customer.com/guardian/birth_cert.pdf" } }, "USER_SELF_ASSESSMENT": { "summary": "User self-assessment check", "value": { "type": "USER_SELF_ASSESSMENT", "check_confirmed_at": "2024-04-22T10:27:13Z", "user_occupation": "EMPLOYEE", "user_industry": "FINANCIAL_SERVICES", "yearly_gross_income": { "currency": "EUR", "lower_bound": 50000, "upper_bound": 75000 }, "income_sources": [ "EMPLOYMENT_INCOME", "CAPITAL_GAINS_SAVINGS_AND_INVESTMENTS" ] } } } } } }, "responses": { "202": { "description": "The request has been successfully accepted.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "User Check - Create - Response", "type": "object", "description": "Response containing the unique identifier of the user check created.", "properties": { "id": { "title": "User Check unique identifier", "type": "string", "description": "User Check unique identifier.", "format": "uuid" } }, "required": [ "id" ], "additionalProperties": false }, "example": { "id": "e13e9d81-7f43-492d-a02a-440edced389a" } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/users/{user_id}/checks/{check_id}": { "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "The unique identifier of the user. Universally Unique Identifier (UUID).", "schema": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" } }, { "name": "check_id", "in": "path", "required": true, "description": "The unique identifier of the user check. Universally Unique Identifier (UUID).", "schema": { "title": "User Check unique identifier", "type": "string", "description": "User Check unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_user_check", "summary": "Get a user check by ID", "description": "Retrieves a check for a user specified by its ID.", "tags": [ "User Checks" ], "security": [ { "oauth-client-credentials": [ "checks:read", "checks:admin" ] } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "User Check", "description": "A check conducted for a user: KYC, proof of residence, instrument fit, compliance, guardian, or self-assessment.", "oneOf": [ { "title": "User Check - Know your customer", "type": "object", "description": "The KYC (Know your customer) check is completed by the client sharing the valid and relevant KYC data for the user.", "properties": { "id": { "title": "User Check unique identifier", "type": "string", "description": "User Check unique identifier.", "format": "uuid" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "type": { "type": "string", "default": "KYC", "description": "The type of check must be “KYC”." }, "check_confirmed_at": { "type": "string", "format": "date-time", "description": "Completion date and time of the KYC check. Must not be older than 24 months." }, "data_download_link": { "type": "string", "format": "url", "maxLength": 1000, "description": "Download URL for the KYC evidence file. The file size must not exceed 250 MB." }, "document_type": { "type": "string", "description": "The type of document used in the KYC process.\n* PASSPORT - Passport\n* ID_CARD - National Identification document\n* RESIDENCE_PERMIT - Residence Permit\n* DRIVING_LICENSE - Driving License\n* TWO_PLUS_TWO_VERIFICATION_PROOF - Two plus two verification proof (for GB residence users only)\n", "enum": [ "PASSPORT", "ID_CARD", "RESIDENCE_PERMIT", "DRIVING_LICENSE", "TWO_PLUS_TWO_VERIFICATION_PROOF" ] }, "document_expiration_date": { "type": "string", "format": "date", "description": "Expiration date of the document used in KYC process in YYYY-MM-DD format.\n\n**The field is required for the following document types:**\n* PASSPORT\n* ID_CARD\n* RESIDENCE_PERMIT\n* DRIVING_LICENSE\n" }, "nationality": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Issuing country of the document used in the KYC process. [ISO 3166 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).\n\n**The field is required for the following document types:**\n* PASSPORT\n* ID_CARD\n* RESIDENCE_PERMIT\n* DRIVING_LICENSE\n" }, "status": { "type": "string", "description": "Final status of the KYC check.\n* IN_PROGRESS - KYC check is in progress\n* PASSED - KYC check passed\n* FAILED - KYC check failed", "enum": [ "IN_PROGRESS", "PASSED", "FAILED" ] }, "provider": { "type": "string", "maxLength": 100, "description": "Provider that was used to perform the KYC check." }, "method": { "type": "string", "description": "Method used for AML-compliant KYC process\n* VIDEO_ID - Video identification\n* IN_PERSON_ID - In-person identification at the post office or the client's outlet\n* ELECTRONIC_ID - Advanced electronic identification methods (namely German eID)\n* LIVENESS_PHOTO_ID - Photos and security features of the identification document in combination with a video-based liveness check (residence country must not be Germany in this case)\n* QUALIFIED_ELECTRONIC_SIGNATURE_WITH_TX - Qualified electronic signature accompanied by a bank transaction for verification\n* TWO_PLUS_TWO_VERIFICATION - A method of verifying identity by matching at least two personal details from two separate sources (for GB residence users only)\n* ID_COLLECTION - The identification document of the user is collected but has not undergone verification", "enum": [ "VIDEO_ID", "IN_PERSON_ID", "ELECTRONIC_ID", "LIVENESS_PHOTO_ID", "QUALIFIED_ELECTRONIC_SIGNATURE_WITH_TX", "TWO_PLUS_TWO_VERIFICATION", "ID_COLLECTION" ] }, "confirmed_address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, "kyc_update": { "type": "boolean", "description": "Marks this check as a KYC refresh/update as opposed to an initial record." } }, "required": [ "id", "user_id", "type", "check_confirmed_at", "data_download_link", "document_type", "status", "provider", "method" ], "additionalProperties": false }, { "title": "User Check - Proof of Residency", "type": "object", "description": "The PoR (Proof of residency) check is completed by the client sharing a valid PoR document, if not fulfilled by the KYC check.", "properties": { "id": { "title": "User Check unique identifier", "type": "string", "description": "User Check unique identifier.", "format": "uuid" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "type": { "type": "string", "default": "POR", "description": "The type of check must be POR." }, "check_confirmed_at": { "type": "string", "format": "date-time", "description": "Completion date and time of the PoR check." }, "issuance_date": { "type": "string", "format": "date", "description": "Issuance date in YYYY-MM-DD format." }, "data_download_link": { "type": "string", "format": "url", "maxLength": 1000, "description": "Download URL for the PoR evidence file. The file size must not exceed 250 MB." }, "document_type": { "type": "string", "description": "The type of document used in the PoR process. Maximum age of the document is 12 months (stated on the document) applicable for: Utility bills (water, gas, electricity), Telephone bills (only landline), Internet bills, Bank account statements. Documents that need to be still valid - Registration certificate (must be valid and issued within the past 5 years), Residence permit e.g. Blue Card (as long as valid and contains the registration address), ID Card that contains the registration address.\n* UTILITY_BILL - \n* TELEPHONE_BILL - \n* INTERNET_BILL - \n* BANK_STATEMENT - \n* REGISTRATION_CERT - \n* RESIDENCE_PERMIT - \n* ID_CARD - \n* PASSPORT - ", "enum": [ "UTILITY_BILL", "TELEPHONE_BILL", "INTERNET_BILL", "BANK_STATEMENT", "REGISTRATION_CERT", "RESIDENCE_PERMIT", "ID_CARD", "PASSPORT" ] }, "status": { "type": "string", "description": "Final status of the PoR check.\n* IN_PROGRESS - \n* PASSED - \n* FAILED - ", "enum": [ "IN_PROGRESS", "PASSED", "FAILED" ] }, "confirmed_address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] } }, "required": [ "id", "user_id", "type", "check_confirmed_at", "issuance_date", "data_download_link", "document_type", "status", "confirmed_address" ], "additionalProperties": false }, { "title": "User Check - Instrument fit", "type": "object", "description": "Instrument fit check is completed by the client providing the user's answers to the instrument appropriateness or suitability questionnaire.", "properties": { "id": { "title": "User Check unique identifier", "type": "string", "description": "User Check unique identifier.", "format": "uuid" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "type": { "type": "string", "default": "INSTRUMENT_FIT", "description": "The type of check must be INSTRUMENT_FIT." }, "check_confirmed_at": { "type": "string", "format": "date-time", "description": "Completion date and time of the instrument fit check." }, "status": { "type": "string", "description": "Final status of the instrument fit check.\n* IN_PROGRESS - Instrument fit check is in progress\n* PASSED - Instrument fit check passed\n* FAILED - Instrument fit check failed", "enum": [ "IN_PROGRESS", "PASSED", "FAILED" ] }, "instrument_suitability": { "type": "object", "description": "Outcome of the user's instrument suitability assessment.", "properties": { "suitability": { "type": "boolean", "description": "Did the user go through a suitability assessment and the outcome indicated suitability." } }, "required": [ "suitability" ] } }, "required": [ "id", "user_id", "type", "check_confirmed_at", "status", "instrument_suitability" ], "additionalProperties": false }, { "title": "User Check - Compliance", "type": "object", "description": "A compliance check conducted by Upvest for a user, including the check and user identifiers.", "properties": { "id": { "title": "User Check unique identifier", "type": "string", "description": "User Check unique identifier.", "format": "uuid" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "type": { "type": "string", "default": "COMPLIANCE", "description": "The type of check must be COMPLIANCE." }, "status": { "type": "string", "description": "Final status of the COMPLIANCE check.\n* IN_PROGRESS - Compliance check is in progress\n* PASSED - Compliance check passed\n* FAILED - Compliance check failed", "enum": [ "IN_PROGRESS", "PASSED", "FAILED" ] }, "check_confirmed_at": { "type": "string", "format": "date-time", "description": "Completion date and time of the COMPLIANCE check." } }, "required": [ "id", "user_id", "type", "check_confirmed_at" ], "additionalProperties": false }, { "title": "User Check - Guardian", "type": "object", "description": "The Guardian check is completed by the client providing documentation proving the guardian relationship with the child user.", "properties": { "id": { "title": "User Check unique identifier", "type": "string", "description": "User Check unique identifier.", "format": "uuid" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "type": { "type": "string", "default": "GUARDIAN", "description": "The type of check must be “GUARDIAN“." }, "check_confirmed_at": { "type": "string", "format": "date-time", "description": "Completion date and time of the PoR check." }, "role_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the role that this guardian check is associated with." }, "document_type": { "type": "string", "description": "The type of document used in the Guardian check.\n* BIRTH_CERTIFICATE - Birth certificate proving guardian relationship", "enum": [ "BIRTH_CERTIFICATE" ] }, "data_download_link": { "type": "string", "format": "url", "maxLength": 1000, "description": "Download URL for the guardian evidence file. The file size must not exceed 250 MB." }, "status": { "type": "string", "description": "Final status of the Guardian check.\n* IN_PROGRESS - Guardian check is in progress\n* PASSED - Guardian check passed\n* FAILED - Guardian check failed", "enum": [ "IN_PROGRESS", "PASSED", "FAILED" ] } }, "required": [ "id", "user_id", "type", "role_id", "document_type", "data_download_link", "status" ], "additionalProperties": false } ] }, "examples": { "KYC": { "summary": "KYC user check", "value": { "id": "008a82d0-c5a4-4410-9318-d34786429c5a", "user_id": "7b39529a-e68c-4688-8242-7549d10d6084", "type": "KYC", "check_confirmed_at": "2019-08-24T14:15:22Z", "data_download_link": "https://bucket.customer.com/ident/user3.zip", "document_type": "ID_CARD", "document_expiration_date": "2030-01-01", "nationality": "DE", "status": "PASSED", "provider": "KYC provider", "method": "VIDEO_ID", "confirmed_address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" } } }, "INSTRUMENT_FIT": { "summary": "Instrument fit user check", "value": { "id": "a680ff52-3a96-4e82-a2ab-12563bbd1a2e", "user_id": "7b39529a-e68c-4688-8242-7549d10d6084", "type": "INSTRUMENT_FIT", "check_confirmed_at": "2020-08-24T14:15:22Z", "status": "PASSED", "instrument_suitability": { "suitability": true } } }, "POR": { "summary": "POR user check", "value": { "id": "b633a915-ed3c-43d7-afb5-a550f26ccb0d", "user_id": "7b39529a-e68c-4688-8242-7549d10d6084", "type": "POR", "check_confirmed_at": "2020-08-24T14:15:22Z", "issuance_date": "2020-01-01", "data_download_link": "https://bucket.customer.com/por/user3.zip", "document_type": "UTILITY_BILL", "status": "PASSED", "confirmed_address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "state": "BE", "country": "DE" } } }, "COMPLIANCE": { "summary": "Compliance user check", "value": { "id": "76aa72aa-3738-4640-bad5-68c1196dc758", "user_id": "7b39529a-e68c-4688-8242-7549d10d6084", "type": "COMPLIANCE", "check_confirmed_at": "2020-08-24T14:15:22Z", "status": "PASSED" } }, "GUARDIAN": { "summary": "Guardian user check", "value": { "id": "d8f9e2c1-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "user_id": "7b39529a-e68c-4688-8242-7549d10d6084", "type": "GUARDIAN", "check_confirmed_at": "2020-08-24T14:15:22Z", "role_id": "baf05386-0459-4e8c-9ac9-cd6442f194dd", "document_type": "BIRTH_CERTIFICATE", "data_download_link": "https://bucket.customer.com/guardian/birth_cert.pdf", "status": "PASSED" } }, "USER_SELF_ASSESMENT": { "summary": "User self-assessment user check", "value": { "id": "d8f9e2c1-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "user_id": "7b39529a-e68c-4688-8242-7549d10d6084", "type": "USER_SELF_ASSESSMENT", "check_confirmed_at": "2024-04-22T10:27:13Z", "user_occupation": "EMPLOYEE", "user_industry": "FINANCIAL_SERVICES", "yearly_gross_income": { "currency": "EUR", "lower_bound": 50000, "upper_bound": 75000 }, "income_sources": [ "EMPLOYMENT_INCOME", "CAPITAL_GAINS_SAVINGS_AND_INVESTMENTS" ], "status": "PASSED" } } } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/users/{user_id}/identifiers": { "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "The unique identifier of the user. Universally Unique Identifier (UUID).", "schema": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_user_identifiers", "summary": "Get user identifiers", "description": "Lists all existing identifiers of a user used for transaction reporting.", "tags": [ "User Identifiers" ], "security": [ { "oauth-client-credentials": [ "users:read", "users:admin" ] } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Identifiers - List - Response", "type": "object", "description": "Response containing the list of all identifiers held by a user.", "properties": { "data": { "type": "array", "description": "List of identifiers held by the user", "items": { "title": "Identifier", "type": "object", "description": "An identifier held by a user for transaction reporting obligations, such as a national ID or passport number. The applicable identifier standard depends on the issuing country's priority rules.", "properties": { "id": { "title": "Unique identifier for the user's national ID.", "type": "string", "description": "Unique identifier of the user identifier resource, as a UUID.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "identifier_standard": { "type": "string", "maxLength": 6, "description": "Identifier standard abbreviation. If it is not provided, the issuing country's 1st priority identifier standard is used by default. Use `CONCAT` to submit a CONCAT identifier. See the User identifiers guide ([TOL](https://docs.upvest.co/products/tol/guides/users/users_identifiers) / [BYOL](https://docs.upvest.co/products/byol/guides/users/users_identifiers))." }, "identifier": { "type": "string", "maxLength": 30, "minLength": 0, "description": "Identifier value. Omit this field when `identifier_standard` is `CONCAT`: the value is generated by Upvest from the user's name and date of birth. See the User identifiers guide ([TOL](https://docs.upvest.co/products/tol/guides/users/users_identifiers) / [BYOL](https://docs.upvest.co/products/byol/guides/users/users_identifiers))." }, "type": { "type": "string", "description": "Identifier type.\n* NATIONAL_ID — national identity card number issued by the user's country.\n* PASSPORT — passport number issued by the user's country.", "enum": [ "NATIONAL_ID", "PASSPORT" ], "default": "NATIONAL_ID" }, "issuing_country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] } }, "required": [ "id", "user_id", "created_at", "updated_at", "identifier_standard", "identifier", "type", "issuing_country" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": [ { "id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be202", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "user_id": "00000ec2-d2ca-49ff-bbea-b92b5c3be203", "type": "NATIONAL_ID", "issuing_country": "PL", "identifier_standard": "PESEL", "identifier": "83053078917" }, { "id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be111", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "user_id": "00000ec2-d2ca-49ff-bbea-b92b5c3be203", "type": "NATIONAL_ID", "issuing_country": "DK", "identifier_standard": "DPIC", "identifier": "3005837891" }, { "id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be303", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "user_id": "00000ec2-d2ca-49ff-bbea-b92b5c3be505", "type": "NATIONAL_ID", "issuing_country": "DE", "identifier_standard": "CONCAT", "identifier": "" }, { "id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be303", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "user_id": "00000ec2-d2ca-49ff-bbea-b92b5c3be505", "type": "PASSPORT", "issuing_country": "NL", "identifier_standard": "NLPN", "identifier": "" } ] } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "post": { "operationId": "create_identifier", "summary": "Create a user identifier", "description": "Creates a new identifier for a user that will be used for transaction reporting obligations. This identifier is required for user activation if the user's nationalities do not allow reporting using the CONCAT format.\n\nSee the User identifiers guide ([TOL](https://docs.upvest.co/products/tol/guides/users/users_identifiers) / [BYOL](https://docs.upvest.co/products/byol/guides/users/users_identifiers)) for details.", "tags": [ "User Identifiers" ], "security": [ { "oauth-client-credentials": [ "users:admin" ] } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Identifier - Create - Request", "type": "object", "description": "Request payload for creating a user identifier used for transaction reporting. Provide `type` and `issuing_country`; the `identifier` value is required unless the `identifier_standard` is `CONCAT`.", "properties": { "type": { "type": "string", "description": "Identifier type.\n* NATIONAL_ID — national identity card number issued by the user's country.\n* PASSPORT — passport number issued by the user's country.", "enum": [ "NATIONAL_ID", "PASSPORT" ], "default": "NATIONAL_ID" }, "issuing_country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "identifier": { "type": "string", "maxLength": 30, "minLength": 0, "description": "Identifier value. Omit this field when `identifier_standard` is `CONCAT`: the value is generated by Upvest from the user's name and date of birth. See the User identifiers guide ([TOL](https://docs.upvest.co/products/tol/guides/users/users_identifiers) / [BYOL](https://docs.upvest.co/products/byol/guides/users/users_identifiers))." }, "identifier_standard": { "type": "string", "maxLength": 6, "description": "Identifier standard abbreviation. If it is not provided, the issuing country's 1st priority identifier standard is used by default. Use `CONCAT` to submit a CONCAT identifier. See the User identifiers guide ([TOL](https://docs.upvest.co/products/tol/guides/users/users_identifiers) / [BYOL](https://docs.upvest.co/products/byol/guides/users/users_identifiers))." } }, "required": [ "type", "issuing_country" ], "additionalProperties": false }, "examples": { "national_id": { "summary": "National ID", "value": { "type": "NATIONAL_ID", "issuing_country": "PL", "identifier_standard": "PESEL", "identifier": "83053078917" } }, "passport": { "summary": "Passport", "value": { "type": "PASSPORT", "issuing_country": "NL", "identifier_standard": "NLPN", "identifier": "AB12AB349" } }, "concat": { "summary": "CONCAT (value generated by Upvest, identifier omitted)", "value": { "type": "NATIONAL_ID", "issuing_country": "DE", "identifier_standard": "CONCAT" } } } } } }, "responses": { "200": { "description": "The user identifier is created.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Identifier", "type": "object", "description": "An identifier held by a user for transaction reporting obligations, such as a national ID or passport number. The applicable identifier standard depends on the issuing country's priority rules.", "properties": { "id": { "title": "Unique identifier for the user's national ID.", "type": "string", "description": "Unique identifier of the user identifier resource, as a UUID.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "identifier_standard": { "type": "string", "maxLength": 6, "description": "Identifier standard abbreviation. If it is not provided, the issuing country's 1st priority identifier standard is used by default. Use `CONCAT` to submit a CONCAT identifier. See the User identifiers guide ([TOL](https://docs.upvest.co/products/tol/guides/users/users_identifiers) / [BYOL](https://docs.upvest.co/products/byol/guides/users/users_identifiers))." }, "identifier": { "type": "string", "maxLength": 30, "minLength": 0, "description": "Identifier value. Omit this field when `identifier_standard` is `CONCAT`: the value is generated by Upvest from the user's name and date of birth. See the User identifiers guide ([TOL](https://docs.upvest.co/products/tol/guides/users/users_identifiers) / [BYOL](https://docs.upvest.co/products/byol/guides/users/users_identifiers))." }, "type": { "type": "string", "description": "Identifier type.\n* NATIONAL_ID — national identity card number issued by the user's country.\n* PASSPORT — passport number issued by the user's country.", "enum": [ "NATIONAL_ID", "PASSPORT" ], "default": "NATIONAL_ID" }, "issuing_country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] } }, "required": [ "id", "user_id", "created_at", "updated_at", "identifier_standard", "identifier", "type", "issuing_country" ], "additionalProperties": false }, "examples": { "national_id": { "summary": "National ID", "value": { "id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be202", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "user_id": "00000ec2-d2ca-49ff-bbea-b92b5c3be203", "type": "NATIONAL_ID", "issuing_country": "PL", "identifier_standard": "PESEL", "identifier": "83053078917" } }, "passport": { "summary": "Passport", "value": { "id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be202", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "user_id": "00000ec2-d2ca-49ff-bbea-b92b5c3be203", "type": "PASSPORT", "issuing_country": "NL", "identifier_standard": "NLPN", "identifier": "83053078917" } } } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/users/{user_id}/identifiers/{identifier_id}": { "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "The unique identifier of the user. Universally Unique Identifier (UUID).", "schema": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" } }, { "name": "identifier_id", "in": "path", "required": true, "description": "The unique identifier of the user identifier document. Universally Unique Identifier (UUID).", "schema": { "title": "Unique identifier for the user's national ID.", "type": "string", "description": "Unique identifier of the user identifier resource, as a UUID.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_identifier", "summary": "Get a user identifier by ID", "description": "Returns an existing identifier of a given user used for transaction reporting.", "tags": [ "User Identifiers" ], "security": [ { "oauth-client-credentials": [ "users:read", "users:admin" ] } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Identifier", "type": "object", "description": "An identifier held by a user for transaction reporting obligations, such as a national ID or passport number. The applicable identifier standard depends on the issuing country's priority rules.", "properties": { "id": { "title": "Unique identifier for the user's national ID.", "type": "string", "description": "Unique identifier of the user identifier resource, as a UUID.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "identifier_standard": { "type": "string", "maxLength": 6, "description": "Identifier standard abbreviation. If it is not provided, the issuing country's 1st priority identifier standard is used by default. Use `CONCAT` to submit a CONCAT identifier. See the User identifiers guide ([TOL](https://docs.upvest.co/products/tol/guides/users/users_identifiers) / [BYOL](https://docs.upvest.co/products/byol/guides/users/users_identifiers))." }, "identifier": { "type": "string", "maxLength": 30, "minLength": 0, "description": "Identifier value. Omit this field when `identifier_standard` is `CONCAT`: the value is generated by Upvest from the user's name and date of birth. See the User identifiers guide ([TOL](https://docs.upvest.co/products/tol/guides/users/users_identifiers) / [BYOL](https://docs.upvest.co/products/byol/guides/users/users_identifiers))." }, "type": { "type": "string", "description": "Identifier type.\n* NATIONAL_ID — national identity card number issued by the user's country.\n* PASSPORT — passport number issued by the user's country.", "enum": [ "NATIONAL_ID", "PASSPORT" ], "default": "NATIONAL_ID" }, "issuing_country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] } }, "required": [ "id", "user_id", "created_at", "updated_at", "identifier_standard", "identifier", "type", "issuing_country" ], "additionalProperties": false }, "example": { "id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be202", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "user_id": "00000ec2-d2ca-49ff-bbea-b92b5c3be203", "type": "NATIONAL_ID", "issuing_country": "PL", "identifier_standard": "PESEL", "identifier": "83053078917" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "patch": { "operationId": "update_identifier", "summary": "Update a user identifier by ID", "description": "Updates an existing identifier of a given user used for transaction reporting.", "tags": [ "User Identifiers" ], "security": [ { "oauth-client-credentials": [ "users:admin" ] } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Identifier - Update - Request", "type": "object", "description": "Request payload for updating the value of an existing user identifier. Only the `identifier` value can be changed.", "properties": { "identifier": { "type": "string", "maxLength": 30, "minLength": 0, "description": "Identifier value. Omit this field when `identifier_standard` is `CONCAT`: the value is generated by Upvest from the user's name and date of birth. See the User identifiers guide ([TOL](https://docs.upvest.co/products/tol/guides/users/users_identifiers) / [BYOL](https://docs.upvest.co/products/byol/guides/users/users_identifiers))." } }, "required": [ "identifier" ], "additionalProperties": false }, "example": { "identifier": "83053078111" } } } }, "responses": { "200": { "description": "The user identifier is updated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Identifier", "type": "object", "description": "An identifier held by a user for transaction reporting obligations, such as a national ID or passport number. The applicable identifier standard depends on the issuing country's priority rules.", "properties": { "id": { "title": "Unique identifier for the user's national ID.", "type": "string", "description": "Unique identifier of the user identifier resource, as a UUID.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "identifier_standard": { "type": "string", "maxLength": 6, "description": "Identifier standard abbreviation. If it is not provided, the issuing country's 1st priority identifier standard is used by default. Use `CONCAT` to submit a CONCAT identifier. See the User identifiers guide ([TOL](https://docs.upvest.co/products/tol/guides/users/users_identifiers) / [BYOL](https://docs.upvest.co/products/byol/guides/users/users_identifiers))." }, "identifier": { "type": "string", "maxLength": 30, "minLength": 0, "description": "Identifier value. Omit this field when `identifier_standard` is `CONCAT`: the value is generated by Upvest from the user's name and date of birth. See the User identifiers guide ([TOL](https://docs.upvest.co/products/tol/guides/users/users_identifiers) / [BYOL](https://docs.upvest.co/products/byol/guides/users/users_identifiers))." }, "type": { "type": "string", "description": "Identifier type.\n* NATIONAL_ID — national identity card number issued by the user's country.\n* PASSPORT — passport number issued by the user's country.", "enum": [ "NATIONAL_ID", "PASSPORT" ], "default": "NATIONAL_ID" }, "issuing_country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] } }, "required": [ "id", "user_id", "created_at", "updated_at", "identifier_standard", "identifier", "type", "issuing_country" ], "additionalProperties": false }, "example": { "id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be202", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-22T15:20:10.00Z", "user_id": "00000ec2-d2ca-49ff-bbea-b92b5c3be203", "type": "NATIONAL_ID", "issuing_country": "PL", "identifier_standard": "PESEL", "identifier": "83053078111" } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/users/{user_id}/account_groups": { "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "The unique identifier of the user. Universally Unique Identifier (UUID).", "schema": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_user_account_groups", "summary": "Get user account groups", "description": "Lists the account groups of a user specified by ID.", "tags": [ "Account Groups" ], "security": [ { "oauth-client-credentials": [ "accounts:read", "accounts:admin" ] } ], "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "updated_at" ], "default": "created_at" }, "description": "Sort the result by `created_at`, `updated_at`." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Account Groups - List - Response", "type": "object", "description": "Paginated response containing the account groups owned by a user.", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "description": "List of the user's account groups", "items": { "title": "Account Group", "type": "object", "description": "", "properties": { "id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "type": { "type": "string", "description": "Relation type\n* OWNER - Account Group Owner\n* CHILD - Child Account Group Owner\n* GUARDIAN - Child Account Group Guardian", "enum": [ "OWNER", "CHILD", "GUARDIAN" ] } } } }, "status": { "type": "string", "description": "Status of the account group\n* PENDING_APPROVAL - Account group approval is pending - the account group is visible through our API but cannot be acted on.\n* ACTIVE - Account group is active - full functionality of the Investment API is accessible.\n* CLOSING - Account group is closing.\n* CLOSED - Account group is closed.\n* LOCKED - Account group is locked for all actions.", "enum": [ "PENDING_APPROVAL", "ACTIVE", "CLOSING", "CLOSED", "LOCKED" ] }, "type": { "type": "string", "description": "Account group type.\n* PERSONAL - Account group of a person holding assets on their own behalf.\n* LEGAL_ENTITY - Account group of a legal entity holding assets on behalf of their users.\n* FRENCH_PEA - Account group of a french resident holding assets in Plan d'Epargne en Actions.\n* ISA - Account group of a UK resident holding assets in an individual savings account.\n* CHILD - Account group of a child user holding assets in a child account.", "enum": [ "PERSONAL", "LEGAL_ENTITY", "FRENCH_PEA", "ISA", "CHILD" ] }, "securities_account_number": { "title": "Securities Account number.", "type": "string", "description": "Account unique identifier.", "format": "^\\d{7,12}$" } }, "required": [ "id", "created_at", "updated_at", "users", "status", "type", "securities_account_number" ], "additionalProperties": false } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "example": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1, "sort": "created_at", "order": "ASC" }, "data": [ { "id": "9d95820d-4333-46b6-98de-04ab7512e76f", "created_at": "2020-08-24T14:15:22Z", "updated_at": "2020-08-24T14:15:22Z", "type": "PERSONAL", "status": "ACTIVE", "users": [ { "id": "9c36af78-91a0-4174-a515-fc81214e3dab", "type": "OWNER" } ], "securities_account_number": "123456789" } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/account_groups/{account_group_id}": { "parameters": [ { "name": "account_group_id", "in": "path", "required": true, "description": "The unique identifier of the account group. Universally Unique Identifier (UUID).", "schema": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_account_group", "summary": "Get an account group by ID", "description": "Returns the account group specified by its ID.", "tags": [ "Account Groups" ], "security": [ { "oauth-client-credentials": [ "accounts:read", "accounts:admin" ] } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Account Group - Retrieve - Response", "oneOf": [ { "title": "Account Group", "type": "object", "description": "", "properties": { "id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "type": { "type": "string", "description": "Relation type\n* OWNER - Account Group Owner\n* CHILD - Child Account Group Owner\n* GUARDIAN - Child Account Group Guardian", "enum": [ "OWNER", "CHILD", "GUARDIAN" ] } } } }, "status": { "type": "string", "description": "Status of the account group\n* PENDING_APPROVAL - Account group approval is pending - the account group is visible through our API but cannot be acted on.\n* ACTIVE - Account group is active - full functionality of the Investment API is accessible.\n* CLOSING - Account group is closing.\n* CLOSED - Account group is closed.\n* LOCKED - Account group is locked for all actions.", "enum": [ "PENDING_APPROVAL", "ACTIVE", "CLOSING", "CLOSED", "LOCKED" ] }, "type": { "type": "string", "description": "Account group type.\n* PERSONAL - Account group of a person holding assets on their own behalf.\n* LEGAL_ENTITY - Account group of a legal entity holding assets on behalf of their users.\n* FRENCH_PEA - Account group of a french resident holding assets in Plan d'Epargne en Actions.\n* ISA - Account group of a UK resident holding assets in an individual savings account.\n* CHILD - Account group of a child user holding assets in a child account.", "enum": [ "PERSONAL", "LEGAL_ENTITY", "FRENCH_PEA", "ISA", "CHILD" ] }, "securities_account_number": { "title": "Securities Account number.", "type": "string", "description": "Account unique identifier.", "format": "^\\d{7,12}$" } }, "required": [ "id", "created_at", "updated_at", "users", "status", "type", "securities_account_number" ], "additionalProperties": false }, { "title": "Business Account Group", "type": "object", "description": "", "properties": { "id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "business_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "status": { "type": "string", "description": "Status of the account group\n* PENDING_APPROVAL - Account group approval is pending - the account group is visible through our API but cannot be acted on.\n* ACTIVE - Account group is active - full functionality of the Investment API is accessible.\n* CLOSING - Account group is closing.\n* CLOSED - Account group is closed.\n* LOCKED - Account group is locked for all actions.", "enum": [ "PENDING_APPROVAL", "ACTIVE", "CLOSING", "CLOSED", "LOCKED" ] }, "type": { "type": "string", "description": "Account group type.\n* BUSINESS - Account group of a business holding assets.", "enum": [ "BUSINESS" ] }, "securities_account_number": { "title": "Securities Account number.", "type": "string", "description": "Account unique identifier.", "format": "^\\d{7,12}$" } }, "required": [ "id", "created_at", "updated_at", "business_id", "status", "type", "securities_account_number" ], "additionalProperties": false } ] }, "examples": { "User Account Group": { "summary": "User account group", "value": { "id": "9d95820d-4333-46b6-98de-04ab7512e76f", "created_at": "2020-08-24T14:15:22Z", "updated_at": "2020-08-24T14:15:22Z", "type": "PERSONAL", "status": "ACTIVE", "users": [ { "id": "413715f2-5401-4b97-8055-034a6b879f8c", "type": "OWNER" } ], "securities_account_number": "123456789" } }, "Business Account Group": { "summary": "Business account group", "value": { "id": "9d95820d-4333-46b6-98de-04ab7512e76f", "created_at": "2020-08-24T14:15:22Z", "updated_at": "2020-08-24T14:15:22Z", "type": "BUSINESS", "status": "ACTIVE", "business_id": "bc6f8c82-1234-4b56-a7d8-9e012345f678", "securities_account_number": "123456789" } } } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "delete": { "operationId": "account_group_closure", "summary": "Close an account group by ID", "description": "Initiates the closure request for an account group specified by its ID.", "parameters": [ { "name": "closure_reason", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "dunning", "power_of_attorney", "loss_of_legal_capacity", "aml", "risk_based", "contract_breach", "user_initiated" ] }, "description": "Records the reason for the account group closure." }, { "name": "notification_only", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Indicates whether the request notifies of an intended future closing." } ], "tags": [ "Account Groups" ], "security": [ { "oauth-client-credentials": [ "accounts:admin" ] } ], "responses": { "202": { "description": "The request has been successfully accepted and will be processed asynchronously.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "409": { "description": "Conflict. An operation is not available for the current state of the resource.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 409, "type": "conflict" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/account_groups/{account_group_id}/payments/cash_balance": { "parameters": [ { "name": "account_group_id", "in": "path", "required": true, "description": "The unique identifier of the account group. Universally Unique Identifier (UUID).", "schema": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_cash_balance", "summary": "Retrieve an account group's cash balance", "deprecated": true, "description": "Retrieve an account group's cash balance", "tags": [ "Cash Balances" ], "security": [ { "oauth-client-credentials": [ "positions:read" ] } ], "responses": { "200": { "description": "Response", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling\n* USD - The United States dollar", "enum": [ "EUR", "GBP", "USD" ] }, "balance": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "locked_for_trading": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "pending_settlement": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "available_for_withdrawal": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "available_for_trading": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" } }, "required": [ "account_group_id", "currency", "balance", "locked_for_trading", "pending_settlement", "available_for_withdrawal", "available_for_trading" ], "additionalProperties": false }, "examples": { "cash_balance": { "summary": "Cash Balance", "value": { "account_group_id": "d0fc0305-97b7-4e3b-bddf-66d3c434898c", "currency": "EUR", "balance": "100", "locked_for_trading": "10", "pending_settlement": "10", "available_for_withdrawal": "80", "available_for_trading": "80" } }, "nominal_buy_order_new_cash_balance_update": { "summary": "Cash Balance when Nominal Buy Order is still NEW", "value": { "account_group_id": "d0fc0305-97b7-4e3b-bddf-66d3c434898c", "currency": "EUR", "balance": "1000", "locked_for_trading": "1000", "pending_settlement": "0", "available_for_withdrawal": "0", "available_for_trading": "0" } }, "nominal_buy_order_filled_cash_balance_update": { "summary": "Cash Balance after Nominal Buy Order was filled", "value": { "account_group_id": "d0fc0305-97b7-4e3b-bddf-66d3c434898c", "currency": "EUR", "balance": "0", "locked_for_trading": "0", "pending_settlement": "0", "available_for_withdrawal": "0", "available_for_trading": "0" } }, "unit_sell_order_filled_cash_balance_update": { "summary": "Cash Balance after a Unit Sell Order was filled", "value": { "account_group_id": "d0fc0305-97b7-4e3b-bddf-66d3c434898c", "currency": "EUR", "balance": "828.75", "locked_for_trading": "0", "pending_settlement": "828.75", "available_for_withdrawal": "0", "available_for_trading": "828.75" } }, "cash_balance_available_before_withdrawal_request": { "summary": "Cash Balance available before withdrawal request", "value": { "account_group_id": "d0fc0305-97b7-4e3b-bddf-66d3c434898c", "currency": "EUR", "balance": "200", "locked_for_trading": "0", "pending_settlement": "0", "available_for_withdrawal": "200", "available_for_trading": "0" } } } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/account_groups/{account_group_id}/payments/cash_balances": { "parameters": [ { "name": "account_group_id", "in": "path", "required": true, "description": "The unique identifier of the account group. Universally Unique Identifier (UUID).", "schema": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_cash_balances", "summary": "Retrieve an account group's cash balances", "description": "Retrieve an account group's cash balances", "tags": [ "Cash Balances" ], "security": [ { "oauth-client-credentials": [ "positions:read" ] } ], "responses": { "200": { "description": "Response", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Cash Balances - Retrieve - Response", "type": "object", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling\n* USD - The United States dollar", "enum": [ "EUR", "GBP", "USD" ] }, "balance": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "locked_for_trading": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "pending_settlement": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "available_for_withdrawal": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "available_for_trading": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" } }, "required": [ "account_group_id", "currency", "balance", "locked_for_trading", "pending_settlement", "available_for_withdrawal", "available_for_trading" ], "additionalProperties": false } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "example": { "meta": { "count": 2, "total_count": 2, "offset": 0, "limit": 100 }, "data": [ { "account_group_id": "d0fc0305-97b7-4e3b-bddf-66d3c434898c", "currency": "EUR", "balance": "100", "locked_for_trading": "10", "pending_settlement": "10", "available_for_withdrawal": "80", "available_for_trading": "80" }, { "account_group_id": "d0fc0305-97b7-4e3b-bddf-66d3c434898c", "currency": "GBP", "balance": "250", "locked_for_trading": "0", "pending_settlement": "0", "available_for_withdrawal": "250", "available_for_trading": "250" }, { "account_group_id": "d0fc0305-97b7-4e3b-bddf-66d3c434898c", "currency": "GBP", "balance": "50", "locked_for_trading": "10", "pending_settlement": "0", "available_for_withdrawal": "40", "available_for_trading": "40" } ] } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/account_groups/{account_group_id}/payments/cash_balances/{currency}": { "parameters": [ { "name": "account_group_id", "in": "path", "required": true, "description": "The unique identifier of the account group. Universally Unique Identifier (UUID).", "schema": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } }, { "name": "currency", "in": "path", "required": true, "description": "The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) alphabetic currency code identifying the cash balance (e.g. `EUR`).", "schema": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling\n* USD - The United States dollar", "enum": [ "EUR", "GBP", "USD" ] } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_cash_balance_with_currency", "summary": "Retrieve an account group's cash balance for particular ISO currency code", "description": "Retrieve an account group's cash balance for particular ISO currency code", "tags": [ "Cash Balances" ], "security": [ { "oauth-client-credentials": [ "positions:read" ] } ], "responses": { "200": { "description": "Response", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling\n* USD - The United States dollar", "enum": [ "EUR", "GBP", "USD" ] }, "balance": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "locked_for_trading": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "pending_settlement": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "available_for_withdrawal": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "available_for_trading": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" } }, "required": [ "account_group_id", "currency", "balance", "locked_for_trading", "pending_settlement", "available_for_withdrawal", "available_for_trading" ], "additionalProperties": false }, "examples": { "cash_balance": { "summary": "Cash Balance", "value": { "account_group_id": "d0fc0305-97b7-4e3b-bddf-66d3c434898c", "currency": "EUR", "balance": "100", "locked_for_trading": "10", "pending_settlement": "10", "available_for_withdrawal": "80", "available_for_trading": "80" } }, "nominal_buy_order_new_cash_balance_update": { "summary": "Cash Balance when Nominal Buy Order is still NEW", "value": { "account_group_id": "d0fc0305-97b7-4e3b-bddf-66d3c434898c", "currency": "EUR", "balance": "1000", "locked_for_trading": "1000", "pending_settlement": "0", "available_for_withdrawal": "0", "available_for_trading": "0" } }, "nominal_buy_order_filled_cash_balance_update": { "summary": "Cash Balance after Nominal Buy Order was filled", "value": { "account_group_id": "d0fc0305-97b7-4e3b-bddf-66d3c434898c", "currency": "EUR", "balance": "0", "locked_for_trading": "0", "pending_settlement": "0", "available_for_withdrawal": "0", "available_for_trading": "0" } }, "unit_sell_order_filled_cash_balance_update": { "summary": "Cash Balance after a Unit Sell Order was filled", "value": { "account_group_id": "d0fc0305-97b7-4e3b-bddf-66d3c434898c", "currency": "EUR", "balance": "828.75", "locked_for_trading": "0", "pending_settlement": "828.75", "available_for_withdrawal": "0", "available_for_trading": "828.75" } }, "cash_balance_available_before_withdrawal_request": { "summary": "Cash Balance available before withdrawal request", "value": { "account_group_id": "d0fc0305-97b7-4e3b-bddf-66d3c434898c", "currency": "EUR", "balance": "200", "locked_for_trading": "0", "pending_settlement": "0", "available_for_withdrawal": "200", "available_for_trading": "0" } } } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/users/{user_id}/accounts": { "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "The unique identifier of the user. Universally Unique Identifier (UUID).", "schema": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_user_accounts", "summary": "Get user accounts", "description": "Lists the accounts of a user specified by ID.", "tags": [ "Accounts" ], "security": [ { "oauth-client-credentials": [ "accounts:read", "accounts:admin" ] } ], "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "updated_at" ], "default": "created_at" }, "description": "Sort the result by `created_at`, `updated_at`." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Accounts - List - Response", "type": "object", "description": "Paginated response containing the accounts owned by a user.", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "description": "List of the user's accounts", "items": { "title": "Account", "type": "object", "description": "", "properties": { "id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "type": { "type": "string", "description": "Account type.\n* TRADING - Orders in accounts of this type are created on a specific instrument basis.\n* PORTFOLIO - Orders in accounts of this type are created on a portfolio basis and additional portfolio functionality is available.", "enum": [ "TRADING", "PORTFOLIO" ] }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "type": { "type": "string", "description": "Relation type\n* OWNER - Account Group Owner\n* CHILD - Child Account Group Owner\n* GUARDIAN - Child Account Group Guardian", "enum": [ "OWNER", "GUARDIAN", "CHILD" ] } } } }, "account_number": { "type": "integer", "description": "The serial account number of the account in the account group.", "minimum": 1 }, "name": { "type": "string", "description": "The name of the account.", "maxLength": 100 }, "status": { "type": "string", "description": "The status of the account\n* PENDING_APPROVAL - Account approval is pending - the account is visible through our API but cannot be acted on.\n* ACTIVE - Account is active - full functionality of the Investment API is accessible.\n* CLOSING - Account is closing - only sell orders or the transfer of positions out are permissible before the account is closed.\n* CLOSED - Account is closed with zero balance successfully.\n* LOCKED - Account is locked for all actions.", "enum": [ "PENDING_APPROVAL", "ACTIVE", "CLOSING", "CLOSED", "LOCKED" ] } }, "required": [ "id", "created_at", "updated_at", "account_group_id", "type", "users", "name", "status", "account_number" ], "additionalProperties": false } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "example": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1, "sort": "created_at", "order": "ASC" }, "data": [ { "id": "ad45b27f-c0e7-4cfb-b48c-a83670dbdfbd", "created_at": "2020-08-24T14:15:22Z", "updated_at": "2020-08-24T14:15:22Z", "account_group_id": "fa2414ed-8d62-46fd-85ed-565a340c81d6", "type": "TRADING", "users": [ { "id": "9c36af78-91a0-4174-a515-fc81214e3dab", "type": "OWNER" } ], "account_number": 1, "name": "Main account", "status": "ACTIVE" } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/accounts/{account_id}": { "parameters": [ { "name": "account_id", "in": "path", "required": true, "description": "The unique identifier of the account. Universally Unique Identifier (UUID).", "schema": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_account", "summary": "Get account by ID", "description": "Returns the account specified by its ID.", "tags": [ "Accounts" ], "security": [ { "oauth-client-credentials": [ "accounts:read", "accounts:admin" ] } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Account - Retrieve - Response", "oneOf": [ { "title": "Account", "type": "object", "description": "", "properties": { "id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "type": { "type": "string", "description": "Account type.\n* TRADING - Orders in accounts of this type are created on a specific instrument basis.\n* PORTFOLIO - Orders in accounts of this type are created on a portfolio basis and additional portfolio functionality is available.", "enum": [ "TRADING", "PORTFOLIO" ] }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "type": { "type": "string", "description": "Relation type\n* OWNER - Account Group Owner\n* CHILD - Child Account Group Owner\n* GUARDIAN - Child Account Group Guardian", "enum": [ "OWNER", "GUARDIAN", "CHILD" ] } } } }, "account_number": { "type": "integer", "description": "The serial account number of the account in the account group.", "minimum": 1 }, "name": { "type": "string", "description": "The name of the account.", "maxLength": 100 }, "status": { "type": "string", "description": "The status of the account\n* PENDING_APPROVAL - Account approval is pending - the account is visible through our API but cannot be acted on.\n* ACTIVE - Account is active - full functionality of the Investment API is accessible.\n* CLOSING - Account is closing - only sell orders or the transfer of positions out are permissible before the account is closed.\n* CLOSED - Account is closed with zero balance successfully.\n* LOCKED - Account is locked for all actions.", "enum": [ "PENDING_APPROVAL", "ACTIVE", "CLOSING", "CLOSED", "LOCKED" ] } }, "required": [ "id", "created_at", "updated_at", "account_group_id", "type", "users", "name", "status", "account_number" ], "additionalProperties": false }, { "title": "Business Account", "type": "object", "description": "", "properties": { "id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "type": { "type": "string", "description": "Account type.\n* TRADING - Orders in accounts of this type are created on a specific instrument basis.\n* PORTFOLIO - Orders in accounts of this type are created on a portfolio basis and additional portfolio functionality is available.", "enum": [ "TRADING", "PORTFOLIO" ] }, "business_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "account_number": { "type": "integer", "description": "The serial account number of the account in the account group.", "minimum": 1 }, "name": { "type": "string", "description": "The name of the account.", "maxLength": 100 }, "status": { "type": "string", "description": "The status of the account\n* PENDING_APPROVAL - Account approval is pending - the account is visible through our API but cannot be acted on.\n* ACTIVE - Account is active - full functionality of the Investment API is accessible.\n* CLOSING - Account is closing - only sell orders or the transfer of positions out are permissible before the account is closed.\n* CLOSED - Account is closed with zero balance successfully.\n* LOCKED - Account is locked for all actions.", "enum": [ "PENDING_APPROVAL", "ACTIVE", "CLOSING", "CLOSED", "LOCKED" ] } }, "required": [ "id", "created_at", "updated_at", "account_group_id", "type", "business_id", "name", "status", "account_number" ], "additionalProperties": false } ] }, "examples": { "User Account": { "summary": "User account", "value": { "id": "ad45b27f-c0e7-4cfb-b48c-a83670dbdfbd", "created_at": "2020-08-24T14:15:22Z", "updated_at": "2020-08-24T14:15:22Z", "account_group_id": "fa2414ed-8d62-46fd-85ed-565a340c81d6", "type": "TRADING", "users": [ { "id": "9c36af78-91a0-4174-a515-fc81214e3dab", "type": "OWNER" } ], "account_number": 1, "name": "Main account", "status": "ACTIVE" } }, "Business Account": { "summary": "Business account", "value": { "id": "ad45b27f-c0e7-4cfb-b48c-a83670dbdfbd", "created_at": "2020-08-24T14:15:22Z", "updated_at": "2020-08-24T14:15:22Z", "account_group_id": "fa2414ed-8d62-46fd-85ed-565a340c81d6", "business_id": "bc6f8c82-1234-4b56-a7d8-9e012345f678", "type": "TRADING", "account_number": 1, "name": "Main account", "status": "ACTIVE" } } } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "patch": { "operationId": "update_account", "summary": "Update account by ID", "description": "Updates the account specified by its ID.", "tags": [ "Accounts" ], "security": [ { "oauth-client-credentials": [ "accounts:admin" ] } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Account - Update - Request", "type": "object", "properties": { "name": { "type": "string", "description": "The name of the account.", "maxLength": 100 } }, "additionalProperties": false }, "example": { "name": "Main account" } } } }, "responses": { "200": { "description": "Account updated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Account - Update - Response", "oneOf": [ { "title": "Account", "type": "object", "description": "", "properties": { "id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "type": { "type": "string", "description": "Account type.\n* TRADING - Orders in accounts of this type are created on a specific instrument basis.\n* PORTFOLIO - Orders in accounts of this type are created on a portfolio basis and additional portfolio functionality is available.", "enum": [ "TRADING", "PORTFOLIO" ] }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "type": { "type": "string", "description": "Relation type\n* OWNER - Account Group Owner\n* CHILD - Child Account Group Owner\n* GUARDIAN - Child Account Group Guardian", "enum": [ "OWNER", "GUARDIAN", "CHILD" ] } } } }, "account_number": { "type": "integer", "description": "The serial account number of the account in the account group.", "minimum": 1 }, "name": { "type": "string", "description": "The name of the account.", "maxLength": 100 }, "status": { "type": "string", "description": "The status of the account\n* PENDING_APPROVAL - Account approval is pending - the account is visible through our API but cannot be acted on.\n* ACTIVE - Account is active - full functionality of the Investment API is accessible.\n* CLOSING - Account is closing - only sell orders or the transfer of positions out are permissible before the account is closed.\n* CLOSED - Account is closed with zero balance successfully.\n* LOCKED - Account is locked for all actions.", "enum": [ "PENDING_APPROVAL", "ACTIVE", "CLOSING", "CLOSED", "LOCKED" ] } }, "required": [ "id", "created_at", "updated_at", "account_group_id", "type", "users", "name", "status", "account_number" ], "additionalProperties": false }, { "title": "Business Account", "type": "object", "description": "", "properties": { "id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "type": { "type": "string", "description": "Account type.\n* TRADING - Orders in accounts of this type are created on a specific instrument basis.\n* PORTFOLIO - Orders in accounts of this type are created on a portfolio basis and additional portfolio functionality is available.", "enum": [ "TRADING", "PORTFOLIO" ] }, "business_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "account_number": { "type": "integer", "description": "The serial account number of the account in the account group.", "minimum": 1 }, "name": { "type": "string", "description": "The name of the account.", "maxLength": 100 }, "status": { "type": "string", "description": "The status of the account\n* PENDING_APPROVAL - Account approval is pending - the account is visible through our API but cannot be acted on.\n* ACTIVE - Account is active - full functionality of the Investment API is accessible.\n* CLOSING - Account is closing - only sell orders or the transfer of positions out are permissible before the account is closed.\n* CLOSED - Account is closed with zero balance successfully.\n* LOCKED - Account is locked for all actions.", "enum": [ "PENDING_APPROVAL", "ACTIVE", "CLOSING", "CLOSED", "LOCKED" ] } }, "required": [ "id", "created_at", "updated_at", "account_group_id", "type", "business_id", "name", "status", "account_number" ], "additionalProperties": false } ] }, "examples": { "User Account": { "summary": "User account", "value": { "id": "ad45b27f-c0e7-4cfb-b48c-a83670dbdfbd", "created_at": "2020-08-24T14:15:22Z", "updated_at": "2020-08-24T14:15:22Z", "account_group_id": "fa2414ed-8d62-46fd-85ed-565a340c81d6", "type": "TRADING", "users": [ { "id": "9c36af78-91a0-4174-a515-fc81214e3dab", "type": "OWNER" } ], "account_number": 1, "name": "Main account", "status": "ACTIVE" } }, "Business Account": { "summary": "Business account", "value": { "id": "ad45b27f-c0e7-4cfb-b48c-a83670dbdfbd", "created_at": "2020-08-24T14:15:22Z", "updated_at": "2020-08-24T14:15:22Z", "account_group_id": "fa2414ed-8d62-46fd-85ed-565a340c81d6", "business_id": "bc6f8c82-1234-4b56-a7d8-9e012345f678", "type": "TRADING", "account_number": 1, "name": "Main account", "status": "ACTIVE" } } } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "delete": { "operationId": "account_closure", "summary": "Close account by ID", "description": "Initiates the closure request for an account specified by its ID.", "tags": [ "Accounts" ], "security": [ { "oauth-client-credentials": [ "accounts:admin" ] } ], "responses": { "202": { "description": "The request has been successfully accepted and will be processed asynchronously.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "409": { "description": "Conflict. An operation is not available for the current state of the resource.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 409, "type": "conflict" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/accounts/{account_id}/positions": { "parameters": [ { "name": "account_id", "in": "path", "required": true, "description": "The unique identifier of the account. Universally Unique Identifier (UUID).", "schema": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_positions", "summary": "List positions", "description": "List of account positions", "tags": [ "Positions" ], "security": [ { "oauth-client-credentials": [ "positions:read" ] } ], "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." } ], "responses": { "200": { "description": "Response", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Positions - List - Response", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "instrument": { "type": "object", "properties": { "uuid": { "type": "string", "description": "Instrument unique identifier.", "format": "uuid" }, "isin": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" } }, "required": [ "uuid" ], "additionalProperties": false }, "quantity": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "locked_for_trading": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "pending_settlement": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "available_for_trading": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "available_for_instruction": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "settled_quantity": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" } }, "required": [ "account_id", "instrument", "quantity", "locked_for_trading", "pending_settlement", "available_for_trading", "available_for_instruction", "settled_quantity" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] } }, "required": [ "data", "meta" ], "additionalProperties": false }, "example": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1, "sort": "id", "order": "ASC" }, "data": [ { "account_id": "c5161455-4d27-4781-bc74-f05532e49a77", "instrument": { "isin": "US0378331005", "uuid": "ccb86937-8a39-4160-8d33-85bf9e902321" }, "quantity": "10.4", "locked_for_trading": "5", "pending_settlement": "0", "available_for_trading": "5.4", "available_for_instruction": "5.4", "settled_quantity": "10.4" } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/accounts/{account_id}/positions/{instrument_id}": { "parameters": [ { "name": "instrument_id", "in": "path", "required": true, "description": "The unique identifier of the instrument, provided as either an `isin:` URN or a `uuid:` URN.", "schema": { "title": "Instrument unique identifier", "description": "Instrument unique identifier.", "oneOf": [ { "title": "International securities identification number with 'isin:' URN namespace", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number), prefixed with a 'isin:' [URN scheme](https://datatracker.ietf.org/doc/html/rfc8141).", "pattern": "^(urn:)?isin:[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, { "title": "Universally Unique IDentifier (UUID) with 'uuid:' URN scheme", "type": "string", "description": "Universally Unique IDentifier (UUID) with 'uuid:' URN namespace, defined by [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122).", "pattern": "^(urn:)?uuid:[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$" } ] } }, { "name": "account_id", "in": "path", "required": true, "description": "The unique identifier of the account. Universally Unique Identifier (UUID).", "schema": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_position", "summary": "Retrieve position", "description": "Retrieve an account position", "tags": [ "Positions" ], "security": [ { "oauth-client-credentials": [ "positions:read" ] } ], "responses": { "200": { "description": "Response", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "instrument": { "type": "object", "properties": { "uuid": { "type": "string", "description": "Instrument unique identifier.", "format": "uuid" }, "isin": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" } }, "required": [ "uuid" ], "additionalProperties": false }, "quantity": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "locked_for_trading": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "pending_settlement": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "available_for_trading": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "available_for_instruction": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "settled_quantity": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" } }, "required": [ "account_id", "instrument", "quantity", "locked_for_trading", "pending_settlement", "available_for_trading", "available_for_instruction", "settled_quantity" ], "additionalProperties": false }, "examples": { "position": { "summary": "Position Example", "value": { "account_id": "c5161455-4d27-4781-bc74-f05532e49a77", "instrument": { "isin": "US0378331005", "uuid": "ccb86937-8a39-4160-8d33-85bf9e902321" }, "quantity": "10.4", "locked_for_trading": "5", "pending_settlement": "0", "available_for_trading": "5.4", "available_for_instruction": "5.4", "settled_quantity": "10.4" } }, "unit_sell_order_new_and_filled_position_update": { "summary": "Position Example", "value": { "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3", "instrument": { "isin": "US0378331005", "uuid": "ccb86937-8a39-4160-8d33-85bf9e902321" }, "quantity": "10", "locked_for_trading": "10", "pending_settlement": "0", "available_for_trading": "0", "available_for_instruction": "0", "settled_quantity": "10" } }, "unit_sell_order_filled_position_update": { "summary": "Position Example", "value": { "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3", "instrument": { "isin": "US0378331005", "uuid": "ccb86937-8a39-4160-8d33-85bf9e902321" }, "quantity": "0", "locked_for_trading": "0", "pending_settlement": "0", "available_for_trading": "0", "available_for_instruction": "0", "settled_quantity": "0" } }, "nominal_buy_order_filled_positions_update": { "summary": "Position Example", "value": { "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3", "instrument": { "isin": "US0378331005", "uuid": "ccb86937-8a39-4160-8d33-85bf9e902321" }, "quantity": "11.734334663", "locked_for_trading": "0", "pending_settlement": "0", "available_for_trading": "11.734334663", "available_for_instruction": "11.734334663", "settled_quantity": "11.734334663" } } } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/users/{user_id}/payments/reference_accounts": { "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "The unique identifier of the user. Universally Unique Identifier (UUID).", "schema": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_reference_accounts", "summary": "Get reference accounts of a user", "description": "Returns the list of reference accounts of a user specified by ID.", "tags": [ "Reference Accounts" ], "security": [ { "oauth-client-credentials": [ "reference_accounts:admin", "reference_accounts:read" ] } ], "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "id", "created_at" ], "default": "created_at" }, "description": "Field of resource to sort by", "example": "id" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Users - List - Response", "type": "object", "description": "Paginated list of reference bank accounts for a user, including cursor-based pagination metadata.", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "items": { "title": "Reference Account", "type": "object", "description": "A verified reference bank account belonging to a user, used as the destination for cash withdrawals.", "properties": { "id": { "title": "Reference account unique identifier.", "type": "string", "description": "Reference account unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "business_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "account_owner": { "type": "string", "maxLength": 140, "description": "Name of the reference account holder" }, "name": { "type": "string", "maxLength": 100, "description": "Human-readable name of the reference bank account" }, "iban": { "title": "International Bank Account Number (IBAN)", "type": "string", "description": "Obfuscated International Bank Account Number [IBAN](https://en.wikipedia.org/wiki/International_Bank_Account_Number).", "pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{2}\\*{10}[A-Z0-9]{4}$" }, "bic": { "title": "Business Identifier Code", "type": "string", "description": "Business Identifier Code (also known as SWIFT-BIC, BIC, SWIFT ID or SWIFT code) [ISO 9362](https://en.wikipedia.org/wiki/ISO_9362).", "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$" }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp of when user validated the reference account" } }, "required": [ "id", "created_at", "updated_at", "account_owner", "name", "iban", "bic", "confirmed_at" ], "additionalProperties": false } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "examples": { "SEPA": { "summary": "SEPA Reference Account", "value": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1 }, "data": [ { "id": "c18f80bd-401e-4836-9776-7dc24c32d35e", "created_at": "2020-08-24T14:15:22Z", "updated_at": "2020-08-24T14:15:22Z", "user_id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be202", "account_owner": "Max Mustermann", "name": "Max's Reference Account", "iban": "DE0210**********0402", "bic": "BELADEBE", "confirmed_at": "2020-08-23T14:15:22Z" } ] } } } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/payments/reference_accounts": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "post": { "operationId": "create_reference_account", "summary": "Create a reference account", "description": "Creates a new reference account for a user or business specified by ID.", "tags": [ "Reference Accounts" ], "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$", "example": "ccb07f42-4104-44ad-8e1f-c660bb7b269c" }, "description": "A UUID to be used as an idempotency key. This prevents a duplicate request from being replayed.\nhttps://docs.upvest.co/documentation/concepts/api_concepts/idempotency\n" } ], "security": [ { "oauth-client-credentials": [ "reference_accounts:admin" ] } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Reference Account - Create - Request", "type": "object", "description": "Request body for registering a reference bank account. Exactly one of `user_id` or `business_id` must be provided.", "properties": { "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "business_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "account_owner": { "type": "string", "maxLength": 140, "description": "Name of the reference account holder" }, "name": { "type": "string", "maxLength": 100, "description": "Human-readable name of the reference bank account" }, "iban": { "title": "International Bank Account Number (IBAN)", "type": "string", "description": "International Bank Account Number [IBAN](https://en.wikipedia.org/wiki/International_Bank_Account_Number).", "pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,26}$" }, "bic": { "title": "Business Identifier Code", "type": "string", "description": "Business Identifier Code (also known as SWIFT-BIC, BIC, SWIFT ID or SWIFT code) [ISO 9362](https://en.wikipedia.org/wiki/ISO_9362).", "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$" }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp of when user validated the reference account" } }, "required": [ "account_owner", "iban", "bic", "confirmed_at" ], "additionalProperties": false }, "examples": { "SEPA": { "summary": "SEPA Reference Account (User)", "value": { "user_id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be202", "account_owner": "Max Mustermann", "name": "Max's Reference Account", "iban": "DE02100500000054540402", "bic": "BELADEBE", "confirmed_at": "2020-08-23T14:15:22Z" } }, "SEPA_Business": { "summary": "SEPA Reference Account (Business)", "value": { "business_id": "8f8a5c5e-2a3b-4c7d-bf9e-1d2e3f4a5b6c", "account_owner": "Acme GmbH", "name": "Acme Business Account", "iban": "DE02100500000054540402", "bic": "BELADEBE", "confirmed_at": "2020-08-23T14:15:22Z" } } } } } }, "responses": { "200": { "description": "Reference account created.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Reference Account", "type": "object", "description": "A verified reference bank account belonging to a user, used as the destination for cash withdrawals.", "properties": { "id": { "title": "Reference account unique identifier.", "type": "string", "description": "Reference account unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "business_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "account_owner": { "type": "string", "maxLength": 140, "description": "Name of the reference account holder" }, "name": { "type": "string", "maxLength": 100, "description": "Human-readable name of the reference bank account" }, "iban": { "title": "International Bank Account Number (IBAN)", "type": "string", "description": "Obfuscated International Bank Account Number [IBAN](https://en.wikipedia.org/wiki/International_Bank_Account_Number).", "pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{2}\\*{10}[A-Z0-9]{4}$" }, "bic": { "title": "Business Identifier Code", "type": "string", "description": "Business Identifier Code (also known as SWIFT-BIC, BIC, SWIFT ID or SWIFT code) [ISO 9362](https://en.wikipedia.org/wiki/ISO_9362).", "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$" }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp of when user validated the reference account" } }, "required": [ "id", "created_at", "updated_at", "account_owner", "name", "iban", "bic", "confirmed_at" ], "additionalProperties": false }, "examples": { "SEPA": { "summary": "SEPA Reference Account (User)", "value": { "id": "c18f80bd-401e-4836-9776-7dc24c32d35e", "created_at": "2020-08-24T14:15:22Z", "updated_at": "2020-08-24T14:15:22Z", "user_id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be202", "account_owner": "Max Mustermann", "name": "Max's Reference Account", "iban": "DE0210**********0402", "bic": "BELADEBE", "confirmed_at": "2020-08-23T14:15:22Z" } }, "SEPA_Business": { "summary": "SEPA Reference Account (Business)", "value": { "id": "c18f80bd-401e-4836-9776-7dc24c32d35e", "created_at": "2020-08-24T14:15:22Z", "updated_at": "2020-08-24T14:15:22Z", "business_id": "8f8a5c5e-2a3b-4c7d-bf9e-1d2e3f4a5b6c", "account_owner": "Acme GmbH", "name": "Acme Business Account", "iban": "DE0210**********0402", "bic": "BELADEBE", "confirmed_at": "2020-08-23T14:15:22Z" } } } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/payments/reference_accounts/{reference_account_id}": { "parameters": [ { "name": "reference_account_id", "in": "path", "required": true, "description": "The unique identifier of the reference (external bank) account. Universally Unique Identifier (UUID).", "schema": { "title": "Reference account unique identifier.", "type": "string", "description": "Reference account unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_reference_account", "summary": "Get a reference account by ID", "description": "Retrieves the reference account specified by its ID.", "tags": [ "Reference Accounts" ], "security": [ { "oauth-client-credentials": [ "reference_accounts:admin", "reference_accounts:read" ] } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Reference Account", "type": "object", "description": "A verified reference bank account belonging to a user, used as the destination for cash withdrawals.", "properties": { "id": { "title": "Reference account unique identifier.", "type": "string", "description": "Reference account unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "business_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "account_owner": { "type": "string", "maxLength": 140, "description": "Name of the reference account holder" }, "name": { "type": "string", "maxLength": 100, "description": "Human-readable name of the reference bank account" }, "iban": { "title": "International Bank Account Number (IBAN)", "type": "string", "description": "Obfuscated International Bank Account Number [IBAN](https://en.wikipedia.org/wiki/International_Bank_Account_Number).", "pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{2}\\*{10}[A-Z0-9]{4}$" }, "bic": { "title": "Business Identifier Code", "type": "string", "description": "Business Identifier Code (also known as SWIFT-BIC, BIC, SWIFT ID or SWIFT code) [ISO 9362](https://en.wikipedia.org/wiki/ISO_9362).", "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$" }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp of when user validated the reference account" } }, "required": [ "id", "created_at", "updated_at", "account_owner", "name", "iban", "bic", "confirmed_at" ], "additionalProperties": false }, "examples": { "SEPA": { "summary": "SEPA Reference Account", "value": { "id": "c18f80bd-401e-4836-9776-7dc24c32d35e", "created_at": "2020-08-24T14:15:22Z", "updated_at": "2020-08-24T14:15:22Z", "user_id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be202", "account_owner": "Max Mustermann", "name": "Max's Reference Account", "iban": "DE0210**********0402", "bic": "BELADEBE", "confirmed_at": "2020-08-23T14:15:22Z" } } } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "delete": { "operationId": "delete_reference_account", "summary": "Delete a reference account by ID", "description": "Deletes the reference account specified by its ID.", "tags": [ "Reference Accounts" ], "security": [ { "oauth-client-credentials": [ "reference_accounts:admin" ] } ], "responses": { "204": { "description": "Request has been processed successfully.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/users/{user_id}/payments/mandates": { "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "The unique identifier of the user. Universally Unique Identifier (UUID).", "schema": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_mandates", "summary": "List mandates", "description": "Returns a paginated list of direct debit mandates for the user specified by their ID.", "tags": [ "Mandates" ], "security": [ { "oauth-client-credentials": [ "mandates:admin", "mandates:read" ] } ], "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "id", "created_at" ], "default": "created_at" }, "description": "Field of resource to sort by", "example": "id" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." } ], "responses": { "200": { "description": "Mandates list", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Mandates - List - Response", "type": "object", "description": "Paginated list of direct debit mandates for a user, including cursor-based pagination metadata.", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "items": { "title": "Direct Debit Mandate", "type": "object", "description": "Represents a SEPA Direct Debit mandate authorising Upvest to debit funds from the end user's registered bank account. Only `RECURRENT` mandates are currently supported.", "properties": { "id": { "title": "Direct Debit Mandate unique identifier.", "type": "string", "description": "Direct Debit Mandate unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "business_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "iban": { "title": "International Bank Account Number (IBAN)", "type": "string", "description": "Obfuscated International Bank Account Number [IBAN](https://en.wikipedia.org/wiki/International_Bank_Account_Number).", "pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{2}\\*{10}[A-Z0-9]{4}$" }, "bic": { "title": "Business Identifier Code", "type": "string", "description": "Business Identifier Code (also known as SWIFT-BIC, BIC, SWIFT ID or SWIFT code) [ISO 9362](https://en.wikipedia.org/wiki/ISO_9362).", "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$" }, "creditor_name": { "type": "string", "maxLength": 100, "description": "Name of the creditor on the mandate." }, "creditor_id": { "type": "string", "maxLength": 20, "description": "Banking identifier of the creditor." }, "creditor_address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, "type": { "type": "string", "maxLength": 10, "enum": [ "RECURRENT" ], "default": "RECURRENT", "description": "Type of mandate.\n* RECURRENT - " }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp of when user validated the mandate" } }, "required": [ "id", "created_at", "iban", "bic", "creditor_name", "creditor_id", "creditor_address", "type", "confirmed_at" ], "additionalProperties": false } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "example": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1, "sort": "id", "order": "ASC" }, "data": [ { "id": "9c5a7dea-46f2-4502-b6b5-9902a53860e4", "created_at": "2020-08-24T14:15:22Z", "user_id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be202", "iban": "DE8900**********0000", "bic": "ABCDEXXX", "creditor_name": "Creditor Company", "creditor_id": "DE98ZZZ09999999999", "creditor_address": { "address_line1": "Strasse 1", "address_line2": "Company GmbH", "postcode": "12345", "city": "Berlin", "state": "BE", "country": "DE" }, "type": "RECURRENT", "confirmed_at": "2021-12-08T08:38:48.021Z" } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/businesses/{business_id}/payments/mandates": { "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "The unique identifier of the business. Universally Unique Identifier (UUID).", "schema": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_business_mandates", "summary": "List mandates for a business", "description": "Returns a paginated list of direct debit mandates for the business specified by its ID.", "tags": [ "Mandates" ], "security": [ { "oauth-client-credentials": [ "mandates:admin", "mandates:read" ] } ], "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "id", "created_at" ], "default": "created_at" }, "description": "Field of resource to sort by", "example": "id" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." } ], "responses": { "200": { "description": "Mandates list", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Mandates - List (Business) - Response", "type": "object", "description": "Paginated list of direct debit mandates for a business, including cursor-based pagination metadata.", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "items": { "title": "Direct Debit Mandate", "type": "object", "description": "Represents a SEPA Direct Debit mandate authorising Upvest to debit funds from the end user's registered bank account. Only `RECURRENT` mandates are currently supported.", "properties": { "id": { "title": "Direct Debit Mandate unique identifier.", "type": "string", "description": "Direct Debit Mandate unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "business_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "iban": { "title": "International Bank Account Number (IBAN)", "type": "string", "description": "Obfuscated International Bank Account Number [IBAN](https://en.wikipedia.org/wiki/International_Bank_Account_Number).", "pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{2}\\*{10}[A-Z0-9]{4}$" }, "bic": { "title": "Business Identifier Code", "type": "string", "description": "Business Identifier Code (also known as SWIFT-BIC, BIC, SWIFT ID or SWIFT code) [ISO 9362](https://en.wikipedia.org/wiki/ISO_9362).", "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$" }, "creditor_name": { "type": "string", "maxLength": 100, "description": "Name of the creditor on the mandate." }, "creditor_id": { "type": "string", "maxLength": 20, "description": "Banking identifier of the creditor." }, "creditor_address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, "type": { "type": "string", "maxLength": 10, "enum": [ "RECURRENT" ], "default": "RECURRENT", "description": "Type of mandate.\n* RECURRENT - " }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp of when user validated the mandate" } }, "required": [ "id", "created_at", "iban", "bic", "creditor_name", "creditor_id", "creditor_address", "type", "confirmed_at" ], "additionalProperties": false } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "example": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1, "sort": "id", "order": "ASC" }, "data": [ { "id": "9c5a7dea-46f2-4502-b6b5-9902a53860e4", "created_at": "2020-08-24T14:15:22Z", "business_id": "b3e4f5a6-1234-4c78-9abc-def012345678", "iban": "DE8900**********0000", "bic": "ABCDEXXX", "creditor_name": "Creditor Company", "creditor_id": "DE98ZZZ09999999999", "creditor_address": { "address_line1": "Strasse 1", "address_line2": "Company GmbH", "postcode": "12345", "city": "Berlin", "state": "BE", "country": "DE" }, "type": "RECURRENT", "confirmed_at": "2021-12-08T08:38:48.021Z" } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/payments/mandates": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "post": { "operationId": "create_mandate", "summary": "Create a mandate", "description": "Create a mandate.\n\nSupports both user and business accounts. Provide `user_id` for user flows or `business_id` for business flows — exactly one must be specified.", "tags": [ "Mandates" ], "security": [ { "oauth-client-credentials": [ "mandates:admin" ] } ], "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$", "example": "ccb07f42-4104-44ad-8e1f-c660bb7b269c" }, "description": "A UUID to be used as an idempotency key. This prevents a duplicate request from being replayed.\nhttps://docs.upvest.co/documentation/concepts/api_concepts/idempotency\n" } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Mandate - Create - Request", "type": "object", "description": "Request body for creating a direct debit mandate. Exactly one of `user_id` or `business_id` must be provided.", "properties": { "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "business_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "iban": { "title": "International Bank Account Number (IBAN)", "type": "string", "description": "International Bank Account Number [IBAN](https://en.wikipedia.org/wiki/International_Bank_Account_Number).", "pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,26}$" }, "bic": { "title": "Business Identifier Code", "type": "string", "description": "Business Identifier Code (also known as SWIFT-BIC, BIC, SWIFT ID or SWIFT code) [ISO 9362](https://en.wikipedia.org/wiki/ISO_9362).", "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$" }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp of when user validated the mandate" } }, "required": [ "iban", "bic", "confirmed_at" ], "additionalProperties": false }, "examples": { "User": { "summary": "User account mandate", "value": { "user_id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be202", "iban": "DE89000000000000000000", "bic": "ABCDEXXX", "confirmed_at": "2021-12-08T08:38:48.021Z" } }, "Business": { "summary": "Business account mandate", "value": { "business_id": "b3e4f5a6-1234-4c78-9abc-def012345678", "iban": "DE89000000000000000000", "bic": "ABCDEXXX", "confirmed_at": "2021-12-08T08:38:48.021Z" } } } } } }, "responses": { "200": { "description": "Mandate", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Direct Debit Mandate", "type": "object", "description": "Represents a SEPA Direct Debit mandate authorising Upvest to debit funds from the end user's registered bank account. Only `RECURRENT` mandates are currently supported.", "properties": { "id": { "title": "Direct Debit Mandate unique identifier.", "type": "string", "description": "Direct Debit Mandate unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "business_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "iban": { "title": "International Bank Account Number (IBAN)", "type": "string", "description": "Obfuscated International Bank Account Number [IBAN](https://en.wikipedia.org/wiki/International_Bank_Account_Number).", "pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{2}\\*{10}[A-Z0-9]{4}$" }, "bic": { "title": "Business Identifier Code", "type": "string", "description": "Business Identifier Code (also known as SWIFT-BIC, BIC, SWIFT ID or SWIFT code) [ISO 9362](https://en.wikipedia.org/wiki/ISO_9362).", "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$" }, "creditor_name": { "type": "string", "maxLength": 100, "description": "Name of the creditor on the mandate." }, "creditor_id": { "type": "string", "maxLength": 20, "description": "Banking identifier of the creditor." }, "creditor_address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, "type": { "type": "string", "maxLength": 10, "enum": [ "RECURRENT" ], "default": "RECURRENT", "description": "Type of mandate.\n* RECURRENT - " }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp of when user validated the mandate" } }, "required": [ "id", "created_at", "iban", "bic", "creditor_name", "creditor_id", "creditor_address", "type", "confirmed_at" ], "additionalProperties": false }, "examples": { "User": { "summary": "User account mandate", "value": { "id": "9c5a7dea-46f2-4502-b6b5-9902a53860e4", "created_at": "2020-08-24T14:15:22Z", "user_id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be202", "iban": "DE8900**********0000", "bic": "ABCDEXXX", "creditor_name": "Creditor Company", "creditor_id": "DE98ZZZ09999999999", "creditor_address": { "address_line1": "Strasse 1", "address_line2": "Company GmbH", "postcode": "12345", "city": "Berlin", "state": "BE", "country": "DE" }, "type": "RECURRENT", "confirmed_at": "2021-12-08T08:38:48.021Z" } }, "Business": { "summary": "Business account mandate", "value": { "id": "9c5a7dea-46f2-4502-b6b5-9902a53860e4", "created_at": "2020-08-24T14:15:22Z", "business_id": "b3e4f5a6-1234-4c78-9abc-def012345678", "iban": "DE8900**********0000", "bic": "ABCDEXXX", "creditor_name": "Creditor Company", "creditor_id": "DE98ZZZ09999999999", "creditor_address": { "address_line1": "Strasse 1", "address_line2": "Company GmbH", "postcode": "12345", "city": "Berlin", "state": "BE", "country": "DE" }, "type": "RECURRENT", "confirmed_at": "2021-12-08T08:38:48.021Z" } } } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/payments/mandates/{mandate_id}": { "parameters": [ { "name": "mandate_id", "in": "path", "required": true, "description": "The unique identifier of the direct debit mandate. Universally Unique Identifier (UUID).", "schema": { "title": "Direct Debit Mandate unique identifier.", "type": "string", "description": "Direct Debit Mandate unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_mandate", "summary": "Retrieve a direct debit mandate", "description": "Retrieve a direct debit mandate.\n\nThe response contains either `user_id` or `business_id` depending on whether the mandate belongs to a user or business account.", "tags": [ "Mandates" ], "security": [ { "oauth-client-credentials": [ "mandates:admin", "mandates:read" ] } ], "responses": { "200": { "description": "Mandate", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Direct Debit Mandate", "type": "object", "description": "Represents a SEPA Direct Debit mandate authorising Upvest to debit funds from the end user's registered bank account. Only `RECURRENT` mandates are currently supported.", "properties": { "id": { "title": "Direct Debit Mandate unique identifier.", "type": "string", "description": "Direct Debit Mandate unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "business_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "iban": { "title": "International Bank Account Number (IBAN)", "type": "string", "description": "Obfuscated International Bank Account Number [IBAN](https://en.wikipedia.org/wiki/International_Bank_Account_Number).", "pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{2}\\*{10}[A-Z0-9]{4}$" }, "bic": { "title": "Business Identifier Code", "type": "string", "description": "Business Identifier Code (also known as SWIFT-BIC, BIC, SWIFT ID or SWIFT code) [ISO 9362](https://en.wikipedia.org/wiki/ISO_9362).", "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$" }, "creditor_name": { "type": "string", "maxLength": 100, "description": "Name of the creditor on the mandate." }, "creditor_id": { "type": "string", "maxLength": 20, "description": "Banking identifier of the creditor." }, "creditor_address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, "type": { "type": "string", "maxLength": 10, "enum": [ "RECURRENT" ], "default": "RECURRENT", "description": "Type of mandate.\n* RECURRENT - " }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp of when user validated the mandate" } }, "required": [ "id", "created_at", "iban", "bic", "creditor_name", "creditor_id", "creditor_address", "type", "confirmed_at" ], "additionalProperties": false }, "examples": { "User": { "summary": "User account mandate", "value": { "id": "9c5a7dea-46f2-4502-b6b5-9902a53860e4", "created_at": "2020-08-24T14:15:22Z", "user_id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be202", "iban": "DE8900**********0000", "bic": "ABCDEXXX", "creditor_name": "Creditor Company", "creditor_id": "DE98ZZZ09999999999", "creditor_address": { "address_line1": "Strasse 1", "address_line2": "Company GmbH", "postcode": "12345", "city": "Berlin", "state": "BE", "country": "DE" }, "type": "RECURRENT", "confirmed_at": "2021-12-08T08:38:48.021Z" } }, "Business": { "summary": "Business account mandate", "value": { "id": "9c5a7dea-46f2-4502-b6b5-9902a53860e4", "created_at": "2020-08-24T14:15:22Z", "business_id": "b3e4f5a6-1234-4c78-9abc-def012345678", "iban": "DE8900**********0000", "bic": "ABCDEXXX", "creditor_name": "Creditor Company", "creditor_id": "DE98ZZZ09999999999", "creditor_address": { "address_line1": "Strasse 1", "address_line2": "Company GmbH", "postcode": "12345", "city": "Berlin", "state": "BE", "country": "DE" }, "type": "RECURRENT", "confirmed_at": "2021-12-08T08:38:48.021Z" } } } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "delete": { "operationId": "delete_mandate", "summary": "Delete mandate", "description": "Deletes the direct debit mandate specified by its ID. Deletion permanently removes the mandate; associated direct debits already in progress are not affected.", "tags": [ "Mandates" ], "security": [ { "oauth-client-credentials": [ "mandates:admin" ] } ], "responses": { "204": { "description": "Request has been processed successfully.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/account_groups/{account_group_id}/payments/direct_debits": { "parameters": [ { "name": "account_group_id", "in": "path", "required": true, "description": "The unique identifier of the account group. Universally Unique Identifier (UUID).", "schema": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_direct_debits", "summary": "List direct debits", "description": "Returns a paginated list of direct debits for the account group specified by its ID.", "tags": [ "Direct Debits" ], "security": [ { "oauth-client-credentials": [ "payments:admin", "payments:read" ] } ], "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "id", "created_at" ], "default": "created_at" }, "description": "Field of resource to sort by", "example": "id" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." } ], "responses": { "200": { "description": "Direct debits list", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Payments - Direct Debits List - Response", "type": "object", "description": "Paginated list of direct debits for an account group, including cursor-based pagination metadata.", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "items": { "type": "object", "description": "Represents a SEPA Direct Debit funding request for an account group. Debits are initiated via a mandate and transition through `NEW` → `PROCESSING` → `CONFIRMED` or `CANCELLED` as they are processed.", "properties": { "id": { "title": "Direct debit funding request unique identifier", "type": "string", "description": "Direct debit funding request unique identifier", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "allOf": [ { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" } ], "description": "The ID of the user. For business-initiated direct debits, this field will be absent.", "deprecated": true }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "mandate_id": { "title": "Direct Debit Mandate unique identifier.", "type": "string", "description": "Direct Debit Mandate unique identifier.", "format": "uuid" }, "cash_amount": { "type": "string", "pattern": "^-?[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "remittance_information": { "type": "string", "maxLength": 140, "pattern": "^[0-9A-Za-z+?/\\-:()\\.,';_ ]{0,140}$", "description": "Payment reference the end user will see in their bank statement for the corresponding direct debit booking (“Verwendungszweck”). We recommend that you keep this info concise and avoid special characters or non-standardised formatting ([see more](/documentation/guides/payments/direct_debit/direct_debit_submitting))." }, "status": { "type": "string", "description": "Status of the direct debit\n* NEW - Direct debit is created but not started processing.\n* PROCESSING - Direct debit is in processing.\n* CONFIRMED - Direct debit was successfully processed.\n* CANCELLED - Direct debit was cancelled.", "enum": [ "NEW", "PROCESSING", "CONFIRMED", "CANCELLED" ] }, "cancellation_reason": { "title": "Cancellation reason code for direct debit", "description": "Reason the direct debit was cancelled. The field is present in case the direct debit has a status of CANCELLED.\n* CANCELLED_BY_BANK - The payment was not completed by your bank. Please check your account details or contact support.\n* CANCELLED_BY_UPVEST - The payment was cancelled. Contact support for details.\n* CANCELLED_BY_CLIENT - The payment was cancelled at your request.\n* OTHER - Reason not available (applies to historical data only).", "type": "string", "enum": [ "CANCELLED_BY_BANK", "CANCELLED_BY_UPVEST", "CANCELLED_BY_CLIENT", "OTHER" ] }, "purpose_code": { "type": "string", "maxLength": 4, "description": "Purpose of the payment based on *ExternalPurpose1Code* from [ISO 20022](https://www.iso20022.org/catalogue-messages/additional-content-messages/external-code-sets)." } }, "required": [ "id", "created_at", "account_group_id", "mandate_id", "cash_amount", "currency" ], "additionalProperties": false } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "example": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1, "sort": "id", "order": "ASC" }, "data": [ { "id": "1ab4fef9-a097-4c6f-9345-647025d5fde6", "created_at": "2020-08-24T14:15:22Z", "user_id": "82b49999-1145-4e05-916a-567662daa7bc", "account_group_id": "1ea60f56-b67b-61fc-829a-0242ac130003", "mandate_id": "730b8719-0bc6-401d-98dd-b2de72afbf05", "cash_amount": "200.00", "currency": "EUR", "remittance_information": "payment for green energy portfolio", "status": "NEW", "purpose_code": "OTHR" } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/payments/direct_debits": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "post": { "operationId": "create_direct_debit", "summary": "Trigger a direct debit", "description": "Trigger a direct debit.\n\n**Deprecation notice:** The `user_id` field is deprecated, optional, and will be removed in a future version. For business account direct debits, ownership is determined by the mandate linked to the business.", "tags": [ "Direct Debits" ], "security": [ { "oauth-client-credentials": [ "payments:admin" ] } ], "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$", "example": "ccb07f42-4104-44ad-8e1f-c660bb7b269c" }, "description": "A UUID to be used as an idempotency key. This prevents a duplicate request from being replayed.\nhttps://docs.upvest.co/documentation/concepts/api_concepts/idempotency\n" } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Payments - Direct Debit - Create - Request", "type": "object", "description": "Request body for initiating a SEPA Direct Debit. Requires a valid `mandate_id` and the `account_group_id` of the account group to receive the funds.", "properties": { "user_id": { "allOf": [ { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" } ], "description": "The ID of the user. This field is optional and will be removed in a future version.", "deprecated": true }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "mandate_id": { "title": "Direct Debit Mandate unique identifier.", "type": "string", "description": "Direct Debit Mandate unique identifier.", "format": "uuid" }, "cash_amount": { "type": "string", "pattern": "^-?[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "remittance_information": { "type": "string", "maxLength": 140, "pattern": "^[0-9A-Za-z+?/\\-:()\\.,';_ ]{0,140}$", "description": "Payment reference the end user will see in their bank statement for the corresponding direct debit booking (“Verwendungszweck”). We recommend that you keep this info concise and avoid special characters or non-standardised formatting ([see more](/documentation/guides/payments/direct_debit/direct_debit_submitting))." }, "purpose_code": { "type": "string", "maxLength": 4, "description": "Purpose of the payment based on *ExternalPurpose1Code* from [ISO 20022](https://www.iso20022.org/catalogue-messages/additional-content-messages/external-code-sets)." } }, "required": [ "account_group_id", "mandate_id", "cash_amount" ], "additionalProperties": false }, "example": { "user_id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be202", "account_group_id": "1ea60f56-b67b-61fc-829a-0242ac130003", "mandate_id": "95b8304e-19fc-4cd9-8e50-82532e6b8d8c", "cash_amount": "200.00", "currency": "EUR", "remittance_information": "payment for green energy portfolio", "purpose_code": "OTHR" } } } }, "responses": { "200": { "description": "Direct debit", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "type": "object", "description": "Represents a SEPA Direct Debit funding request for an account group. Debits are initiated via a mandate and transition through `NEW` → `PROCESSING` → `CONFIRMED` or `CANCELLED` as they are processed.", "properties": { "id": { "title": "Direct debit funding request unique identifier", "type": "string", "description": "Direct debit funding request unique identifier", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "allOf": [ { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" } ], "description": "The ID of the user. For business-initiated direct debits, this field will be absent.", "deprecated": true }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "mandate_id": { "title": "Direct Debit Mandate unique identifier.", "type": "string", "description": "Direct Debit Mandate unique identifier.", "format": "uuid" }, "cash_amount": { "type": "string", "pattern": "^-?[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "remittance_information": { "type": "string", "maxLength": 140, "pattern": "^[0-9A-Za-z+?/\\-:()\\.,';_ ]{0,140}$", "description": "Payment reference the end user will see in their bank statement for the corresponding direct debit booking (“Verwendungszweck”). We recommend that you keep this info concise and avoid special characters or non-standardised formatting ([see more](/documentation/guides/payments/direct_debit/direct_debit_submitting))." }, "status": { "type": "string", "description": "Status of the direct debit\n* NEW - Direct debit is created but not started processing.\n* PROCESSING - Direct debit is in processing.\n* CONFIRMED - Direct debit was successfully processed.\n* CANCELLED - Direct debit was cancelled.", "enum": [ "NEW", "PROCESSING", "CONFIRMED", "CANCELLED" ] }, "cancellation_reason": { "title": "Cancellation reason code for direct debit", "description": "Reason the direct debit was cancelled. The field is present in case the direct debit has a status of CANCELLED.\n* CANCELLED_BY_BANK - The payment was not completed by your bank. Please check your account details or contact support.\n* CANCELLED_BY_UPVEST - The payment was cancelled. Contact support for details.\n* CANCELLED_BY_CLIENT - The payment was cancelled at your request.\n* OTHER - Reason not available (applies to historical data only).", "type": "string", "enum": [ "CANCELLED_BY_BANK", "CANCELLED_BY_UPVEST", "CANCELLED_BY_CLIENT", "OTHER" ] }, "purpose_code": { "type": "string", "maxLength": 4, "description": "Purpose of the payment based on *ExternalPurpose1Code* from [ISO 20022](https://www.iso20022.org/catalogue-messages/additional-content-messages/external-code-sets)." } }, "required": [ "id", "created_at", "account_group_id", "mandate_id", "cash_amount", "currency" ], "additionalProperties": false }, "example": { "id": "1ab4fef9-a097-4c6f-9345-647025d5fde6", "created_at": "2020-08-24T14:15:22Z", "user_id": "82b49999-1145-4e05-916a-567662daa7bc", "account_group_id": "1ea60f56-b67b-61fc-829a-0242ac130003", "mandate_id": "730b8719-0bc6-401d-98dd-b2de72afbf05", "cash_amount": "200.00", "currency": "EUR", "status": "NEW", "purpose_code": "OTHR" } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/payments/direct_debits/{direct_debit_id}": { "parameters": [ { "name": "direct_debit_id", "in": "path", "required": true, "description": "The unique identifier of the direct debit. Universally Unique Identifier (UUID).", "schema": { "title": "Direct debit funding request unique identifier", "type": "string", "description": "Direct debit funding request unique identifier", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_direct_debit", "summary": "Retrieve a direct debit", "description": "Returns the direct debit specified by its ID, including its current status, cash amount, mandate reference, and any cancellation reason.", "tags": [ "Direct Debits" ], "security": [ { "oauth-client-credentials": [ "payments:admin", "payments:read" ] } ], "responses": { "200": { "description": "Direct debit payment", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "type": "object", "description": "Represents a SEPA Direct Debit funding request for an account group. Debits are initiated via a mandate and transition through `NEW` → `PROCESSING` → `CONFIRMED` or `CANCELLED` as they are processed.", "properties": { "id": { "title": "Direct debit funding request unique identifier", "type": "string", "description": "Direct debit funding request unique identifier", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "allOf": [ { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" } ], "description": "The ID of the user. For business-initiated direct debits, this field will be absent.", "deprecated": true }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "mandate_id": { "title": "Direct Debit Mandate unique identifier.", "type": "string", "description": "Direct Debit Mandate unique identifier.", "format": "uuid" }, "cash_amount": { "type": "string", "pattern": "^-?[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "remittance_information": { "type": "string", "maxLength": 140, "pattern": "^[0-9A-Za-z+?/\\-:()\\.,';_ ]{0,140}$", "description": "Payment reference the end user will see in their bank statement for the corresponding direct debit booking (“Verwendungszweck”). We recommend that you keep this info concise and avoid special characters or non-standardised formatting ([see more](/documentation/guides/payments/direct_debit/direct_debit_submitting))." }, "status": { "type": "string", "description": "Status of the direct debit\n* NEW - Direct debit is created but not started processing.\n* PROCESSING - Direct debit is in processing.\n* CONFIRMED - Direct debit was successfully processed.\n* CANCELLED - Direct debit was cancelled.", "enum": [ "NEW", "PROCESSING", "CONFIRMED", "CANCELLED" ] }, "cancellation_reason": { "title": "Cancellation reason code for direct debit", "description": "Reason the direct debit was cancelled. The field is present in case the direct debit has a status of CANCELLED.\n* CANCELLED_BY_BANK - The payment was not completed by your bank. Please check your account details or contact support.\n* CANCELLED_BY_UPVEST - The payment was cancelled. Contact support for details.\n* CANCELLED_BY_CLIENT - The payment was cancelled at your request.\n* OTHER - Reason not available (applies to historical data only).", "type": "string", "enum": [ "CANCELLED_BY_BANK", "CANCELLED_BY_UPVEST", "CANCELLED_BY_CLIENT", "OTHER" ] }, "purpose_code": { "type": "string", "maxLength": 4, "description": "Purpose of the payment based on *ExternalPurpose1Code* from [ISO 20022](https://www.iso20022.org/catalogue-messages/additional-content-messages/external-code-sets)." } }, "required": [ "id", "created_at", "account_group_id", "mandate_id", "cash_amount", "currency" ], "additionalProperties": false }, "examples": { "ordinary": { "summary": "Ordinary", "value": { "id": "1ab4fef9-a097-4c6f-9345-647025d5fde6", "created_at": "2020-08-24T14:15:22Z", "user_id": "82b49999-1145-4e05-916a-567662daa7bc", "account_group_id": "1ea60f56-b67b-61fc-829a-0242ac130003", "mandate_id": "730b8719-0bc6-401d-98dd-b2de72afbf05", "cash_amount": "200.00", "currency": "EUR", "remittance_information": "payment for green energy portfolio", "status": "NEW", "purpose_code": "OTHR" } }, "cancelled": { "summary": "Cancelled", "value": { "id": "1ab4fef9-a097-4c6f-9345-647025d5fde6", "created_at": "2020-08-24T14:15:22Z", "user_id": "82b49999-1145-4e05-916a-567662daa7bc", "account_group_id": "1ea60f56-b67b-61fc-829a-0242ac130003", "mandate_id": "730b8719-0bc6-401d-98dd-b2de72afbf05", "cash_amount": "200.00", "currency": "EUR", "remittance_information": "payment for green energy portfolio", "status": "CANCELLED", "cancellation_reason": "CANCELLED_BY_UPVEST", "purpose_code": "OTHR" } } } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/account_groups/{account_group_id}/payments/topups": { "parameters": [ { "name": "account_group_id", "in": "path", "required": true, "description": "The unique identifier of the account group. Universally Unique Identifier (UUID).", "schema": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_topups", "summary": "List top-ups", "description": "Returns a list of top-ups.", "tags": [ "Top-ups" ], "security": [ { "oauth-client-credentials": [ "topups:admin", "topups:read" ] } ], "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "id", "created_at" ], "default": "created_at" }, "description": "Field of resource to sort by", "example": "id" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." } ], "responses": { "200": { "description": "List of top-ups.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Payments - Top ups List - Response", "type": "object", "description": "Paginated list of top-ups for an account group, including cursor-based pagination metadata.", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "items": { "type": "object", "description": "Represents a top-up funding request for an account group. After creation, the end user must send a SEPA Credit Transfer with the provided `settlement_reference` to complete the funding.", "properties": { "id": { "title": "Top up request unique identifier.", "type": "string", "description": "Top up request unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "settlement_reference": { "type": "string", "maxLength": 130, "pattern": "^[0-9A-Za-z+?/\\-:()\\.,'; ]{0,130}$", "description": "Settlement reference to be included in the corresponding bank transfer to settle this top up." }, "status": { "type": "string", "description": "Status of the top up\n* CONFIRMED - The top up is created and confirmed.\n* SETTLED - The top up is settled.\n* CANCELLED - The top up is cancelled", "enum": [ "CONFIRMED", "SETTLED", "CANCELLED" ] } }, "required": [ "id", "created_at", "account_group_id", "cash_amount", "currency" ], "additionalProperties": false } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "example": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1, "sort": "id", "order": "ASC" }, "data": [ { "id": "1ab4fef9-a097-4c6f-9345-647025d5fde6", "created_at": "2020-08-24T14:15:22Z", "account_group_id": "1ea60f56-b67b-61fc-829a-0242ac130003", "cash_amount": "200.00", "currency": "EUR", "status": "CONFIRMED" } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/payments/topups": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "post": { "operationId": "create_topup", "summary": "Trigger a top-up", "description": "Creates a top-up request for an account group and returns a `settlement_reference`. The end user must then send a SEPA Credit Transfer including that reference to complete the funding.", "tags": [ "Top-ups" ], "security": [ { "oauth-client-credentials": [ "topups:admin" ] } ], "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$", "example": "ccb07f42-4104-44ad-8e1f-c660bb7b269c" }, "description": "A UUID to be used as an idempotency key. This prevents a duplicate request from being replayed.\nhttps://docs.upvest.co/documentation/concepts/api_concepts/idempotency\n" } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Payments - Top up - Create - Request", "type": "object", "description": "Request body for creating a top-up. Specifies the account group to fund and the expected cash amount.", "properties": { "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] } }, "required": [ "account_group_id", "cash_amount", "currency" ], "additionalProperties": false }, "example": { "account_group_id": "1ea60f56-b67b-61fc-829a-0242ac130003", "cash_amount": "200.00", "currency": "EUR" } } } }, "responses": { "200": { "description": "Top-up created.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "type": "object", "description": "Represents a top-up funding request for an account group. After creation, the end user must send a SEPA Credit Transfer with the provided `settlement_reference` to complete the funding.", "properties": { "id": { "title": "Top up request unique identifier.", "type": "string", "description": "Top up request unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "settlement_reference": { "type": "string", "maxLength": 130, "pattern": "^[0-9A-Za-z+?/\\-:()\\.,'; ]{0,130}$", "description": "Settlement reference to be included in the corresponding bank transfer to settle this top up." }, "status": { "type": "string", "description": "Status of the top up\n* CONFIRMED - The top up is created and confirmed.\n* SETTLED - The top up is settled.\n* CANCELLED - The top up is cancelled", "enum": [ "CONFIRMED", "SETTLED", "CANCELLED" ] } }, "required": [ "id", "created_at", "account_group_id", "cash_amount", "currency" ], "additionalProperties": false }, "example": { "id": "1ab4fef9-a097-4c6f-9345-647025d5fde6", "created_at": "2020-08-24T14:15:22Z", "account_group_id": "1ea60f56-b67b-61fc-829a-0242ac130003", "cash_amount": "200.00", "currency": "EUR", "status": "CONFIRMED", "settlement_reference": "1ab4fef9-a097-4c6f-9345-647025d5fde6" } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/payments/topups/{topup_id}": { "parameters": [ { "name": "topup_id", "in": "path", "required": true, "description": "The unique identifier of the top-up. Universally Unique Identifier (UUID).", "schema": { "title": "Top up request unique identifier.", "type": "string", "description": "Top up request unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_topup", "summary": "Retrieve a top-up by ID", "description": "Returns a top-up specified by its ID.", "tags": [ "Top-ups" ], "security": [ { "oauth-client-credentials": [ "topups:admin", "topups:read" ] } ], "responses": { "200": { "description": "OK.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "type": "object", "description": "Represents a top-up funding request for an account group. After creation, the end user must send a SEPA Credit Transfer with the provided `settlement_reference` to complete the funding.", "properties": { "id": { "title": "Top up request unique identifier.", "type": "string", "description": "Top up request unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "settlement_reference": { "type": "string", "maxLength": 130, "pattern": "^[0-9A-Za-z+?/\\-:()\\.,'; ]{0,130}$", "description": "Settlement reference to be included in the corresponding bank transfer to settle this top up." }, "status": { "type": "string", "description": "Status of the top up\n* CONFIRMED - The top up is created and confirmed.\n* SETTLED - The top up is settled.\n* CANCELLED - The top up is cancelled", "enum": [ "CONFIRMED", "SETTLED", "CANCELLED" ] } }, "required": [ "id", "created_at", "account_group_id", "cash_amount", "currency" ], "additionalProperties": false }, "example": { "id": "1ab4fef9-a097-4c6f-9345-647025d5fde6", "created_at": "2020-08-24T14:15:22Z", "account_group_id": "1ea60f56-b67b-61fc-829a-0242ac130003", "cash_amount": "200.00", "currency": "EUR", "status": "CONFIRMED" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "delete": { "operationId": "cancel_topup", "summary": "Cancel a top-up by ID", "description": "Cancels a top-up specified by its ID. It is only possible to cancel a top-up if it has the status `CONFIRMED`.", "tags": [ "Top-ups" ], "security": [ { "oauth-client-credentials": [ "topups:admin" ] } ], "responses": { "204": { "description": "Request has been processed successfully.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "422": { "description": "Unprocessable Entity. The syntax of request is correct but server can't process it due a semantic error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 422, "type": "unprocessable_entity" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/account_groups/{account_group_id}/payments/credit_funding_details": { "parameters": [ { "name": "account_group_id", "in": "path", "required": true, "description": "The unique identifier of the account group. Universally Unique Identifier (UUID).", "schema": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_funding_details", "summary": "Retrieve funding details", "description": "Returns the virtual bank account details needed to fund an account group via SEPA Credit Transfer. Clients should present these details to end users so they can initiate the bank transfer.", "tags": [ "Credit Fundings" ], "security": [ { "oauth-client-credentials": [ "payments:admin", "payments:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." } ], "responses": { "200": { "description": "Funding Details", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "type": "object", "description": "Virtual bank account details for funding an account group via SEPA Credit Transfer. Each entry includes an IBAN, BIC, and `remittance_information` the end user must include in their bank transfer.", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "virtual_bank_account_id": { "title": "Virtual bank account request unique identifier.", "type": "string", "description": "Virtual bank account request unique identifier.", "format": "uuid" }, "name": { "type": "string", "description": "Name of the recipient account for the SEPA Credit Transfer" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "owner": { "type": "object", "description": "Owner of the virtual bank account", "properties": { "name": { "type": "string", "description": "Name of the owner of the virtual bank account" } }, "required": [ "name" ], "additionalProperties": false }, "identification": { "type": "object", "description": "Identification details", "properties": { "swift": { "type": "object", "description": "SWIFT details", "properties": { "iban": { "title": "International Bank Account Number (IBAN)", "type": "string", "description": "International Bank Account Number [IBAN](https://en.wikipedia.org/wiki/International_Bank_Account_Number).", "pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,26}$" }, "bic": { "title": "Business Identifier Code", "type": "string", "description": "Business Identifier Code (also known as SWIFT-BIC, BIC, SWIFT ID or SWIFT code) [ISO 9362](https://en.wikipedia.org/wiki/ISO_9362).", "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$" } }, "required": [ "iban", "bic" ], "additionalProperties": false } }, "additionalProperties": false }, "remittance_information": { "type": "string", "description": "Payment reference the one that should be used for SEPA Credit Transfer" } }, "required": [ "currency", "owner", "identification" ], "additionalProperties": false } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "example": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1, "sort": "created_at", "order": "ASC" }, "data": [ { "virtual_bank_account_id": "4e127ac5-dae3-487e-b76b-fef7225a8b80", "name": "Max's Virtual Bank Account", "currency": "EUR", "owner": { "name": "Max Musterman" }, "identification": { "swift": { "iban": "DE02100500000054540402", "bic": "DEUTDEFFXXX" } } }, { "virtual_bank_account_id": "a38470db-f54c-4514-ad71-6904a5c2744f", "name": "Max's Virtual Bank Account", "currency": "EUR", "owner": { "name": "Max Musterman" }, "identification": { "swift": { "iban": "DE02100500000054540403", "bic": "DEUTDEFFXXX" } } } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/account_groups/{account_group_id}/payments/credit_fundings": { "parameters": [ { "name": "account_group_id", "in": "path", "required": true, "description": "The unique identifier of the account group. Universally Unique Identifier (UUID).", "schema": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_credit_fundings", "summary": "List credit fundings", "description": "Returns a paginated list of credit fundings for the account group specified by its ID. A credit funding represents an incoming SEPA Credit Transfer that has been received and applied to the account group.", "tags": [ "Credit Fundings" ], "security": [ { "oauth-client-credentials": [ "credit_fundings:read", "payments:admin", "payments:read" ] } ], "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at" ], "default": "created_at" }, "description": "Field of resource to sort by", "example": "created_at" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." } ], "responses": { "200": { "description": "Credit Funding list", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Payments - Credit Fundings List - Response", "type": "object", "description": "Paginated list of credit fundings for an account group, including cursor-based pagination metadata.", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "items": { "type": "object", "description": "Represents an incoming SEPA Credit Transfer received by Upvest and credited to an account group. Contains counterparty identification and remittance details from the sender's bank.", "properties": { "id": { "title": "Credit Funding request unique identifier", "type": "string", "description": "Credit Funding request unique identifier", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "status": { "type": "string", "description": "Status of the credit funding\n* CONFIRMED - Credit Funding was confirmed.\n* CANCELLED - Credit Funding was cancelled.", "enum": [ "CONFIRMED", "CANCELLED" ] }, "remittance_information": { "type": "string", "description": "Payment reference the one that was used by the end user for the corresponding SEPA Credit Transfer" }, "counterparty": { "type": "object", "properties": { "identification": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the counterparty" } }, "required": [ "name" ] }, "account": { "type": "object", "properties": { "identification": { "type": "object", "properties": { "iban": { "title": "International Bank Account Number (IBAN)", "type": "string", "description": "International Bank Account Number [IBAN](https://en.wikipedia.org/wiki/International_Bank_Account_Number).", "pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,26}$" } }, "required": [ "iban" ] } }, "required": [ "identification" ] } }, "required": [ "identification", "account" ] }, "virtual_bank_account_id": { "title": "Virtual bank account request unique identifier.", "type": "string", "description": "Virtual bank account request unique identifier.", "format": "uuid" }, "purpose_code": { "type": "string", "maxLength": 4, "description": "Purpose of the payment based on *ExternalPurpose1Code* from [ISO 20022](https://www.iso20022.org/catalogue-messages/additional-content-messages/external-code-sets)." } }, "required": [ "id", "created_at", "account_group_id", "cash_amount", "currency", "remittance_information", "counterparty" ], "additionalProperties": false } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "example": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1, "sort": "id", "order": "ASC" }, "data": [ { "id": "1ab4fef9-a097-4c6f-9345-647025d5fde6", "created_at": "2020-08-24T14:15:22Z", "account_group_id": "1ea60f56-b67b-61fc-829a-0242ac130003", "cash_amount": "200.00", "currency": "EUR", "status": "CONFIRMED", "remittance_information": "CF123456789", "counterparty": { "identification": { "name": "Max Musterman" }, "account": { "identification": { "iban": "DE02100500000054540402" } } }, "virtual_bank_account_id": "ab8f9b19-6a31-48d3-b201-4dee92f3da0d", "purpose_code": "OTHR" } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/payments/credit_fundings/{credit_funding_id}": { "parameters": [ { "name": "credit_funding_id", "in": "path", "required": true, "description": "The unique identifier of the credit funding. Universally Unique Identifier (UUID).", "schema": { "title": "Credit Funding request unique identifier", "type": "string", "description": "Credit Funding request unique identifier", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_credit_funding", "summary": "Retrieve a credit funding", "description": "Returns the credit funding specified by its ID, including its status, cash amount, and counterparty details.", "tags": [ "Credit Fundings" ], "security": [ { "oauth-client-credentials": [ "credit_fundings:read", "payments:admin", "payments:read" ] } ], "responses": { "200": { "description": "Credit Funding payment", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "type": "object", "description": "Represents an incoming SEPA Credit Transfer received by Upvest and credited to an account group. Contains counterparty identification and remittance details from the sender's bank.", "properties": { "id": { "title": "Credit Funding request unique identifier", "type": "string", "description": "Credit Funding request unique identifier", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "status": { "type": "string", "description": "Status of the credit funding\n* CONFIRMED - Credit Funding was confirmed.\n* CANCELLED - Credit Funding was cancelled.", "enum": [ "CONFIRMED", "CANCELLED" ] }, "remittance_information": { "type": "string", "description": "Payment reference the one that was used by the end user for the corresponding SEPA Credit Transfer" }, "counterparty": { "type": "object", "properties": { "identification": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the counterparty" } }, "required": [ "name" ] }, "account": { "type": "object", "properties": { "identification": { "type": "object", "properties": { "iban": { "title": "International Bank Account Number (IBAN)", "type": "string", "description": "International Bank Account Number [IBAN](https://en.wikipedia.org/wiki/International_Bank_Account_Number).", "pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,26}$" } }, "required": [ "iban" ] } }, "required": [ "identification" ] } }, "required": [ "identification", "account" ] }, "virtual_bank_account_id": { "title": "Virtual bank account request unique identifier.", "type": "string", "description": "Virtual bank account request unique identifier.", "format": "uuid" }, "purpose_code": { "type": "string", "maxLength": 4, "description": "Purpose of the payment based on *ExternalPurpose1Code* from [ISO 20022](https://www.iso20022.org/catalogue-messages/additional-content-messages/external-code-sets)." } }, "required": [ "id", "created_at", "account_group_id", "cash_amount", "currency", "remittance_information", "counterparty" ], "additionalProperties": false }, "example": { "id": "1ab4fef9-a097-4c6f-9345-647025d5fde6", "created_at": "2020-08-24T14:15:22Z", "account_group_id": "1ea60f56-b67b-61fc-829a-0242ac130003", "cash_amount": "200.00", "currency": "EUR", "status": "CONFIRMED", "remittance_information": "CF123456789", "counterparty": { "identification": { "name": "Max Musterman" }, "account": { "identification": { "iban": "DE02100500000054540402" } } }, "virtual_bank_account_id": "ab8f9b19-6a31-48d3-b201-4dee92f3da0d", "purpose_code": "OTHR" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/payments/withdrawals": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "post": { "operationId": "create_cash_withdrawal", "summary": "Trigger a withdrawal", "description": "Trigger a withdrawal.\n\n**Deprecation notice:** The `user_id` field is deprecated, optional, and will be removed in a future version. For business account withdrawals, ownership is determined by the reference account linked to the business.", "tags": [ "Withdrawals" ], "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$", "example": "ccb07f42-4104-44ad-8e1f-c660bb7b269c" }, "description": "A UUID to be used as an idempotency key. This prevents a duplicate request from being replayed.\nhttps://docs.upvest.co/documentation/concepts/api_concepts/idempotency\n" } ], "security": [ { "oauth-client-credentials": [ "payments:admin" ] } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Payments - Withdrawal - Create - Request", "type": "object", "description": "Request body for initiating a cash withdrawal from an account group to a registered reference bank account.", "additionalProperties": false, "properties": { "reference_account_id": { "title": "Reference account unique identifier.", "type": "string", "description": "Reference account unique identifier.", "format": "uuid" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "user_id": { "allOf": [ { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" } ], "description": "The ID of the user. This field is optional and will be removed in a future version.", "deprecated": true }, "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "remittance_information": { "type": "string", "maxLength": 140, "pattern": "^[0-9A-Za-z+?/\\-:()\\.,';_ ]{0,140}$", "description": "Payment reference the end user will see in their bank statement for the corresponding credit transfer booking (“Verwendungszweck”). We recommend that you keep this info concise and avoid special characters or non-standardised formatting. See the ([Cash balance withdrawal guide](/documentation/guides/payments/cash_balances/cash_withdrawal))." }, "purpose_code": { "type": "string", "maxLength": 4, "description": "Purpose of the payment based on *ExternalPurpose1Code* from [ISO 20022](https://www.iso20022.org/catalogue-messages/additional-content-messages/external-code-sets)." } }, "required": [ "reference_account_id", "account_group_id", "amount" ] }, "example": { "reference_account_id": "295378ec-036e-4f3f-ae5c-2be85c93e837", "account_group_id": "2596db3b-0d03-4651-9eda-970910479dfb", "user_id": "e56c14b3-8370-4c04-bc67-7092f7ec113c", "amount": "200.00", "currency": "EUR", "remittance_information": "Withdrawal", "purpose_code": "OTHR" } } } }, "responses": { "200": { "description": "Withdrawal", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Payments - Withdrawal", "type": "object", "description": "Represents a cash withdrawal from an account group to a registered reference bank account. Withdrawals transition through `NEW` → `PROCESSING` → `CONFIRMED` or `CANCELLED` as they are processed.", "additionalProperties": false, "properties": { "id": { "title": "Cash withdrawal unique identifier", "type": "string", "description": "Cash withdrawal unique identifier", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "reference_account_id": { "title": "Reference account unique identifier.", "type": "string", "description": "Reference account unique identifier.", "format": "uuid" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "user_id": { "allOf": [ { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" } ], "description": "The ID of the user. For business-initiated withdrawals, this field will be absent.", "deprecated": true }, "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "remittance_information": { "type": "string", "maxLength": 140, "pattern": "^[0-9A-Za-z+?/\\-:()\\.,';_ ]{0,140}$", "description": "Payment reference the end user will see in their bank statement for the corresponding credit transfer booking (“Verwendungszweck”). We recommend that you keep this info concise and avoid special characters or non-standardised formatting. See the ([Cash balance withdrawal guide](/documentation/guides/payments/cash_balances/cash_withdrawal))." }, "taxes": { "type": "array", "items": { "title": "Tax", "type": "object", "description": "Tax deducted as part of a payment (e.g. a withdrawal). Contains the tax type and the deducted amount in the specified currency.", "properties": { "amount": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "type": { "type": "string", "description": "Type of the tax.\n* TOTAL - Total taxes", "enum": [ "TOTAL" ], "default": "TOTAL" } }, "required": [ "type", "amount", "currency" ] } }, "status": { "type": "string", "description": "Status of the withdrawal\n* NEW - Withdrawal is created but not started processing.\n* PROCESSING - Withdrawal is in processing.\n* CONFIRMED - Withdrawal was successfully sent to the bank for processing.\n* CANCELLED - Withdrawal was cancelled. **Note**: In rare instances, a bank may reject a withdrawal after it has been confirmed. \nFor more information, see the [Potential cancellation after confirmation](/documentation/guides/payments/cash_balances/cash_withdrawal#potential-cancellation-after-confirmation) section of the guide.", "enum": [ "NEW", "PROCESSING", "CONFIRMED", "CANCELLED" ] }, "cancellation_reason": { "title": "Cancellation reason code for withdrawal", "description": "Reason the withdrawal was cancelled. The field is present in case the withdrawal has a status of CANCELLED.\n* CANCELLED_BY_BANK - The payment was not completed by your bank. Please check your account details or contact support.\n* CANCELLED_BY_UPVEST - The payment was cancelled. Contact support for details.\n* CANCELLED_BY_CLIENT - The payment was cancelled at your request.\n* OTHER - Reason not available (applies to historical data only).", "type": "string", "enum": [ "CANCELLED_BY_BANK", "CANCELLED_BY_UPVEST", "CANCELLED_BY_CLIENT", "OTHER" ] }, "purpose_code": { "type": "string", "maxLength": 4, "description": "Purpose of the payment based on *ExternalPurpose1Code* from [ISO 20022](https://www.iso20022.org/catalogue-messages/additional-content-messages/external-code-sets)." } }, "required": [ "id", "reference_account_id", "account_group_id", "amount", "currency", "created_at", "updated_at", "remittance_information" ] }, "example": { "id": "6ffa6b16-2380-4e7a-88b2-ae625c8eef99", "created_at": "2020-08-24T14:15:22Z", "updated_at": "2020-08-24T14:15:22Z", "reference_account_id": "295378ec-036e-4f3f-ae5c-2be85c93e837", "account_group_id": "ac1c39e9-2101-46b8-a624-d10a9e351b6c", "user_id": "b668282b-cdf3-439a-bda2-3f3c9f655bb7", "amount": "200.00", "currency": "EUR", "remittance_information": "Withdrawal", "taxes": [ { "type": "TOTAL", "amount": "38.00", "currency": "EUR" } ], "status": "NEW", "purpose_code": "OTHR" } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/payments/withdrawals/{withdrawal_id}": { "parameters": [ { "name": "withdrawal_id", "in": "path", "required": true, "description": "The unique identifier of the cash withdrawal. Universally Unique Identifier (UUID).", "schema": { "title": "Cash withdrawal unique identifier", "type": "string", "description": "Cash withdrawal unique identifier", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_cash_withdrawal", "summary": "Retrieve withdrawal", "description": "Returns the cash withdrawal specified by its ID, including its current status, amount, and reference account.", "tags": [ "Withdrawals" ], "security": [ { "oauth-client-credentials": [ "payments:admin", "payments:read" ] } ], "responses": { "200": { "description": "Withdrawal", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Payments - Withdrawal", "type": "object", "description": "Represents a cash withdrawal from an account group to a registered reference bank account. Withdrawals transition through `NEW` → `PROCESSING` → `CONFIRMED` or `CANCELLED` as they are processed.", "additionalProperties": false, "properties": { "id": { "title": "Cash withdrawal unique identifier", "type": "string", "description": "Cash withdrawal unique identifier", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "reference_account_id": { "title": "Reference account unique identifier.", "type": "string", "description": "Reference account unique identifier.", "format": "uuid" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "user_id": { "allOf": [ { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" } ], "description": "The ID of the user. For business-initiated withdrawals, this field will be absent.", "deprecated": true }, "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "remittance_information": { "type": "string", "maxLength": 140, "pattern": "^[0-9A-Za-z+?/\\-:()\\.,';_ ]{0,140}$", "description": "Payment reference the end user will see in their bank statement for the corresponding credit transfer booking (“Verwendungszweck”). We recommend that you keep this info concise and avoid special characters or non-standardised formatting. See the ([Cash balance withdrawal guide](/documentation/guides/payments/cash_balances/cash_withdrawal))." }, "taxes": { "type": "array", "items": { "title": "Tax", "type": "object", "description": "Tax deducted as part of a payment (e.g. a withdrawal). Contains the tax type and the deducted amount in the specified currency.", "properties": { "amount": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "type": { "type": "string", "description": "Type of the tax.\n* TOTAL - Total taxes", "enum": [ "TOTAL" ], "default": "TOTAL" } }, "required": [ "type", "amount", "currency" ] } }, "status": { "type": "string", "description": "Status of the withdrawal\n* NEW - Withdrawal is created but not started processing.\n* PROCESSING - Withdrawal is in processing.\n* CONFIRMED - Withdrawal was successfully sent to the bank for processing.\n* CANCELLED - Withdrawal was cancelled. **Note**: In rare instances, a bank may reject a withdrawal after it has been confirmed. \nFor more information, see the [Potential cancellation after confirmation](/documentation/guides/payments/cash_balances/cash_withdrawal#potential-cancellation-after-confirmation) section of the guide.", "enum": [ "NEW", "PROCESSING", "CONFIRMED", "CANCELLED" ] }, "cancellation_reason": { "title": "Cancellation reason code for withdrawal", "description": "Reason the withdrawal was cancelled. The field is present in case the withdrawal has a status of CANCELLED.\n* CANCELLED_BY_BANK - The payment was not completed by your bank. Please check your account details or contact support.\n* CANCELLED_BY_UPVEST - The payment was cancelled. Contact support for details.\n* CANCELLED_BY_CLIENT - The payment was cancelled at your request.\n* OTHER - Reason not available (applies to historical data only).", "type": "string", "enum": [ "CANCELLED_BY_BANK", "CANCELLED_BY_UPVEST", "CANCELLED_BY_CLIENT", "OTHER" ] }, "purpose_code": { "type": "string", "maxLength": 4, "description": "Purpose of the payment based on *ExternalPurpose1Code* from [ISO 20022](https://www.iso20022.org/catalogue-messages/additional-content-messages/external-code-sets)." } }, "required": [ "id", "reference_account_id", "account_group_id", "amount", "currency", "created_at", "updated_at", "remittance_information" ] }, "examples": { "ordinary": { "summary": "Ordinary", "value": { "id": "6ffa6b16-2380-4e7a-88b2-ae625c8eef99", "created_at": "2020-08-24T14:15:22Z", "updated_at": "2020-08-24T14:15:22Z", "reference_account_id": "295378ec-036e-4f3f-ae5c-2be85c93e837", "account_group_id": "ac1c39e9-2101-46b8-a624-d10a9e351b6c", "user_id": "b668282b-cdf3-439a-bda2-3f3c9f655bb7", "amount": "200.00", "currency": "EUR", "remittance_information": "Withdrawal", "taxes": [ { "type": "TOTAL", "amount": "38.00", "currency": "EUR" } ], "status": "CONFIRMED", "purpose_code": "OTHR" } }, "cancelled": { "summary": "Cancelled", "value": { "id": "6ffa6b16-2380-4e7a-88b2-ae625c8eef99", "created_at": "2020-08-24T14:15:22Z", "updated_at": "2020-08-24T14:16:05Z", "reference_account_id": "295378ec-036e-4f3f-ae5c-2be85c93e837", "account_group_id": "ac1c39e9-2101-46b8-a624-d10a9e351b6c", "user_id": "b668282b-cdf3-439a-bda2-3f3c9f655bb7", "amount": "200.00", "currency": "EUR", "remittance_information": "Withdrawal", "taxes": [ { "type": "TOTAL", "amount": "38.00", "currency": "EUR" } ], "status": "CANCELLED", "cancellation_reason": "CANCELLED_BY_BANK", "purpose_code": "OTHR" } } } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "delete": { "operationId": "cancel_cash_withdrawal", "summary": "Cancel withdrawal by ID", "description": "Cancels a withdrawal specified by its ID. It is only possible to cancel a withdrawal if it has the status `NEW`.", "tags": [ "Withdrawals" ], "security": [ { "oauth-client-credentials": [ "payments:admin" ] } ], "responses": { "204": { "description": "Request has been processed successfully.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "422": { "description": "Unprocessable Entity. The syntax of request is correct but server can't process it due a semantic error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 422, "type": "unprocessable_entity" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/account_groups/{account_group_id}/payments/withdrawals": { "parameters": [ { "name": "account_group_id", "in": "path", "required": true, "description": "The unique identifier of the account group. Universally Unique Identifier (UUID).", "schema": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_cash_withdrawals", "summary": "List withdrawals", "description": "Returns a paginated list of cash withdrawals for the account group specified by its ID.", "tags": [ "Withdrawals" ], "security": [ { "oauth-client-credentials": [ "payments:admin", "payments:read" ] } ], "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "id", "created_at" ], "default": "created_at" }, "description": "Field of resource to sort by", "example": "id" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." } ], "responses": { "200": { "description": "Withdrawals list", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Withdrawals - List - Response", "type": "object", "description": "Paginated list of cash withdrawals for an account group, including cursor-based pagination metadata.", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "items": { "title": "Payments - Withdrawal", "type": "object", "description": "Represents a cash withdrawal from an account group to a registered reference bank account. Withdrawals transition through `NEW` → `PROCESSING` → `CONFIRMED` or `CANCELLED` as they are processed.", "additionalProperties": false, "properties": { "id": { "title": "Cash withdrawal unique identifier", "type": "string", "description": "Cash withdrawal unique identifier", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "reference_account_id": { "title": "Reference account unique identifier.", "type": "string", "description": "Reference account unique identifier.", "format": "uuid" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "user_id": { "allOf": [ { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" } ], "description": "The ID of the user. For business-initiated withdrawals, this field will be absent.", "deprecated": true }, "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "remittance_information": { "type": "string", "maxLength": 140, "pattern": "^[0-9A-Za-z+?/\\-:()\\.,';_ ]{0,140}$", "description": "Payment reference the end user will see in their bank statement for the corresponding credit transfer booking (“Verwendungszweck”). We recommend that you keep this info concise and avoid special characters or non-standardised formatting. See the ([Cash balance withdrawal guide](/documentation/guides/payments/cash_balances/cash_withdrawal))." }, "taxes": { "type": "array", "items": { "title": "Tax", "type": "object", "description": "Tax deducted as part of a payment (e.g. a withdrawal). Contains the tax type and the deducted amount in the specified currency.", "properties": { "amount": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "type": { "type": "string", "description": "Type of the tax.\n* TOTAL - Total taxes", "enum": [ "TOTAL" ], "default": "TOTAL" } }, "required": [ "type", "amount", "currency" ] } }, "status": { "type": "string", "description": "Status of the withdrawal\n* NEW - Withdrawal is created but not started processing.\n* PROCESSING - Withdrawal is in processing.\n* CONFIRMED - Withdrawal was successfully sent to the bank for processing.\n* CANCELLED - Withdrawal was cancelled. **Note**: In rare instances, a bank may reject a withdrawal after it has been confirmed. \nFor more information, see the [Potential cancellation after confirmation](/documentation/guides/payments/cash_balances/cash_withdrawal#potential-cancellation-after-confirmation) section of the guide.", "enum": [ "NEW", "PROCESSING", "CONFIRMED", "CANCELLED" ] }, "cancellation_reason": { "title": "Cancellation reason code for withdrawal", "description": "Reason the withdrawal was cancelled. The field is present in case the withdrawal has a status of CANCELLED.\n* CANCELLED_BY_BANK - The payment was not completed by your bank. Please check your account details or contact support.\n* CANCELLED_BY_UPVEST - The payment was cancelled. Contact support for details.\n* CANCELLED_BY_CLIENT - The payment was cancelled at your request.\n* OTHER - Reason not available (applies to historical data only).", "type": "string", "enum": [ "CANCELLED_BY_BANK", "CANCELLED_BY_UPVEST", "CANCELLED_BY_CLIENT", "OTHER" ] }, "purpose_code": { "type": "string", "maxLength": 4, "description": "Purpose of the payment based on *ExternalPurpose1Code* from [ISO 20022](https://www.iso20022.org/catalogue-messages/additional-content-messages/external-code-sets)." } }, "required": [ "id", "reference_account_id", "account_group_id", "amount", "currency", "created_at", "updated_at", "remittance_information" ] } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "example": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1 }, "data": [ { "id": "6ffa6b16-2380-4e7a-88b2-ae625c8eef99", "created_at": "2020-08-24T14:15:22Z", "updated_at": "2020-08-24T14:15:22Z", "reference_account_id": "295378ec-036e-4f3f-ae5c-2be85c93e837", "account_group_id": "ac1c39e9-2101-46b8-a624-d10a9e351b6c", "user_id": "b668282b-cdf3-439a-bda2-3f3c9f655bb7", "amount": "200.00", "currency": "EUR", "remittance_information": "Withdrawal", "taxes": [ { "type": "TOTAL", "amount": "38.00", "currency": "EUR" } ], "status": "CONFIRMED", "purpose_code": "OTHR" } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/payments/cash_balance_transfers": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_cash_balance_transfers", "summary": "List cash balance transfers", "description": "Returns a paginated list of all cash balance transfers initiated by the client, across all account groups and users.", "tags": [ "Cash Balance Transfers" ], "security": [ { "oauth-client-credentials": [ "cash_balance_transfers:admin", "cash_balance_transfers:read" ] } ], "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "id", "created_at" ], "default": "created_at" }, "description": "Field of resource to sort by", "example": "id" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." } ], "responses": { "200": { "description": "Cash balance transfers list", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Cash Balance Transfers - List - Response", "type": "object", "description": "Paginated list of cash balance transfers, including cursor-based pagination metadata.", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "items": { "title": "Payments - Cash Balance Transfer", "type": "object", "description": "Represents an internal cash balance transfer between two account groups belonging to the same user and tenant. Only settled cash in the same currency can be transferred.", "additionalProperties": false, "properties": { "id": { "title": "Cash balance transfer unique identifier", "type": "string", "description": "Cash balance transfer unique identifier", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "source_account_group_id": { "allOf": [ { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } ], "description": "The account group the cash is transferred from. Must differ from `target_account_group_id` and belong to the same user and tenant. Allowed account group types are `PERSONAL`, `CHILD`, and `BUSINESS`, and the source and target account groups must be of the same type." }, "target_account_group_id": { "allOf": [ { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } ], "description": "The account group the cash is transferred to. Must differ from `source_account_group_id` and belong to the same user and tenant. Allowed account group types are `PERSONAL`, `CHILD`, and `BUSINESS`, and the source and target account groups must be of the same type." }, "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "status": { "type": "string", "description": "Status of the cash balance transfer.\n* ISSUED - Transfer has been created and the cash movement is in progress.\n* CONFIRMED - Cash was successfully moved from the source to the target account group.\n* CANCELLED - Transfer was cancelled and no cash was moved.", "enum": [ "ISSUED", "CONFIRMED", "CANCELLED" ] }, "cancellation_reason": { "type": "string", "nullable": true, "description": "Reason the transfer was cancelled. Present only when `status` is `CANCELLED`, otherwise `null`." } }, "required": [ "id", "source_account_group_id", "target_account_group_id", "amount", "currency", "status", "created_at", "updated_at" ] } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "example": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1 }, "data": [ { "id": "b3f6a0c2-1d7e-4a3b-9f21-0c2d4e6f8a10", "created_at": "2026-06-25T14:15:22Z", "updated_at": "2026-06-25T14:15:23Z", "source_account_group_id": "2596db3b-0d03-4651-9eda-970910479dfb", "target_account_group_id": "e56c14b3-8370-4c04-bc67-7092f7ec113c", "amount": "200.00", "currency": "EUR", "status": "CONFIRMED", "cancellation_reason": null } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "post": { "operationId": "create_cash_balance_transfer", "summary": "Create a cash balance transfer", "description": "Create an internal cash balance transfer between two account groups belonging to the same user and tenant. The cash leaves the source account group and arrives at the target account group as a single operation, with no external bank transfer. Only settled cash denominated in the same currency (EUR) can be transferred. Both account groups must be of the same type, and the type must be one of `PERSONAL`, `CHILD`, or `BUSINESS`.", "tags": [ "Cash Balance Transfers" ], "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$", "example": "ccb07f42-4104-44ad-8e1f-c660bb7b269c" }, "description": "A UUID to be used as an idempotency key. This prevents a duplicate request from being replayed.\nhttps://docs.upvest.co/documentation/concepts/api_concepts/idempotency\n" } ], "security": [ { "oauth-client-credentials": [ "cash_balance_transfers:admin" ] } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Payments - Cash Balance Transfer - Create - Request", "type": "object", "description": "Request body for creating a cash balance transfer between two account groups belonging to the same user and tenant.", "additionalProperties": false, "properties": { "source_account_group_id": { "allOf": [ { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } ], "description": "The account group the cash is transferred from. Must differ from `target_account_group_id` and belong to the same user and tenant. Allowed account group types are `PERSONAL`, `CHILD`, and `BUSINESS`, and the source and target account groups must be of the same type." }, "target_account_group_id": { "allOf": [ { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } ], "description": "The account group the cash is transferred to. Must differ from `source_account_group_id` and belong to the same user and tenant. Allowed account group types are `PERSONAL`, `CHILD`, and `BUSINESS`, and the source and target account groups must be of the same type." }, "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] } }, "required": [ "source_account_group_id", "target_account_group_id", "amount", "currency" ] }, "example": { "source_account_group_id": "2596db3b-0d03-4651-9eda-970910479dfb", "target_account_group_id": "e56c14b3-8370-4c04-bc67-7092f7ec113c", "amount": "200.00", "currency": "EUR" } } } }, "responses": { "200": { "description": "Cash balance transfer", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Payments - Cash Balance Transfer", "type": "object", "description": "Represents an internal cash balance transfer between two account groups belonging to the same user and tenant. Only settled cash in the same currency can be transferred.", "additionalProperties": false, "properties": { "id": { "title": "Cash balance transfer unique identifier", "type": "string", "description": "Cash balance transfer unique identifier", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "source_account_group_id": { "allOf": [ { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } ], "description": "The account group the cash is transferred from. Must differ from `target_account_group_id` and belong to the same user and tenant. Allowed account group types are `PERSONAL`, `CHILD`, and `BUSINESS`, and the source and target account groups must be of the same type." }, "target_account_group_id": { "allOf": [ { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } ], "description": "The account group the cash is transferred to. Must differ from `source_account_group_id` and belong to the same user and tenant. Allowed account group types are `PERSONAL`, `CHILD`, and `BUSINESS`, and the source and target account groups must be of the same type." }, "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "status": { "type": "string", "description": "Status of the cash balance transfer.\n* ISSUED - Transfer has been created and the cash movement is in progress.\n* CONFIRMED - Cash was successfully moved from the source to the target account group.\n* CANCELLED - Transfer was cancelled and no cash was moved.", "enum": [ "ISSUED", "CONFIRMED", "CANCELLED" ] }, "cancellation_reason": { "type": "string", "nullable": true, "description": "Reason the transfer was cancelled. Present only when `status` is `CANCELLED`, otherwise `null`." } }, "required": [ "id", "source_account_group_id", "target_account_group_id", "amount", "currency", "status", "created_at", "updated_at" ] }, "example": { "id": "b3f6a0c2-1d7e-4a3b-9f21-0c2d4e6f8a10", "created_at": "2026-06-25T14:15:22Z", "updated_at": "2026-06-25T14:15:22Z", "source_account_group_id": "2596db3b-0d03-4651-9eda-970910479dfb", "target_account_group_id": "e56c14b3-8370-4c04-bc67-7092f7ec113c", "amount": "200.00", "currency": "EUR", "status": "ISSUED", "cancellation_reason": null } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/payments/cash_balance_transfers/{cash_balance_transfer_id}": { "parameters": [ { "name": "cash_balance_transfer_id", "in": "path", "required": true, "description": "The unique identifier of the cash balance transfer. Universally Unique Identifier (UUID).", "schema": { "title": "Cash balance transfer unique identifier", "type": "string", "description": "Cash balance transfer unique identifier", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_cash_balance_transfer", "summary": "Retrieve cash balance transfer", "description": "Retrieve a cash balance transfer by its ID.", "tags": [ "Cash Balance Transfers" ], "security": [ { "oauth-client-credentials": [ "cash_balance_transfers:admin", "cash_balance_transfers:read" ] } ], "responses": { "200": { "description": "Cash balance transfer", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Payments - Cash Balance Transfer", "type": "object", "description": "Represents an internal cash balance transfer between two account groups belonging to the same user and tenant. Only settled cash in the same currency can be transferred.", "additionalProperties": false, "properties": { "id": { "title": "Cash balance transfer unique identifier", "type": "string", "description": "Cash balance transfer unique identifier", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "source_account_group_id": { "allOf": [ { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } ], "description": "The account group the cash is transferred from. Must differ from `target_account_group_id` and belong to the same user and tenant. Allowed account group types are `PERSONAL`, `CHILD`, and `BUSINESS`, and the source and target account groups must be of the same type." }, "target_account_group_id": { "allOf": [ { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } ], "description": "The account group the cash is transferred to. Must differ from `source_account_group_id` and belong to the same user and tenant. Allowed account group types are `PERSONAL`, `CHILD`, and `BUSINESS`, and the source and target account groups must be of the same type." }, "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "status": { "type": "string", "description": "Status of the cash balance transfer.\n* ISSUED - Transfer has been created and the cash movement is in progress.\n* CONFIRMED - Cash was successfully moved from the source to the target account group.\n* CANCELLED - Transfer was cancelled and no cash was moved.", "enum": [ "ISSUED", "CONFIRMED", "CANCELLED" ] }, "cancellation_reason": { "type": "string", "nullable": true, "description": "Reason the transfer was cancelled. Present only when `status` is `CANCELLED`, otherwise `null`." } }, "required": [ "id", "source_account_group_id", "target_account_group_id", "amount", "currency", "status", "created_at", "updated_at" ] }, "example": { "id": "b3f6a0c2-1d7e-4a3b-9f21-0c2d4e6f8a10", "created_at": "2026-06-25T14:15:22Z", "updated_at": "2026-06-25T14:15:23Z", "source_account_group_id": "2596db3b-0d03-4651-9eda-970910479dfb", "target_account_group_id": "e56c14b3-8370-4c04-bc67-7092f7ec113c", "amount": "200.00", "currency": "EUR", "status": "CONFIRMED", "cancellation_reason": null } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "delete": { "operationId": "cancel_cash_balance_transfer", "summary": "Cancel cash balance transfer by ID", "description": "Cancels a cash balance transfer specified by its ID. It is only possible to cancel a transfer while it has the status `ISSUED`.", "tags": [ "Cash Balance Transfers" ], "security": [ { "oauth-client-credentials": [ "cash_balance_transfers:admin" ] } ], "responses": { "204": { "description": "Request has been processed successfully.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "422": { "description": "Unprocessable Entity. The syntax of request is correct but server can't process it due a semantic error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 422, "type": "unprocessable_entity" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/users/{user_id}/payments/cash_balance_transfers": { "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "The unique identifier of the user. Universally Unique Identifier (UUID).", "schema": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_user_cash_balance_transfers", "summary": "List cash balance transfers of a user", "description": "Returns the list of cash balance transfers of a user specified by ID.", "tags": [ "Cash Balance Transfers" ], "security": [ { "oauth-client-credentials": [ "cash_balance_transfers:admin", "cash_balance_transfers:read" ] } ], "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "id", "created_at" ], "default": "created_at" }, "description": "Field of resource to sort by", "example": "id" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." } ], "responses": { "200": { "description": "Cash balance transfers list", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "User Cash Balance Transfers - List - Response", "type": "object", "description": "Paginated list of cash balance transfers for a user, including cursor-based pagination metadata.", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "items": { "title": "Payments - Cash Balance Transfer", "type": "object", "description": "Represents an internal cash balance transfer between two account groups belonging to the same user and tenant. Only settled cash in the same currency can be transferred.", "additionalProperties": false, "properties": { "id": { "title": "Cash balance transfer unique identifier", "type": "string", "description": "Cash balance transfer unique identifier", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "source_account_group_id": { "allOf": [ { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } ], "description": "The account group the cash is transferred from. Must differ from `target_account_group_id` and belong to the same user and tenant. Allowed account group types are `PERSONAL`, `CHILD`, and `BUSINESS`, and the source and target account groups must be of the same type." }, "target_account_group_id": { "allOf": [ { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } ], "description": "The account group the cash is transferred to. Must differ from `source_account_group_id` and belong to the same user and tenant. Allowed account group types are `PERSONAL`, `CHILD`, and `BUSINESS`, and the source and target account groups must be of the same type." }, "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "status": { "type": "string", "description": "Status of the cash balance transfer.\n* ISSUED - Transfer has been created and the cash movement is in progress.\n* CONFIRMED - Cash was successfully moved from the source to the target account group.\n* CANCELLED - Transfer was cancelled and no cash was moved.", "enum": [ "ISSUED", "CONFIRMED", "CANCELLED" ] }, "cancellation_reason": { "type": "string", "nullable": true, "description": "Reason the transfer was cancelled. Present only when `status` is `CANCELLED`, otherwise `null`." } }, "required": [ "id", "source_account_group_id", "target_account_group_id", "amount", "currency", "status", "created_at", "updated_at" ] } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "example": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1 }, "data": [ { "id": "b3f6a0c2-1d7e-4a3b-9f21-0c2d4e6f8a10", "created_at": "2026-06-25T14:15:22Z", "updated_at": "2026-06-25T14:15:23Z", "source_account_group_id": "2596db3b-0d03-4651-9eda-970910479dfb", "target_account_group_id": "e56c14b3-8370-4c04-bc67-7092f7ec113c", "amount": "200.00", "currency": "EUR", "status": "CONFIRMED", "cancellation_reason": null } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/businesses/{business_id}/payments/cash_balance_transfers": { "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "The unique identifier of the business. Universally Unique Identifier (UUID).", "schema": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_business_cash_balance_transfers", "summary": "List cash balance transfers of a business", "description": "Returns the list of cash balance transfers of a business specified by ID.", "tags": [ "Cash Balance Transfers" ], "security": [ { "oauth-client-credentials": [ "cash_balance_transfers:admin", "cash_balance_transfers:read" ] } ], "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "id", "created_at" ], "default": "created_at" }, "description": "Field of resource to sort by", "example": "id" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." } ], "responses": { "200": { "description": "Cash balance transfers list", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Business Cash Balance Transfers - List - Response", "type": "object", "description": "Paginated list of cash balance transfers for a business, including cursor-based pagination metadata.", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "items": { "title": "Payments - Cash Balance Transfer", "type": "object", "description": "Represents an internal cash balance transfer between two account groups belonging to the same user and tenant. Only settled cash in the same currency can be transferred.", "additionalProperties": false, "properties": { "id": { "title": "Cash balance transfer unique identifier", "type": "string", "description": "Cash balance transfer unique identifier", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "source_account_group_id": { "allOf": [ { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } ], "description": "The account group the cash is transferred from. Must differ from `target_account_group_id` and belong to the same user and tenant. Allowed account group types are `PERSONAL`, `CHILD`, and `BUSINESS`, and the source and target account groups must be of the same type." }, "target_account_group_id": { "allOf": [ { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } ], "description": "The account group the cash is transferred to. Must differ from `source_account_group_id` and belong to the same user and tenant. Allowed account group types are `PERSONAL`, `CHILD`, and `BUSINESS`, and the source and target account groups must be of the same type." }, "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "status": { "type": "string", "description": "Status of the cash balance transfer.\n* ISSUED - Transfer has been created and the cash movement is in progress.\n* CONFIRMED - Cash was successfully moved from the source to the target account group.\n* CANCELLED - Transfer was cancelled and no cash was moved.", "enum": [ "ISSUED", "CONFIRMED", "CANCELLED" ] }, "cancellation_reason": { "type": "string", "nullable": true, "description": "Reason the transfer was cancelled. Present only when `status` is `CANCELLED`, otherwise `null`." } }, "required": [ "id", "source_account_group_id", "target_account_group_id", "amount", "currency", "status", "created_at", "updated_at" ] } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "example": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1 }, "data": [ { "id": "b3f6a0c2-1d7e-4a3b-9f21-0c2d4e6f8a10", "created_at": "2026-06-25T14:15:22Z", "updated_at": "2026-06-25T14:15:23Z", "source_account_group_id": "2596db3b-0d03-4651-9eda-970910479dfb", "target_account_group_id": "e56c14b3-8370-4c04-bc67-7092f7ec113c", "amount": "200.00", "currency": "EUR", "status": "CONFIRMED", "cancellation_reason": null } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/account_groups/{account_group_id}/payments/virtual_bank_accounts": { "parameters": [ { "name": "account_group_id", "in": "path", "required": true, "description": "The unique identifier of the account group. Universally Unique Identifier (UUID).", "schema": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_virtual_bank_accounts", "summary": "List virtual bank accounts", "description": "Returns a list of virtual bank accounts.", "tags": [ "Virtual Bank Accounts" ], "security": [ { "oauth-client-credentials": [ "payments:admin", "payments:read" ] } ], "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "id", "created_at" ], "default": "created_at" }, "description": "Field of resource to sort by", "example": "id" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." } ], "responses": { "200": { "description": "List of virtual bank accounts.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Payments - Virtual Bank Accounts List - Response", "type": "object", "description": "Paginated list of virtual bank accounts for an account group, including cursor-based pagination metadata.", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "items": { "type": "object", "description": "Represents a virtual bank account assigned to an account group. Provides an IBAN and BIC that end users can use to send SEPA Credit Transfers directly to their investment account.", "properties": { "id": { "title": "Virtual bank account request unique identifier.", "type": "string", "description": "Virtual bank account request unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "name": { "type": "string", "description": "Name of the virtual bank account" }, "owner": { "type": "object", "description": "Owner of the virtual bank account", "properties": { "name": { "type": "string", "description": "Name of the owner of the virtual bank account" } }, "required": [ "name" ], "additionalProperties": false }, "identification": { "type": "object", "description": "Identification details", "properties": { "swift": { "type": "object", "description": "SWIFT details", "properties": { "iban": { "title": "International Bank Account Number (IBAN)", "type": "string", "description": "International Bank Account Number [IBAN](https://en.wikipedia.org/wiki/International_Bank_Account_Number).", "pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,26}$" }, "bic": { "title": "Business Identifier Code", "type": "string", "description": "Business Identifier Code (also known as SWIFT-BIC, BIC, SWIFT ID or SWIFT code) [ISO 9362](https://en.wikipedia.org/wiki/ISO_9362).", "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$" } }, "required": [ "iban", "bic" ], "additionalProperties": false } }, "additionalProperties": false } }, "required": [ "id", "created_at", "account_group_id", "owner", "identification" ], "additionalProperties": false } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "example": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1, "sort": "id", "order": "ASC" }, "data": [ { "id": "22913092-0484-42e9-9273-9ffd6dfd0b13", "created_at": "2021-07-21T14:10:00.00Z", "account_group_id": "d1354aad-6da7-4da7-aaa1-e00ebfd3240d", "name": "Max's Virtual Bank Account", "owner": { "name": "Max Musterman" }, "identification": { "swift": { "iban": "DE89000000000000000000", "bic": "ABCDEXXX" } } } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/payments/virtual_bank_accounts": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "post": { "operationId": "create_virtual_bank_account", "summary": "Create a virtual bank account", "description": "Creates a virtual bank account for an account group. The virtual bank account provides an IBAN and BIC that end users can use to send SEPA Credit Transfers directly to their investment account.", "tags": [ "Virtual Bank Accounts" ], "security": [ { "oauth-client-credentials": [ "payments:admin" ] } ], "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$", "example": "ccb07f42-4104-44ad-8e1f-c660bb7b269c" }, "description": "A UUID to be used as an idempotency key. This prevents a duplicate request from being replayed.\nhttps://docs.upvest.co/documentation/concepts/api_concepts/idempotency\n" } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Payments - Virtual Bank Account - Create - Request", "type": "object", "description": "Request body for creating a virtual bank account for an account group.", "properties": { "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "name": { "type": "string", "description": "Name of the virtual bank account" } }, "required": [ "account_group_id", "name" ], "additionalProperties": false }, "example": { "account_group_id": "f874a64a-ceaa-42b2-b59a-39d4f62166fb", "name": "Max's Virtual Bank Account" } } } }, "responses": { "200": { "description": "Virtual Bank Account created.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "type": "object", "description": "Represents a virtual bank account assigned to an account group. Provides an IBAN and BIC that end users can use to send SEPA Credit Transfers directly to their investment account.", "properties": { "id": { "title": "Virtual bank account request unique identifier.", "type": "string", "description": "Virtual bank account request unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "name": { "type": "string", "description": "Name of the virtual bank account" }, "owner": { "type": "object", "description": "Owner of the virtual bank account", "properties": { "name": { "type": "string", "description": "Name of the owner of the virtual bank account" } }, "required": [ "name" ], "additionalProperties": false }, "identification": { "type": "object", "description": "Identification details", "properties": { "swift": { "type": "object", "description": "SWIFT details", "properties": { "iban": { "title": "International Bank Account Number (IBAN)", "type": "string", "description": "International Bank Account Number [IBAN](https://en.wikipedia.org/wiki/International_Bank_Account_Number).", "pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,26}$" }, "bic": { "title": "Business Identifier Code", "type": "string", "description": "Business Identifier Code (also known as SWIFT-BIC, BIC, SWIFT ID or SWIFT code) [ISO 9362](https://en.wikipedia.org/wiki/ISO_9362).", "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$" } }, "required": [ "iban", "bic" ], "additionalProperties": false } }, "additionalProperties": false } }, "required": [ "id", "created_at", "account_group_id", "owner", "identification" ], "additionalProperties": false }, "example": { "id": "22913092-0484-42e9-9273-9ffd6dfd0b13", "created_at": "2021-07-21T14:10:00.00Z", "account_group_id": "d1354aad-6da7-4da7-aaa1-e00ebfd3240d", "name": "Max's Virtual Bank Account", "owner": { "name": "Max Musterman" }, "identification": { "swift": { "iban": "DE89000000000000000000", "bic": "ABCDEXXX" } } } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/payments/virtual_bank_accounts/{virtual_bank_account_id}": { "parameters": [ { "name": "virtual_bank_account_id", "in": "path", "required": true, "description": "The unique identifier of the virtual bank account. Universally Unique Identifier (UUID).", "schema": { "title": "Virtual bank account request unique identifier.", "type": "string", "description": "Virtual bank account request unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_virtual_bank_account", "summary": "Retrieve a virtual bank account by ID", "description": "Returns a virtual bank account specified by its ID.", "tags": [ "Virtual Bank Accounts" ], "security": [ { "oauth-client-credentials": [ "payments:admin", "payments:read" ] } ], "responses": { "200": { "description": "OK.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "type": "object", "description": "Represents a virtual bank account assigned to an account group. Provides an IBAN and BIC that end users can use to send SEPA Credit Transfers directly to their investment account.", "properties": { "id": { "title": "Virtual bank account request unique identifier.", "type": "string", "description": "Virtual bank account request unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "name": { "type": "string", "description": "Name of the virtual bank account" }, "owner": { "type": "object", "description": "Owner of the virtual bank account", "properties": { "name": { "type": "string", "description": "Name of the owner of the virtual bank account" } }, "required": [ "name" ], "additionalProperties": false }, "identification": { "type": "object", "description": "Identification details", "properties": { "swift": { "type": "object", "description": "SWIFT details", "properties": { "iban": { "title": "International Bank Account Number (IBAN)", "type": "string", "description": "International Bank Account Number [IBAN](https://en.wikipedia.org/wiki/International_Bank_Account_Number).", "pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,26}$" }, "bic": { "title": "Business Identifier Code", "type": "string", "description": "Business Identifier Code (also known as SWIFT-BIC, BIC, SWIFT ID or SWIFT code) [ISO 9362](https://en.wikipedia.org/wiki/ISO_9362).", "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$" } }, "required": [ "iban", "bic" ], "additionalProperties": false } }, "additionalProperties": false } }, "required": [ "id", "created_at", "account_group_id", "owner", "identification" ], "additionalProperties": false }, "example": { "id": "22913092-0484-42e9-9273-9ffd6dfd0b13", "created_at": "2021-07-21T14:10:00.00Z", "account_group_id": "d1354aad-6da7-4da7-aaa1-e00ebfd3240d", "name": "Max's Virtual Bank Account", "owner": { "name": "Max Musterman" }, "identification": { "swift": { "iban": "DE89000000000000000000", "bic": "ABCDEXXX" } } } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/account_groups": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_account_groups", "summary": "Get account groups", "description": "Returns a list of all account groups.", "tags": [ "Account Groups" ], "security": [ { "oauth-client-credentials": [ "accounts:read", "accounts:admin" ] } ], "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "updated_at" ], "default": "created_at" }, "description": "Sort the result by `created_at`, `updated_at`." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Account Groups - List - Response", "type": "object", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "items": { "oneOf": [ { "title": "Account Group", "type": "object", "description": "", "properties": { "id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "type": { "type": "string", "description": "Relation type\n* OWNER - Account Group Owner\n* CHILD - Child Account Group Owner\n* GUARDIAN - Child Account Group Guardian", "enum": [ "OWNER", "CHILD", "GUARDIAN" ] } } } }, "status": { "type": "string", "description": "Status of the account group\n* PENDING_APPROVAL - Account group approval is pending - the account group is visible through our API but cannot be acted on.\n* ACTIVE - Account group is active - full functionality of the Investment API is accessible.\n* CLOSING - Account group is closing.\n* CLOSED - Account group is closed.\n* LOCKED - Account group is locked for all actions.", "enum": [ "PENDING_APPROVAL", "ACTIVE", "CLOSING", "CLOSED", "LOCKED" ] }, "type": { "type": "string", "description": "Account group type.\n* PERSONAL - Account group of a person holding assets on their own behalf.\n* LEGAL_ENTITY - Account group of a legal entity holding assets on behalf of their users.\n* FRENCH_PEA - Account group of a french resident holding assets in Plan d'Epargne en Actions.\n* ISA - Account group of a UK resident holding assets in an individual savings account.\n* CHILD - Account group of a child user holding assets in a child account.", "enum": [ "PERSONAL", "LEGAL_ENTITY", "FRENCH_PEA", "ISA", "CHILD" ] }, "securities_account_number": { "title": "Securities Account number.", "type": "string", "description": "Account unique identifier.", "format": "^\\d{7,12}$" } }, "required": [ "id", "created_at", "updated_at", "users", "status", "type", "securities_account_number" ], "additionalProperties": false }, { "title": "Business Account Group", "type": "object", "description": "", "properties": { "id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "business_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "status": { "type": "string", "description": "Status of the account group\n* PENDING_APPROVAL - Account group approval is pending - the account group is visible through our API but cannot be acted on.\n* ACTIVE - Account group is active - full functionality of the Investment API is accessible.\n* CLOSING - Account group is closing.\n* CLOSED - Account group is closed.\n* LOCKED - Account group is locked for all actions.", "enum": [ "PENDING_APPROVAL", "ACTIVE", "CLOSING", "CLOSED", "LOCKED" ] }, "type": { "type": "string", "description": "Account group type.\n* BUSINESS - Account group of a business holding assets.", "enum": [ "BUSINESS" ] }, "securities_account_number": { "title": "Securities Account number.", "type": "string", "description": "Account unique identifier.", "format": "^\\d{7,12}$" } }, "required": [ "id", "created_at", "updated_at", "business_id", "status", "type", "securities_account_number" ], "additionalProperties": false } ] } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "examples": { "User Account Group": { "summary": "User account group", "value": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1, "sort": "created_at", "order": "ASC" }, "data": [ { "id": "9d95820d-4333-46b6-98de-04ab7512e76f", "created_at": "2020-08-24T14:15:22Z", "updated_at": "2020-08-24T14:15:22Z", "type": "PERSONAL", "status": "ACTIVE", "users": [ { "id": "9c36af78-91a0-4174-a515-fc81214e3dab", "type": "OWNER" } ], "securities_account_number": "123456789" } ] } }, "Business Account Group": { "summary": "Business account group", "value": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1, "sort": "created_at", "order": "ASC" }, "data": [ { "id": "9d95820d-4333-46b6-98de-04ab7512e76f", "created_at": "2020-08-24T14:15:22Z", "updated_at": "2020-08-24T14:15:22Z", "type": "BUSINESS", "status": "ACTIVE", "business_id": "bc6f8c82-1234-4b56-a7d8-9e012345f678", "securities_account_number": "123456789" } ] } } } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "post": { "operationId": "create_account_group", "summary": "Create an account group", "description": "Creates an account group.", "tags": [ "Account Groups" ], "security": [ { "oauth-client-credentials": [ "accounts:admin" ] } ], "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$", "example": "ccb07f42-4104-44ad-8e1f-c660bb7b269c" }, "description": "A UUID to be used as an idempotency key. This prevents a duplicate request from being replayed.\nhttps://docs.upvest.co/documentation/concepts/api_concepts/idempotency\n" } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Account Group - Create - Request", "oneOf": [ { "title": "Account Group - Create - User Request", "type": "object", "properties": { "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "type": { "type": "string", "description": "Account group type.\n* PERSONAL - Account group of a person holding assets on their own behalf.\n* LEGAL_ENTITY - Account group of a legal entity holding assets on behalf of their users.\n* FRENCH_PEA - Account group of a french resident holding assets in Plan d'Epargne en Actions.\n* ISA - Account group of a UK resident holding assets in an individual savings account.\n* CHILD - Account group of a child user holding assets in a child account.", "enum": [ "PERSONAL", "LEGAL_ENTITY", "FRENCH_PEA", "ISA", "CHILD" ] }, "securities_account_number": { "title": "Securities Account number.", "type": "string", "description": "Account unique identifier.", "format": "^\\d{7,12}$" } }, "required": [ "user_id", "type" ], "additionalProperties": false }, { "title": "Account Group - Create - Business Request", "type": "object", "properties": { "business_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "type": { "type": "string", "description": "Account group type.\n* BUSINESS - Account group of a business holding assets.", "enum": [ "BUSINESS" ] }, "securities_account_number": { "title": "Securities Account number.", "type": "string", "description": "Account unique identifier.", "format": "^\\d{7,12}$" } }, "required": [ "business_id", "type" ], "additionalProperties": false } ] }, "examples": { "User Account Group": { "summary": "User account group", "value": { "user_id": "413715f2-5401-4b97-8055-034a6b879f8c", "type": "PERSONAL", "securities_account_number": "12345689" } }, "Business Account Group": { "summary": "Business account group", "value": { "business_id": "bc6f8c82-1234-4b56-a7d8-9e012345f678", "type": "BUSINESS", "securities_account_number": "12345689" } } } } } }, "responses": { "200": { "description": "Account group created.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Account Group - Create - Response", "oneOf": [ { "title": "Account Group", "type": "object", "description": "", "properties": { "id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "type": { "type": "string", "description": "Relation type\n* OWNER - Account Group Owner\n* CHILD - Child Account Group Owner\n* GUARDIAN - Child Account Group Guardian", "enum": [ "OWNER", "CHILD", "GUARDIAN" ] } } } }, "status": { "type": "string", "description": "Status of the account group\n* PENDING_APPROVAL - Account group approval is pending - the account group is visible through our API but cannot be acted on.\n* ACTIVE - Account group is active - full functionality of the Investment API is accessible.\n* CLOSING - Account group is closing.\n* CLOSED - Account group is closed.\n* LOCKED - Account group is locked for all actions.", "enum": [ "PENDING_APPROVAL", "ACTIVE", "CLOSING", "CLOSED", "LOCKED" ] }, "type": { "type": "string", "description": "Account group type.\n* PERSONAL - Account group of a person holding assets on their own behalf.\n* LEGAL_ENTITY - Account group of a legal entity holding assets on behalf of their users.\n* FRENCH_PEA - Account group of a french resident holding assets in Plan d'Epargne en Actions.\n* ISA - Account group of a UK resident holding assets in an individual savings account.\n* CHILD - Account group of a child user holding assets in a child account.", "enum": [ "PERSONAL", "LEGAL_ENTITY", "FRENCH_PEA", "ISA", "CHILD" ] }, "securities_account_number": { "title": "Securities Account number.", "type": "string", "description": "Account unique identifier.", "format": "^\\d{7,12}$" } }, "required": [ "id", "created_at", "updated_at", "users", "status", "type", "securities_account_number" ], "additionalProperties": false }, { "title": "Business Account Group", "type": "object", "description": "", "properties": { "id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "business_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "status": { "type": "string", "description": "Status of the account group\n* PENDING_APPROVAL - Account group approval is pending - the account group is visible through our API but cannot be acted on.\n* ACTIVE - Account group is active - full functionality of the Investment API is accessible.\n* CLOSING - Account group is closing.\n* CLOSED - Account group is closed.\n* LOCKED - Account group is locked for all actions.", "enum": [ "PENDING_APPROVAL", "ACTIVE", "CLOSING", "CLOSED", "LOCKED" ] }, "type": { "type": "string", "description": "Account group type.\n* BUSINESS - Account group of a business holding assets.", "enum": [ "BUSINESS" ] }, "securities_account_number": { "title": "Securities Account number.", "type": "string", "description": "Account unique identifier.", "format": "^\\d{7,12}$" } }, "required": [ "id", "created_at", "updated_at", "business_id", "status", "type", "securities_account_number" ], "additionalProperties": false } ] }, "examples": { "User Account Group": { "summary": "User account group", "value": { "id": "9d95820d-4333-46b6-98de-04ab7512e76f", "created_at": "2020-08-24T14:15:22Z", "updated_at": "2020-08-24T14:15:22Z", "type": "PERSONAL", "status": "ACTIVE", "users": [ { "id": "413715f2-5401-4b97-8055-034a6b879f8c", "type": "OWNER" } ], "securities_account_number": "123456789" } }, "Business Account Group": { "summary": "Business account group", "value": { "id": "9d95820d-4333-46b6-98de-04ab7512e76f", "created_at": "2020-08-24T14:15:22Z", "updated_at": "2020-08-24T14:15:22Z", "type": "BUSINESS", "status": "ACTIVE", "business_id": "bc6f8c82-1234-4b56-a7d8-9e012345f678", "securities_account_number": "123456789" } } } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/accounts": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_accounts", "summary": "Get accounts", "description": "Returns a list of all accounts.", "tags": [ "Accounts" ], "security": [ { "oauth-client-credentials": [ "accounts:read", "accounts:admin" ] } ], "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "updated_at" ], "default": "created_at" }, "description": "Sort the result by `created_at`, `updated_at§`." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Accounts - List - Response", "type": "object", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "items": { "oneOf": [ { "title": "Account", "type": "object", "description": "", "properties": { "id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "type": { "type": "string", "description": "Account type.\n* TRADING - Orders in accounts of this type are created on a specific instrument basis.\n* PORTFOLIO - Orders in accounts of this type are created on a portfolio basis and additional portfolio functionality is available.", "enum": [ "TRADING", "PORTFOLIO" ] }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "type": { "type": "string", "description": "Relation type\n* OWNER - Account Group Owner\n* CHILD - Child Account Group Owner\n* GUARDIAN - Child Account Group Guardian", "enum": [ "OWNER", "GUARDIAN", "CHILD" ] } } } }, "account_number": { "type": "integer", "description": "The serial account number of the account in the account group.", "minimum": 1 }, "name": { "type": "string", "description": "The name of the account.", "maxLength": 100 }, "status": { "type": "string", "description": "The status of the account\n* PENDING_APPROVAL - Account approval is pending - the account is visible through our API but cannot be acted on.\n* ACTIVE - Account is active - full functionality of the Investment API is accessible.\n* CLOSING - Account is closing - only sell orders or the transfer of positions out are permissible before the account is closed.\n* CLOSED - Account is closed with zero balance successfully.\n* LOCKED - Account is locked for all actions.", "enum": [ "PENDING_APPROVAL", "ACTIVE", "CLOSING", "CLOSED", "LOCKED" ] } }, "required": [ "id", "created_at", "updated_at", "account_group_id", "type", "users", "name", "status", "account_number" ], "additionalProperties": false }, { "title": "Business Account", "type": "object", "description": "", "properties": { "id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "type": { "type": "string", "description": "Account type.\n* TRADING - Orders in accounts of this type are created on a specific instrument basis.\n* PORTFOLIO - Orders in accounts of this type are created on a portfolio basis and additional portfolio functionality is available.", "enum": [ "TRADING", "PORTFOLIO" ] }, "business_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "account_number": { "type": "integer", "description": "The serial account number of the account in the account group.", "minimum": 1 }, "name": { "type": "string", "description": "The name of the account.", "maxLength": 100 }, "status": { "type": "string", "description": "The status of the account\n* PENDING_APPROVAL - Account approval is pending - the account is visible through our API but cannot be acted on.\n* ACTIVE - Account is active - full functionality of the Investment API is accessible.\n* CLOSING - Account is closing - only sell orders or the transfer of positions out are permissible before the account is closed.\n* CLOSED - Account is closed with zero balance successfully.\n* LOCKED - Account is locked for all actions.", "enum": [ "PENDING_APPROVAL", "ACTIVE", "CLOSING", "CLOSED", "LOCKED" ] } }, "required": [ "id", "created_at", "updated_at", "account_group_id", "type", "business_id", "name", "status", "account_number" ], "additionalProperties": false } ] } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "examples": { "User Account": { "summary": "User account", "value": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1, "sort": "created_at", "order": "ASC" }, "data": [ { "id": "ad45b27f-c0e7-4cfb-b48c-a83670dbdfbd", "created_at": "2020-08-24T14:15:22Z", "updated_at": "2020-08-24T14:15:22Z", "account_group_id": "fa2414ed-8d62-46fd-85ed-565a340c81d6", "type": "TRADING", "users": [ { "id": "9c36af78-91a0-4174-a515-fc81214e3dab", "type": "OWNER" } ], "account_number": 1, "name": "Main account", "status": "ACTIVE" } ] } }, "Business Account": { "summary": "Business account", "value": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1, "sort": "created_at", "order": "ASC" }, "data": [ { "id": "ad45b27f-c0e7-4cfb-b48c-a83670dbdfbd", "created_at": "2020-08-24T14:15:22Z", "updated_at": "2020-08-24T14:15:22Z", "account_group_id": "fa2414ed-8d62-46fd-85ed-565a340c81d6", "business_id": "bc6f8c82-1234-4b56-a7d8-9e012345f678", "type": "TRADING", "account_number": 1, "name": "Main account", "status": "ACTIVE" } ] } } } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "post": { "operationId": "create_account", "summary": "Create an account", "description": "Creates an account.", "tags": [ "Accounts" ], "security": [ { "oauth-client-credentials": [ "accounts:admin" ] } ], "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$", "example": "ccb07f42-4104-44ad-8e1f-c660bb7b269c" }, "description": "A UUID to be used as an idempotency key. This prevents a duplicate request from being replayed.\nhttps://docs.upvest.co/documentation/concepts/api_concepts/idempotency\n" } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Account - Create - Request", "oneOf": [ { "title": "Account - Create - User Request", "type": "object", "properties": { "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "type": { "type": "string", "description": "Account type.\n* TRADING - Orders in accounts of this type are created on a specific instrument basis.\n* PORTFOLIO - Orders in accounts of this type are created on a portfolio basis and additional portfolio functionality is available.", "enum": [ "TRADING", "PORTFOLIO" ] }, "name": { "type": "string", "description": "The name of the account.", "maxLength": 100 } }, "required": [ "user_id", "account_group_id", "type" ], "additionalProperties": false }, { "title": "Account - Create - Business Request", "type": "object", "properties": { "business_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "type": { "type": "string", "description": "Account type.\n* TRADING - Orders in accounts of this type are created on a specific instrument basis.\n* PORTFOLIO - Orders in accounts of this type are created on a portfolio basis and additional portfolio functionality is available.", "enum": [ "TRADING", "PORTFOLIO" ] }, "name": { "type": "string", "description": "The name of the account.", "maxLength": 100 } }, "required": [ "business_id", "account_group_id", "type" ], "additionalProperties": false } ] }, "examples": { "User Account": { "summary": "User account", "value": { "user_id": "413715f2-5401-4b97-8055-034a6b879f8c", "account_group_id": "fa2414ed-8d62-46fd-85ed-565a340c81d6", "type": "TRADING", "name": "Main account" } }, "Business Account": { "summary": "Business account", "value": { "business_id": "bc6f8c82-1234-4b56-a7d8-9e012345f678", "account_group_id": "fa2414ed-8d62-46fd-85ed-565a340c81d6", "type": "TRADING", "name": "Main account" } } } } } }, "responses": { "200": { "description": "Account created.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Account - Create - Response", "oneOf": [ { "title": "Account", "type": "object", "description": "", "properties": { "id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "type": { "type": "string", "description": "Account type.\n* TRADING - Orders in accounts of this type are created on a specific instrument basis.\n* PORTFOLIO - Orders in accounts of this type are created on a portfolio basis and additional portfolio functionality is available.", "enum": [ "TRADING", "PORTFOLIO" ] }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "type": { "type": "string", "description": "Relation type\n* OWNER - Account Group Owner\n* CHILD - Child Account Group Owner\n* GUARDIAN - Child Account Group Guardian", "enum": [ "OWNER", "GUARDIAN", "CHILD" ] } } } }, "account_number": { "type": "integer", "description": "The serial account number of the account in the account group.", "minimum": 1 }, "name": { "type": "string", "description": "The name of the account.", "maxLength": 100 }, "status": { "type": "string", "description": "The status of the account\n* PENDING_APPROVAL - Account approval is pending - the account is visible through our API but cannot be acted on.\n* ACTIVE - Account is active - full functionality of the Investment API is accessible.\n* CLOSING - Account is closing - only sell orders or the transfer of positions out are permissible before the account is closed.\n* CLOSED - Account is closed with zero balance successfully.\n* LOCKED - Account is locked for all actions.", "enum": [ "PENDING_APPROVAL", "ACTIVE", "CLOSING", "CLOSED", "LOCKED" ] } }, "required": [ "id", "created_at", "updated_at", "account_group_id", "type", "users", "name", "status", "account_number" ], "additionalProperties": false }, { "title": "Business Account", "type": "object", "description": "", "properties": { "id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "type": { "type": "string", "description": "Account type.\n* TRADING - Orders in accounts of this type are created on a specific instrument basis.\n* PORTFOLIO - Orders in accounts of this type are created on a portfolio basis and additional portfolio functionality is available.", "enum": [ "TRADING", "PORTFOLIO" ] }, "business_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "account_number": { "type": "integer", "description": "The serial account number of the account in the account group.", "minimum": 1 }, "name": { "type": "string", "description": "The name of the account.", "maxLength": 100 }, "status": { "type": "string", "description": "The status of the account\n* PENDING_APPROVAL - Account approval is pending - the account is visible through our API but cannot be acted on.\n* ACTIVE - Account is active - full functionality of the Investment API is accessible.\n* CLOSING - Account is closing - only sell orders or the transfer of positions out are permissible before the account is closed.\n* CLOSED - Account is closed with zero balance successfully.\n* LOCKED - Account is locked for all actions.", "enum": [ "PENDING_APPROVAL", "ACTIVE", "CLOSING", "CLOSED", "LOCKED" ] } }, "required": [ "id", "created_at", "updated_at", "account_group_id", "type", "business_id", "name", "status", "account_number" ], "additionalProperties": false } ] }, "examples": { "User Account": { "summary": "User account", "value": { "id": "ad45b27f-c0e7-4cfb-b48c-a83670dbdfbd", "created_at": "2020-08-24T14:15:22Z", "updated_at": "2020-08-24T14:15:22Z", "account_group_id": "fa2414ed-8d62-46fd-85ed-565a340c81d6", "type": "TRADING", "users": [ { "id": "9c36af78-91a0-4174-a515-fc81214e3dab", "type": "OWNER" } ], "account_number": 1, "name": "Main account", "status": "ACTIVE" } }, "Business Account": { "summary": "Business account", "value": { "id": "ad45b27f-c0e7-4cfb-b48c-a83670dbdfbd", "created_at": "2020-08-24T14:15:22Z", "updated_at": "2020-08-24T14:15:22Z", "account_group_id": "fa2414ed-8d62-46fd-85ed-565a340c81d6", "business_id": "bc6f8c82-1234-4b56-a7d8-9e012345f678", "type": "TRADING", "account_number": 1, "name": "Main account", "status": "ACTIVE" } } } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/accounts/{account_id}/orders": { "parameters": [ { "name": "account_id", "in": "path", "required": true, "description": "The unique identifier of the account. Universally Unique Identifier (UUID).", "schema": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_account_orders", "summary": "Get orders for an account by ID", "description": "Returns a paginated list of orders for the account specified by its ID, including their statuses, executions, and fee configurations.\n\nSee the Orders guide ([TOL](https://docs.upvest.co/products/tol/guides/orders) / [BYOL](https://docs.upvest.co/products/byol/guides/orders) / [Omnibus](https://docs.upvest.co/products/omnibus/guides/orders)) for order lifecycle details.", "tags": [ "Orders" ], "security": [ { "oauth-client-credentials": [ "orders:read", "orders:admin" ] } ], "parameters": [ { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, { "name": "account_group_id", "in": "query", "required": false, "description": "Filters results by account group ID. Universally Unique Identifier (UUID).", "schema": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } }, { "name": "user_id", "in": "query", "required": false, "description": "Filters results by user ID. Universally Unique Identifier (UUID).", "schema": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "NEW", "PROCESSING", "FILLED", "CANCELLED" ], "default": "FILLED" }, "description": "The execution status of the order.\n* NEW - \n* PROCESSING - \n* FILLED - \n* CANCELLED - " }, { "name": "date_created_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "title": "Date in YYYY-MM-DD format. RFC 3339, section 5.6" }, "description": "Filters results to those created at or after this timestamp. [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) date-time format (e.g. `2024-01-01`).", "example": "2022-10-14T10:10:10Z" }, { "name": "date_created_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "title": "Date in YYYY-MM-DD format. RFC 3339, section 5.6" }, "description": "Filters results to those created at or before this timestamp. [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) date-time format (e.g. `2024-12-31T23:59:59Z`).", "example": "2022-10-14T10:10:10Z" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Orders - List - Response", "type": "object", "description": "Paginated list of orders for the specified account, including cursor-based pagination metadata.", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "items": { "title": "Order", "type": "object", "description": "Represents an investment order placed by an end user or on their behalf. An order transitions through states (`NEW` → `PROCESSING` → `FILLED` or `CANCELLED`) as it is routed and executed.", "properties": { "id": { "title": "Order unique identifier", "type": "string", "description": "Unique identifier for an order. Universally Unique Identifier (UUID).", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "type": "string", "format": "uuid", "description": "The ID of the user. Either user ID or business ID must be specified." }, "business_id": { "type": "string", "format": "uuid", "description": "The ID of the business. Either user ID or business ID must be specified." }, "account_id": { "type": "string", "format": "uuid", "description": "The ID of the account that owns the order" }, "cash_amount": { "allOf": [ { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, { "description": "Cash amount for a nominal order, not required if a share quantity is specified." } ] }, "currency": { "allOf": [ { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound\n* USD - US Dollar", "enum": [ "EUR", "GBP", "USD" ] }, { "description": "The currency for the order." } ] }, "side": { "type": "string", "description": "Side of the order.\n* BUY — purchases the specified instrument.\n* SELL — disposes of the specified instrument.", "enum": [ "BUY", "SELL" ] }, "instrument_id": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, "instrument_id_type": { "description": "The type of the ID used in the request.\n* ISIN - ", "enum": [ "ISIN" ], "default": "ISIN", "type": "string" }, "order_type": { "type": "string", "description": "Type of the order.\n* MARKET — executes immediately at the best available market price.\n* LIMIT — executes only at or better than the specified `limit_price`.\n* STOP — triggers when the market price reaches `stop_price`, then executes at the prevailing market price.", "enum": [ "MARKET", "LIMIT", "STOP" ] }, "quantity": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "Quantity of securities for the order. Only required if the cash amount is not specified." } ] }, "user_instrument_fit_acknowledgement": { "type": "boolean", "description": "Only applicable if the user has failed the instrument fit check for the instrument type being ordered. True if the user has acknowledged their willingness to trade." }, "limit_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The limit price for orders of the type 'limit'." } ] }, "stop_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The stop price for orders of the type 'stop'." } ] }, "expiry_date": { "allOf": [ { "title": "Expiry date", "type": "string", "description": "Order expiration date in YYYY-MM-DD format. Only applicable to `LIMIT` and `STOP` orders — the order will not execute after this date. Defaults to order creation date plus 359 days.", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, { "description": "The order expiration date (last day the order can trade) in the YYYY-MM-DD format. The expiry date can only be set for LIMIT and STOP orders. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339. The default value is order creation date + 359 days" } ] }, "status": { "type": "string", "description": "The execution status of the order.\n* NEW — the order has been received and validated, awaiting routing.\n* PROCESSING — the order is being routed for execution.\n* FILLED — the order has been fully executed.\n* CANCELLED — the order was cancelled before being fully executed.", "enum": [ "NEW", "PROCESSING", "FILLED", "CANCELLED" ] }, "fee": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "cancellation_reason": { "type": "string", "description": "Reason for order cancellation. Present only when `status` is `CANCELLED`.\n* CANCELLED_BY_CLIENT — cancelled at the end user's or client's request via the API.\n* CANCELLED_BY_UPVEST_OPERATIONS — cancelled by Upvest operations.\n* CANCELLED_BY_TRADING_PARTNER — cancelled by the executing partner.\n* CANCELLED_BY_UPVEST_PLATFORM — cancelled automatically by the Upvest platform.", "enum": [ "CANCELLED_BY_CLIENT", "CANCELLED_BY_UPVEST_OPERATIONS", "CANCELLED_BY_TRADING_PARTNER", "CANCELLED_BY_UPVEST_PLATFORM" ] }, "initiation_flow": { "type": "string", "description": "Identifies what triggered the order.\n* API — initiated directly via the client API.\n* PORTFOLIO — initiated by a portfolio rebalancing flow.\n* CASH_DIVIDEND_REINVESTMENT — initiated as part of dividend reinvestment.\n* PORTFOLIO_REBALANCING — initiated by an automated rebalancing.\n* SELL_TO_COVER_FEES — initiated automatically to cover outstanding fees.\n* SELL_TO_COVER_TAXES — initiated automatically to cover tax obligations.\n* ACCOUNT_LIQUIDATION — initiated as part of an account liquidation.\n* UPVEST_OPERATIONS — initiated by Upvest operations.\n* SAVINGS_PLAN — initiated by a savings plan execution.\n* CLIENT_OPERATIONS — initiated by client operations.", "enum": [ "API", "PORTFOLIO", "CASH_DIVIDEND_REINVESTMENT", "PORTFOLIO_REBALANCING", "SELL_TO_COVER_FEES", "SELL_TO_COVER_TAXES", "ACCOUNT_LIQUIDATION", "UPVEST_OPERATIONS", "SAVINGS_PLAN", "CLIENT_OPERATIONS" ] }, "execution_flow": { "type": "string", "description": "Execution flow for order processing. Defaults to `STRAIGHT_THROUGH` if not specified.\n* STRAIGHT_THROUGH — the order is routed and executed directly without manual intervention.\n* BLOCK — the order is bundled with other orders for block execution.", "enum": [ "STRAIGHT_THROUGH", "BLOCK" ] }, "executions": { "type": "array", "description": "Order executions associated with this order", "items": { "title": "Order execution", "type": "object", "description": "Represents a single execution (trade fill) within an order. An order may have multiple executions if it is partially filled across several trades.", "properties": { "id": { "title": "Order execution unique identifier", "type": "string", "format": "uuid" }, "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "share_quantity": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "price": { "type": "string", "description": "Price of an instrument for a trade execution provided as a decimal string.", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,4})?$" }, "transaction_time": { "type": "string", "format": "date-time", "description": "Timestamp of when the trade was executed at the market. [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) date-time format." }, "taxes": { "type": "array", "description": "Taxes deducted as part of this execution.", "items": { "title": "Tax", "type": "object", "description": "Tax deducted as part of an order execution. Contains the tax type and the deducted amount.", "properties": { "type": { "type": "string", "description": "Tax type\n* TOTAL - ", "default": "TOTAL", "enum": [ "TOTAL" ] }, "amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" } }, "required": [ "type", "amount" ] } }, "order_id": { "title": "Order unique identifier", "type": "string", "description": "Unique identifier for an order. Universally Unique Identifier (UUID).", "format": "uuid" }, "status": { "type": "string", "description": "Status of the execution.\n* FILLED — the execution has been filled.\n* SETTLED — the execution has settled and securities and cash have been exchanged.\n* CANCELLED — the execution was cancelled before settlement.", "enum": [ "FILLED", "SETTLED", "CANCELLED" ] }, "side": { "type": "string", "description": "Side of the execution.\n* BUY — a buy execution.\n* SELL — a sell execution.", "enum": [ "BUY", "SELL" ] }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound\n* USD - US Dollar", "enum": [ "EUR", "GBP", "USD" ] }, "settlement_date": { "allOf": [ { "title": "Settlement date", "type": "string", "description": "Trade settlement date in YYYY-MM-DD format. The date on which securities and cash are exchanged following execution.", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, { "description": "Order execution settlement date in the YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339" } ] }, "venue_id": { "type": "string", "format": "uuid", "description": "The ID of the venue" } }, "required": [ "id", "cash_amount", "share_quantity", "price", "transaction_time", "taxes", "order_id", "status", "side", "currency", "venue_id" ], "additionalProperties": false } }, "client_reference": { "type": "string", "description": "Immutable reference to the API flow that initiated the order. For client initiated API flows, this is a client provided ID. For internal initiations, it is set to the ID of the related object.", "maxLength": 100 }, "fee_configuration": { "type": "array", "description": "Fee configuration applied to this order. Determines how the order fee is calculated.", "items": { "title": "Fee", "description": "A fee applied to an order. Either a fixed absolute cash fee (`absolute_fee_configuration_item`) or a reference to a predefined transaction fee model.", "oneOf": [ { "title": "Absolute Fee", "type": "object", "description": "A fixed cash fee applied to an order, specified as an absolute amount in a given currency.", "properties": { "type": { "title": "Fee type", "description": "Fee type\n* TRANSACTION_FEE_BUY - \n* TRANSACTION_FEE_SELL - ", "type": "string", "enum": [ "TRANSACTION_FEE_BUY", "TRANSACTION_FEE_SELL" ] }, "value_type": { "type": "string", "default": "ABSOLUTE", "description": "The value type must be “ABSOLUTE”." }, "charge_method": { "title": "Fee charge method", "type": "string", "description": "Indicates whether the fee will be charged by client or by other methods.\n* CHARGED_BY_CLIENT - \n* COLLECTED_BY_UPVEST - ", "enum": [ "CHARGED_BY_CLIENT", "COLLECTED_BY_UPVEST" ] }, "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound\n* USD - US Dollar", "enum": [ "EUR", "GBP", "USD" ] } }, "required": [ "type", "value_type", "charge_method", "cash_amount", "currency" ], "additionalProperties": false }, { "title": "Transaction Fee Model", "type": "object", "description": "A fee configuration that references a predefined transaction fee model by its ID, rather than specifying a fee amount directly.", "properties": { "type": { "title": "Fee type", "description": "Fee type\n* TRANSACTION_FEE_BUY - \n* TRANSACTION_FEE_SELL - ", "type": "string", "enum": [ "TRANSACTION_FEE_BUY", "TRANSACTION_FEE_SELL" ] }, "transaction_fee_model_id": { "type": "string", "format": "uuid", "description": "The ID of the transaction fee model." } }, "required": [ "type", "transaction_fee_model_id" ], "additionalProperties": false } ] } }, "decision_maker_id": { "type": "string", "description": "ID of the user behind the decision to place an order. Required only if different from the user_id. (e.g. child account order placed by a guardian)" } }, "required": [ "id", "created_at", "updated_at", "account_id", "cash_amount", "currency", "side", "instrument_id", "instrument_id_type", "order_type", "quantity", "status", "fee", "initiation_flow", "executions" ], "additionalProperties": false } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "example": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1, "sort": "id", "order": "ASC" }, "data": [ { "id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "user_id": "2dedfeb0-58cd-44f2-ae08-0e41fe0413d9", "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3", "cash_amount": "56.65", "currency": "EUR", "side": "BUY", "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "order_type": "MARKET", "quantity": "0.05", "user_instrument_fit_acknowledgement": true, "limit_price": "", "stop_price": "", "status": "FILLED", "fee": "0.5", "executions": [ { "id": "b9dc0676-8a7d-412d-802a-3b325eefd15e", "side": "BUY", "currency": "EUR", "status": "FILLED", "order_id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c", "cash_amount": "56.65", "share_quantity": "0.05", "price": "130.65", "transaction_time": "2021-07-21T14:10:00.00Z", "taxes": [ { "amount": "1.3", "type": "TOTAL" } ], "venue_id": "20d6024b-2df4-41ae-8d42-62e4744e455b" } ], "client_reference": "", "initiation_flow": "API" } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/transaction_fees/models": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_transaction_fee_models", "summary": "List transaction fee models", "description": "Returns a paginated list of the transaction fee models created for your client account.\n\nUse the `offset` and `limit` query parameters to page through results; `meta.total_count` gives the total number of matching fee models.\n\nSee the Transaction fees guide ([TOL](https://docs.upvest.co/products/tol/guides/fees/fees_transaction_fees_overview) / [BYOL](https://docs.upvest.co/products/byol/guides/fees/fees_transaction_fees_overview)) for fee model concepts.", "tags": [ "Transaction Fees Models" ], "security": [ { "oauth-client-credentials": [ "transaction_fees:admin", "transaction_fees:read" ] } ], "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "updated_at" ], "default": "created_at" }, "description": "The field to sort the results by, either `created_at` or `updated_at`." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Transaction Fee Models - List - Response", "type": "object", "description": "Paginated list of transaction fee models. Contains a `data` array of transaction fee model objects and a `meta` object with offset/limit pagination metadata.", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "description": "List of transaction fee models matching the query.", "items": { "title": "Fee Configuration", "type": "object", "description": "A transaction fee model. Defines how per-order transaction fees are calculated, as a set of tiers with either absolute cash amounts or relative basis-point values. Assign a model to an order via the `fee_configuration` array when placing the order.", "properties": { "id": { "title": "Fee model unique identifier.", "type": "string", "description": "Universally Unique Identifier (UUID) of the transaction fee model.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "label": { "title": "Label", "description": "A human-readable label for the transaction fee model.", "type": "string" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "charge_method": { "title": "Fee charge method", "type": "string", "description": "Indicates how the transaction fee is charged.\n* `CHARGED_BY_CLIENT` — The fee is charged by the client as part of post-trade settlement; the fee movement occurs outside Upvest cash balances.", "enum": [ "CHARGED_BY_CLIENT" ] }, "value_type": { "title": "Value Type", "type": "string", "description": "The value type of the transaction fee model.\n* `ABSOLUTE` — Tier fees are fixed cash amounts.\n* `RELATIVE` — Tier fees are percentages of the order value, expressed in basis points.", "enum": [ "ABSOLUTE", "RELATIVE" ] }, "application_type": { "title": "Application Type", "type": "string", "description": "The application type of the transaction fee model.\n* `VOLUME` — The full order value is assessed against the tier thresholds, and the matching tier's fee applies to the total order volume.", "enum": [ "VOLUME" ] }, "base_amount_scope": { "title": "Base Amount Scope", "type": "string", "description": "The scope of the base amount that fee tiers are evaluated against.\n* `ORDER` — Tiers are evaluated against the total cash value of each order.", "enum": [ "ORDER" ] }, "tiers": { "description": "The tiers of the transaction fee model.", "type": "array", "items": { "title": "Fee Tier", "description": "A single tier of a transaction fee model — either an absolute tier with a fixed cash amount or a relative tier defined in basis points.", "oneOf": [ { "title": "Absolute Transaction Fee Tier", "description": "A single tier of a transaction fee model with a fixed, absolute cash amount.", "type": "object", "properties": { "tier_id": { "title": "The unique identifier for the fee tier.", "type": "string", "description": "Unique identifier of the fee tier within the transaction fee model. A numeric string of up to 63 digits.", "pattern": "^[0-9]{1,63}$" }, "base_amount_from": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "fee_amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" } }, "required": [ "tier_id", "base_amount_from", "fee_amount" ] }, { "title": "Relative Transaction Fee Tier", "description": "A single tier of a transaction fee model based on a percentage (defined in basis points).", "type": "object", "properties": { "tier_id": { "title": "The unique identifier for the fee tier.", "type": "string", "description": "Unique identifier of the fee tier within the transaction fee model. A numeric string of up to 63 digits.", "pattern": "^[0-9]{1,63}$" }, "base_amount_from": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "fee_bps": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "min_fee_amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "max_fee_amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" } }, "required": [ "tier_id", "base_amount_from", "fee_bps" ] } ] } } }, "required": [ "id", "created_at", "updated_at", "label", "currency", "charge_method", "value_type", "application_type", "base_amount_scope", "tiers" ], "additionalProperties": false } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "examples": { "list_transaction_fee_models": { "summary": "List Transaction Fee Models", "value": { "meta": { "offset": 0, "limit": 100, "count": 5, "total_count": 5, "sort": "id", "order": "ASC" }, "data": [ { "id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "label": "absolute fee amount - flat fee model (only 1 tier specified)", "currency": "EUR", "charge_method": "CHARGED_BY_CLIENT", "value_type": "ABSOLUTE", "application_type": "VOLUME", "base_amount_scope": "ORDER", "tiers": [ { "tier_id": "0", "base_amount_from": "0", "fee_amount": "10" } ] }, { "id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "label": "absolute fee amount - tiered fee model", "currency": "EUR", "charge_method": "CHARGED_BY_CLIENT", "value_type": "ABSOLUTE", "application_type": "VOLUME", "base_amount_scope": "ORDER", "tiers": [ { "tier_id": "0", "base_amount_from": "0", "fee_amount": "10" }, { "tier_id": "1", "base_amount_from": "2000", "fee_amount": "12" }, { "tier_id": "2", "base_amount_from": "4000", "fee_amount": "14" } ] }, { "id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "label": "relative fee (bps) - flat fee model (only 1 tier specified)", "currency": "EUR", "charge_method": "CHARGED_BY_CLIENT", "value_type": "RELATIVE", "application_type": "VOLUME", "base_amount_scope": "ORDER", "tiers": [ { "tier_id": "0", "base_amount_from": "0", "fee_bps": "100" } ] }, { "id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "label": "relative fee (bps) - tiered fee model with lower/upper bound", "currency": "EUR", "charge_method": "CHARGED_BY_CLIENT", "value_type": "RELATIVE", "application_type": "VOLUME", "base_amount_scope": "ORDER", "tiers": [ { "tier_id": "0", "base_amount_from": "0", "fee_bps": "10", "min_fee_amount": "10", "max_fee_amount": "100" }, { "tier_id": "1", "base_amount_from": "2000", "fee_bps": "12", "min_fee_amount": "100", "max_fee_amount": "1000" }, { "tier_id": "2", "base_amount_from": "4000", "fee_bps": "14", "min_fee_amount": "1000", "max_fee_amount": "1111" } ] }, { "id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "label": "relative fee (bps) with a minimum: for orders less than 10.000 1 EUR+1%, for orders more than 10.000 101 EUR+0,5%", "currency": "EUR", "charge_method": "CHARGED_BY_CLIENT", "value_type": "RELATIVE", "application_type": "VOLUME", "base_amount_scope": "ORDER", "tiers": [ { "tier_id": "0", "base_amount_from": "0", "fee_bps": "0", "min_fee_amount": "1" }, { "tier_id": "1", "base_amount_from": "0.01", "fee_bps": "100" }, { "tier_id": "2", "base_amount_from": "10000", "fee_bps": "0", "min_fee_amount": "100" }, { "tier_id": "3", "base_amount_from": "10000.01", "fee_bps": "50" } ] } ] } } } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "409": { "description": "Conflict. An operation is not available for the current state of the resource.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 409, "type": "conflict" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "post": { "operationId": "create_transaction_fee_model", "summary": "Create a transaction fee model", "description": "Creates a transaction fee model that defines how per-order transaction fees are calculated — either as fixed cash amounts (`ABSOLUTE`) or in basis points of the order value (`RELATIVE`), with one or more tiers based on the order's cash amount.\n\nFee models are immutable once created; to change a fee structure, create a new model. Apply a model to an order by referencing its ID in the `fee_configuration` object of the order request.\n\nSee the Building transaction fees guide ([TOL](https://docs.upvest.co/products/tol/guides/fees/fees_transaction_fees_building) / [BYOL](https://docs.upvest.co/products/byol/guides/fees/fees_transaction_fees_building)) for implementation details.", "tags": [ "Transaction Fees Models" ], "security": [ { "oauth-client-credentials": [ "transaction_fees:admin" ] } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Fee configuration - Create - Request", "type": "object", "description": "Request to create a transaction fee model. Defines the currency, charge method, value type, application type, base amount scope, and the fee tiers. Transaction fee models are immutable once created.", "properties": { "label": { "title": "Label", "description": "A human-readable label for the transaction fee model.", "type": "string" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "charge_method": { "title": "Fee charge method", "type": "string", "description": "Indicates how the transaction fee is charged.\n* `CHARGED_BY_CLIENT` — The fee is charged by the client as part of post-trade settlement; the fee movement occurs outside Upvest cash balances.", "enum": [ "CHARGED_BY_CLIENT" ] }, "value_type": { "title": "Value Type", "type": "string", "description": "The value type of the transaction fee model.\n* `ABSOLUTE` — Tier fees are fixed cash amounts.\n* `RELATIVE` — Tier fees are percentages of the order value, expressed in basis points.", "enum": [ "ABSOLUTE", "RELATIVE" ] }, "application_type": { "title": "Application Type", "type": "string", "description": "The application type of the transaction fee model.\n* `VOLUME` — The full order value is assessed against the tier thresholds, and the matching tier's fee applies to the total order volume.", "enum": [ "VOLUME" ] }, "base_amount_scope": { "title": "Base Amount Scope", "type": "string", "description": "The scope of the base amount that fee tiers are evaluated against.\n* `ORDER` — Tiers are evaluated against the total cash value of each order.", "enum": [ "ORDER" ] }, "tiers": { "description": "The tiers of the transaction fee model.", "type": "array", "items": { "title": "Fee Tier", "description": "A single tier of a transaction fee model — either an absolute tier with a fixed cash amount or a relative tier defined in basis points.", "oneOf": [ { "title": "Absolute Transaction Fee Tier", "description": "A single tier of a transaction fee model with a fixed, absolute cash amount.", "type": "object", "properties": { "tier_id": { "title": "The unique identifier for the fee tier.", "type": "string", "description": "Unique identifier of the fee tier within the transaction fee model. A numeric string of up to 63 digits.", "pattern": "^[0-9]{1,63}$" }, "base_amount_from": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "fee_amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" } }, "required": [ "tier_id", "base_amount_from", "fee_amount" ] }, { "title": "Relative Transaction Fee Tier", "description": "A single tier of a transaction fee model based on a percentage (defined in basis points).", "type": "object", "properties": { "tier_id": { "title": "The unique identifier for the fee tier.", "type": "string", "description": "Unique identifier of the fee tier within the transaction fee model. A numeric string of up to 63 digits.", "pattern": "^[0-9]{1,63}$" }, "base_amount_from": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "fee_bps": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "min_fee_amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "max_fee_amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" } }, "required": [ "tier_id", "base_amount_from", "fee_bps" ] } ] } } }, "required": [ "label", "currency", "charge_method", "value_type", "application_type", "base_amount_scope", "tiers" ], "additionalProperties": false }, "examples": { "create_absolute_transaction_fee_model": { "summary": "Create Transaction Fee Model - Absolute", "value": { "label": "transaction fee buy - new year promotion", "currency": "EUR", "charge_method": "CHARGED_BY_CLIENT", "value_type": "ABSOLUTE", "application_type": "VOLUME", "base_amount_scope": "ORDER", "tiers": [ { "tier_id": "0", "base_amount_from": "0", "fee_amount": "10" }, { "tier_id": "1", "base_amount_from": "2000", "fee_amount": "12" }, { "tier_id": "2", "base_amount_from": "4000", "fee_amount": "14" } ] } }, "create_relative_transaction_fee_model": { "summary": "Create Transaction Fee Model - Relative", "value": { "label": "Tiered relative fee model with lower/upper bounds", "currency": "EUR", "charge_method": "CHARGED_BY_CLIENT", "value_type": "RELATIVE", "application_type": "VOLUME", "base_amount_scope": "ORDER", "tiers": [ { "tier_id": "0", "base_amount_from": "0.00", "fee_bps": "300", "min_fee_amount": "1.00" }, { "tier_id": "1", "base_amount_from": "5000.00", "fee_bps": "250", "min_fee_amount": "150.00" }, { "tier_id": "2", "base_amount_from": "10000.00", "fee_bps": "200", "min_fee_amount": "250.00", "max_fee_amount": "300.00" } ] } } } } } }, "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Fee Configuration", "type": "object", "description": "A transaction fee model. Defines how per-order transaction fees are calculated, as a set of tiers with either absolute cash amounts or relative basis-point values. Assign a model to an order via the `fee_configuration` array when placing the order.", "properties": { "id": { "title": "Fee model unique identifier.", "type": "string", "description": "Universally Unique Identifier (UUID) of the transaction fee model.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "label": { "title": "Label", "description": "A human-readable label for the transaction fee model.", "type": "string" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "charge_method": { "title": "Fee charge method", "type": "string", "description": "Indicates how the transaction fee is charged.\n* `CHARGED_BY_CLIENT` — The fee is charged by the client as part of post-trade settlement; the fee movement occurs outside Upvest cash balances.", "enum": [ "CHARGED_BY_CLIENT" ] }, "value_type": { "title": "Value Type", "type": "string", "description": "The value type of the transaction fee model.\n* `ABSOLUTE` — Tier fees are fixed cash amounts.\n* `RELATIVE` — Tier fees are percentages of the order value, expressed in basis points.", "enum": [ "ABSOLUTE", "RELATIVE" ] }, "application_type": { "title": "Application Type", "type": "string", "description": "The application type of the transaction fee model.\n* `VOLUME` — The full order value is assessed against the tier thresholds, and the matching tier's fee applies to the total order volume.", "enum": [ "VOLUME" ] }, "base_amount_scope": { "title": "Base Amount Scope", "type": "string", "description": "The scope of the base amount that fee tiers are evaluated against.\n* `ORDER` — Tiers are evaluated against the total cash value of each order.", "enum": [ "ORDER" ] }, "tiers": { "description": "The tiers of the transaction fee model.", "type": "array", "items": { "title": "Fee Tier", "description": "A single tier of a transaction fee model — either an absolute tier with a fixed cash amount or a relative tier defined in basis points.", "oneOf": [ { "title": "Absolute Transaction Fee Tier", "description": "A single tier of a transaction fee model with a fixed, absolute cash amount.", "type": "object", "properties": { "tier_id": { "title": "The unique identifier for the fee tier.", "type": "string", "description": "Unique identifier of the fee tier within the transaction fee model. A numeric string of up to 63 digits.", "pattern": "^[0-9]{1,63}$" }, "base_amount_from": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "fee_amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" } }, "required": [ "tier_id", "base_amount_from", "fee_amount" ] }, { "title": "Relative Transaction Fee Tier", "description": "A single tier of a transaction fee model based on a percentage (defined in basis points).", "type": "object", "properties": { "tier_id": { "title": "The unique identifier for the fee tier.", "type": "string", "description": "Unique identifier of the fee tier within the transaction fee model. A numeric string of up to 63 digits.", "pattern": "^[0-9]{1,63}$" }, "base_amount_from": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "fee_bps": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "min_fee_amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "max_fee_amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" } }, "required": [ "tier_id", "base_amount_from", "fee_bps" ] } ] } } }, "required": [ "id", "created_at", "updated_at", "label", "currency", "charge_method", "value_type", "application_type", "base_amount_scope", "tiers" ], "additionalProperties": false }, "examples": { "create_absolute_transaction_fee_model": { "summary": "Create Transaction Fee Model - Absolute", "value": { "id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "label": "transaction fee buy - new year promotion", "currency": "EUR", "charge_method": "CHARGED_BY_CLIENT", "value_type": "ABSOLUTE", "application_type": "VOLUME", "base_amount_scope": "ORDER", "tiers": [ { "tier_id": "0", "base_amount_from": "0", "fee_amount": "10" }, { "tier_id": "1", "base_amount_from": "2000", "fee_amount": "12" }, { "tier_id": "2", "base_amount_from": "4000", "fee_amount": "14" } ] } }, "create_relative_transaction_fee_model": { "summary": "Create Transaction Fee Model - Relative", "value": { "id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "label": "Tiered relative fee model with lower/upper bounds", "currency": "EUR", "charge_method": "CHARGED_BY_CLIENT", "value_type": "RELATIVE", "application_type": "VOLUME", "base_amount_scope": "ORDER", "tiers": [ { "tier_id": "0", "base_amount_from": "0.00", "fee_bps": "300", "min_fee_amount": "1.00" }, { "tier_id": "1", "base_amount_from": "5000.00", "fee_bps": "250", "min_fee_amount": "150.00" }, { "tier_id": "2", "base_amount_from": "10000.00", "fee_bps": "200", "min_fee_amount": "250.00", "max_fee_amount": "300.00" } ] } } } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "409": { "description": "Conflict. An operation is not available for the current state of the resource.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 409, "type": "conflict" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/transaction_fees/models/{transaction_fee_model_id}": { "parameters": [ { "name": "transaction_fee_model_id", "in": "path", "description": "The unique identifier of the transaction fee model. Universally Unique Identifier (UUID).", "required": true, "schema": { "title": "Fee model unique identifier.", "type": "string", "description": "Universally Unique Identifier (UUID) of the transaction fee model.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_transaction_fee_model", "summary": "Get transaction fee model", "description": "Returns the transaction fee model with the given ID, including its currency, charge method, value type, and tier structure.\n\nSee the Transaction fees guide ([TOL](https://docs.upvest.co/products/tol/guides/fees/fees_transaction_fees_overview) / [BYOL](https://docs.upvest.co/products/byol/guides/fees/fees_transaction_fees_overview)) for fee model concepts.", "tags": [ "Transaction Fees Models" ], "security": [ { "oauth-client-credentials": [ "transaction_fees:admin", "transaction_fees:read" ] } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Fee Configuration", "type": "object", "description": "A transaction fee model. Defines how per-order transaction fees are calculated, as a set of tiers with either absolute cash amounts or relative basis-point values. Assign a model to an order via the `fee_configuration` array when placing the order.", "properties": { "id": { "title": "Fee model unique identifier.", "type": "string", "description": "Universally Unique Identifier (UUID) of the transaction fee model.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "label": { "title": "Label", "description": "A human-readable label for the transaction fee model.", "type": "string" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "charge_method": { "title": "Fee charge method", "type": "string", "description": "Indicates how the transaction fee is charged.\n* `CHARGED_BY_CLIENT` — The fee is charged by the client as part of post-trade settlement; the fee movement occurs outside Upvest cash balances.", "enum": [ "CHARGED_BY_CLIENT" ] }, "value_type": { "title": "Value Type", "type": "string", "description": "The value type of the transaction fee model.\n* `ABSOLUTE` — Tier fees are fixed cash amounts.\n* `RELATIVE` — Tier fees are percentages of the order value, expressed in basis points.", "enum": [ "ABSOLUTE", "RELATIVE" ] }, "application_type": { "title": "Application Type", "type": "string", "description": "The application type of the transaction fee model.\n* `VOLUME` — The full order value is assessed against the tier thresholds, and the matching tier's fee applies to the total order volume.", "enum": [ "VOLUME" ] }, "base_amount_scope": { "title": "Base Amount Scope", "type": "string", "description": "The scope of the base amount that fee tiers are evaluated against.\n* `ORDER` — Tiers are evaluated against the total cash value of each order.", "enum": [ "ORDER" ] }, "tiers": { "description": "The tiers of the transaction fee model.", "type": "array", "items": { "title": "Fee Tier", "description": "A single tier of a transaction fee model — either an absolute tier with a fixed cash amount or a relative tier defined in basis points.", "oneOf": [ { "title": "Absolute Transaction Fee Tier", "description": "A single tier of a transaction fee model with a fixed, absolute cash amount.", "type": "object", "properties": { "tier_id": { "title": "The unique identifier for the fee tier.", "type": "string", "description": "Unique identifier of the fee tier within the transaction fee model. A numeric string of up to 63 digits.", "pattern": "^[0-9]{1,63}$" }, "base_amount_from": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "fee_amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" } }, "required": [ "tier_id", "base_amount_from", "fee_amount" ] }, { "title": "Relative Transaction Fee Tier", "description": "A single tier of a transaction fee model based on a percentage (defined in basis points).", "type": "object", "properties": { "tier_id": { "title": "The unique identifier for the fee tier.", "type": "string", "description": "Unique identifier of the fee tier within the transaction fee model. A numeric string of up to 63 digits.", "pattern": "^[0-9]{1,63}$" }, "base_amount_from": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "fee_bps": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "min_fee_amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "max_fee_amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" } }, "required": [ "tier_id", "base_amount_from", "fee_bps" ] } ] } } }, "required": [ "id", "created_at", "updated_at", "label", "currency", "charge_method", "value_type", "application_type", "base_amount_scope", "tiers" ], "additionalProperties": false }, "examples": { "retrieve_absolute_transaction_fee_model": { "summary": "Get Transaction Fee Model - Absolute", "value": { "id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "label": "transaction fee buy - new year promotion", "currency": "EUR", "charge_method": "CHARGED_BY_CLIENT", "value_type": "ABSOLUTE", "application_type": "VOLUME", "base_amount_scope": "ORDER", "tiers": [ { "tier_id": "0", "base_amount_from": "0", "fee_amount": "10" }, { "tier_id": "1", "base_amount_from": "2000", "fee_amount": "12" }, { "tier_id": "2", "base_amount_from": "4000", "fee_amount": "14" } ] } }, "retrieve_absolute_transaction_fee_model_with_one_tier": { "summary": "Get Transaction Fee Model - Absolute - With One Tier", "value": { "id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "label": "transaction fee buy - new year promotion", "currency": "EUR", "charge_method": "CHARGED_BY_CLIENT", "value_type": "ABSOLUTE", "application_type": "VOLUME", "base_amount_scope": "ORDER", "tiers": [ { "tier_id": "0", "base_amount_from": "100", "fee_amount": "10" } ] } }, "retrieve_relative_transaction_fee_model": { "summary": "Get Transaction Fee Model - Relative", "value": { "id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "label": "transaction fee buy - new year promotion", "currency": "EUR", "charge_method": "CHARGED_BY_CLIENT", "value_type": "ABSOLUTE", "application_type": "VOLUME", "base_amount_scope": "ORDER", "tiers": [ { "tier_id": "0", "base_amount_from": "0", "fee_bps": "100", "min_fee_amount": "5", "max_fee_amount": "15" }, { "tier_id": "1", "base_amount_from": "2000", "fee_bps": "200", "min_cash_amount": "15", "max_cash_amount": "100" }, { "tier_id": "2", "base_amount_from": "4000", "fee_bps": "300", "min_fee_amount": "100", "max_fee_amount": "200" } ] } } } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "409": { "description": "Conflict. An operation is not available for the current state of the resource.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 409, "type": "conflict" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/fees/configurations": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "post": { "operationId": "create_fee_configuration", "summary": "Create a fee configuration", "description": "Creates a fee configuration for a fee collection.", "tags": [ "Fees Configurations" ], "security": [ { "oauth-client-credentials": [ "fees:admin" ] } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Fee configuration - Create - Request", "type": "object", "properties": { "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "fee_model_id": { "title": "Fee model unique identifier.", "type": "string", "description": "Fee model unique identifier.", "format": "uuid" } }, "required": [ "account_id", "fee_model_id" ], "additionalProperties": false }, "example": { "fee_model_id": "1df86975-06f4-484d-935e-46b54bab2f6c", "account_id": "7524949b-31fd-497e-ad92-f52de45341d1" } } } }, "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Fee Configuration", "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "fee_model_id": { "title": "Fee model unique identifier.", "type": "string", "description": "Fee model unique identifier.", "format": "uuid" } }, "required": [ "account_id", "fee_model_id", "created_at", "updated_at" ], "additionalProperties": false }, "example": { "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "fee_model_id": "1df86975-06f4-484d-935e-46b54bab2f6c", "account_id": "7524949b-31fd-497e-ad92-f52de45341d1" } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "409": { "description": "Conflict. An operation is not available for the current state of the resource.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 409, "type": "conflict" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/fees/configurations/{account_id}": { "parameters": [ { "name": "account_id", "in": "path", "required": true, "description": "The unique identifier of the account. Universally Unique Identifier (UUID).", "schema": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_fee_configurations", "summary": "Get fee configuration", "description": "Retrieve the fee configuration for a specific account.", "tags": [ "Fees Configurations" ], "security": [ { "oauth-client-credentials": [ "fees:read", "fees:admin" ] } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Fee Configuration", "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "fee_model_id": { "title": "Fee model unique identifier.", "type": "string", "description": "Fee model unique identifier.", "format": "uuid" } }, "required": [ "account_id", "fee_model_id", "created_at", "updated_at" ], "additionalProperties": false }, "example": { "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "account_id": "7524949b-31fd-497e-ad92-f52de45341d1", "fee_model_id": "1df86975-06f4-484d-935e-46b54bab2f6c" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "patch": { "operationId": "update_fee_configuration", "summary": "Update fee configuration", "description": "Update fee configuration", "tags": [ "Fees Configurations" ], "security": [ { "oauth-client-credentials": [ "fees:admin" ] } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Fee configuration - Update - Request", "type": "object", "properties": { "fee_model_id": { "title": "Fee model unique identifier.", "type": "string", "description": "Fee model unique identifier.", "format": "uuid" } }, "required": [ "fee_model_id" ], "additionalProperties": false }, "example": { "fee_model_id": "1df86975-06f4-484d-935e-46b54bab2f6c" } } } }, "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Fee Configuration", "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "fee_model_id": { "title": "Fee model unique identifier.", "type": "string", "description": "Fee model unique identifier.", "format": "uuid" } }, "required": [ "account_id", "fee_model_id", "created_at", "updated_at" ], "additionalProperties": false }, "example": { "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "fee_model_id": "1df86975-06f4-484d-935e-46b54bab2f6c", "account_id": "7524949b-31fd-497e-ad92-f52de45341d1" } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/fees/collections": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_fee_collections", "summary": "Get fee collections", "description": "Returns a list of fee collections.", "tags": [ "Fees" ], "security": [ { "oauth-client-credentials": [ "fees:read", "fees:admin" ] } ], "parameters": [ { "name": "account_id", "in": "query", "required": false, "schema": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "description": "Filters the list to show only fees associated with a specific account ID.", "example": "413715f2-5401-4b97-8055-034a6b879f8c" }, { "name": "account_group_id", "in": "query", "required": false, "schema": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "description": "Filters the list to show only fees associated with a specific account group ID.", "example": "72da9e41-9926-419f-976e-4c8069a04249" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "updated_at" ], "default": "created_at" }, "description": "Field of resource to sort by.", "example": "created_at" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Fee Collection - List - Response", "type": "object", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "items": { "title": "Fee Collection", "type": "object", "properties": { "id": { "title": "Fee collection unique identifier.", "type": "string", "description": "Fee collection unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "type": { "type": "string", "description": "Type of the fee collection\n* SERVICE_FEE - Service fee intake in a pre-defined cadence (e.g. monthly)\n* SERVICE_FEE_LIQUIDATION - Service fee intake as a result of a Portfolio liquidation", "enum": [ "SERVICE_FEE", "SERVICE_FEE_LIQUIDATION" ] }, "collection_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "processed_amount": { "type": "object", "properties": { "cash_balance": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "sell_to_cover": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "total_residual_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" } } }, "sell_to_cover_orders": { "type": "array", "items": { "title": "Sell to cover order details", "type": "object", "properties": { "id": { "title": "Sell to cover order id used to cover fee amount.", "type": "string", "description": "Sell to cover order id used to cover fee amount.", "format": "uuid" }, "residual_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" } }, "required": [ "id", "residual_amount" ], "additionalProperties": false } }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "status": { "type": "string", "description": "Status of the fee collection\n* PROCESSING - Fee collection is in progress.\n* FINALISED - Fees have been collected from the account and the funds has been transferred to the client.\n* CANCELLED - Fee collection has been cancelled.", "enum": [ "PROCESSING", "FINALISED", "CANCELLED" ] }, "period_start": { "type": "string", "format": "date", "description": "Start date of the fee collection period in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339" }, "period_end": { "type": "string", "format": "date", "description": "End date of the fee collection period in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339" }, "calculation_breakdown": { "type": "array", "description": "Breakdown of the fee collection by fee model and subperiod. Populated only for fee collections created from daily fee model calculations.", "items": { "title": "Fee Calculation Breakdown Item", "type": "object", "properties": { "fee_model_id": { "title": "Fee model unique identifier.", "type": "string", "description": "Fee model unique identifier.", "format": "uuid" }, "subperiod_start": { "type": "string", "format": "date", "description": "Start date of the fee subperiod in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339" }, "subperiod_end": { "type": "string", "format": "date", "description": "End date of the fee subperiod in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339" }, "subtotal_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "components": { "type": "array", "description": "Individual fee components contributing to the subtotal.", "items": { "title": "Fee Breakdown Component", "type": "object", "properties": { "type": { "type": "string", "description": "Type of the fee component\n* TRANSACTION_LUMP_SUM - Lump sum transaction fee\n* PLATFORM - Platform fee\n* SERVICE - Service fee (client portfolio)\n* VAT - Value-added tax", "enum": [ "TRANSACTION_LUMP_SUM", "PLATFORM", "SERVICE", "VAT" ] }, "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" } }, "required": [ "type", "amount" ], "additionalProperties": false } } }, "required": [ "fee_model_id", "subperiod_start", "subperiod_end", "subtotal_amount", "components" ], "additionalProperties": false } }, "replaced_collection_id": { "title": "Fee collection unique identifier.", "type": "string", "description": "Fee collection unique identifier.", "format": "uuid" } }, "required": [ "id", "account_id", "account_group_id", "type", "collection_amount", "processed_amount", "currency", "status", "period_start", "period_end", "created_at", "updated_at" ], "additionalProperties": false } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "example": { "meta": { "offset": 0, "limit": 100, "count": 3, "total_count": 3, "sort": "id", "order": "ASC" }, "data": [ { "id": "d77e6924-9bb7-4db0-addc-404442258f4b", "created_at": "2022-11-30T14:16:22Z", "updated_at": "2022-11-30T14:16:22Z", "account_id": "689f7566-2ca3-4007-b99d-e501be8c7783", "account_group_id": "999f7566-2ca3-4007-b99d-e501be8c7222", "type": "SERVICE_FEE", "collection_amount": "12.41", "processed_amount": { "cash_balance": "6.50", "sell_to_cover": "0" }, "currency": "EUR", "status": "PROCESSING", "period_start": "2022-11-01", "period_end": "2022-11-30" }, { "id": "7c5f2b11-7078-4bb9-8ed8-9dcf5eb7597f", "created_at": "2022-11-30T14:16:22Z", "updated_at": "2022-11-30T14:16:22Z", "account_id": "5b8b1e66-cf3c-40f3-94d3-c94f2ac7abb7", "account_group_id": "87805651-ad25-4a85-8c04-88a666164ad4", "type": "SERVICE_FEE", "collection_amount": "82.12", "processed_amount": { "cash_balance": "40.00", "sell_to_cover": "42.12" }, "currency": "EUR", "status": "FINALISED", "period_start": "2022-09-01", "period_end": "2022-12-31" }, { "id": "85fba2a0-da2f-46ac-a2a8-b4e7c66cb375", "created_at": "2022-11-30T14:16:22Z", "updated_at": "2022-11-30T14:16:22Z", "account_id": "c28b6611-7ac1-405a-8eb7-ab3b35caccc2", "account_group_id": "f930f9d4-3e21-4ad5-a266-730821d9a9fc", "type": "SERVICE_FEE_LIQUIDATION", "collection_amount": "65.30", "processed_amount": { "cash_balance": "0.00", "sell_to_cover": "0.00" }, "currency": "EUR", "status": "CANCELLED", "period_start": "2022-03-01", "period_end": "2022-07-30" } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "post": { "operationId": "create_fee_collection", "summary": "Create a fee collection", "description": "Creates a fee collection for pre-calculated fee amounts.", "tags": [ "Fees" ], "security": [ { "oauth-client-credentials": [ "fees:admin" ] } ], "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$", "example": "ccb07f42-4104-44ad-8e1f-c660bb7b269c" }, "description": "A UUID to be used as an idempotency key. This prevents a duplicate request from being replayed.\nhttps://docs.upvest.co/documentation/concepts/api_concepts/idempotency\n" } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Fee Collection - Create - Request", "type": "object", "properties": { "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "type": { "type": "string", "description": "Type of the fee collection\n* SERVICE_FEE - Service fee intake in a pre-defined cadence (e.g. monthly)\n* SERVICE_FEE_LIQUIDATION - Service fee intake as a result of a Portfolio liquidation", "enum": [ "SERVICE_FEE", "SERVICE_FEE_LIQUIDATION" ] }, "collection_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "period_start": { "type": "string", "format": "date", "description": "Start date of the fee collection period in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339" }, "period_end": { "type": "string", "format": "date", "description": "End date of the fee collection period in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339" } }, "required": [ "account_id", "type", "collection_amount", "currency", "period_start", "period_end" ], "additionalProperties": false }, "example": { "account_id": "689f7566-2ca3-4007-b99d-e501be8c7783", "type": "SERVICE_FEE", "collection_amount": "12.41", "currency": "EUR", "period_start": "2022-11-01", "period_end": "2022-11-30" } } } }, "responses": { "200": { "description": "Fee collection created.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Fee Collection", "type": "object", "properties": { "id": { "title": "Fee collection unique identifier.", "type": "string", "description": "Fee collection unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "type": { "type": "string", "description": "Type of the fee collection\n* SERVICE_FEE - Service fee intake in a pre-defined cadence (e.g. monthly)\n* SERVICE_FEE_LIQUIDATION - Service fee intake as a result of a Portfolio liquidation", "enum": [ "SERVICE_FEE", "SERVICE_FEE_LIQUIDATION" ] }, "collection_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "processed_amount": { "type": "object", "properties": { "cash_balance": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "sell_to_cover": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "total_residual_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" } } }, "sell_to_cover_orders": { "type": "array", "items": { "title": "Sell to cover order details", "type": "object", "properties": { "id": { "title": "Sell to cover order id used to cover fee amount.", "type": "string", "description": "Sell to cover order id used to cover fee amount.", "format": "uuid" }, "residual_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" } }, "required": [ "id", "residual_amount" ], "additionalProperties": false } }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "status": { "type": "string", "description": "Status of the fee collection\n* PROCESSING - Fee collection is in progress.\n* FINALISED - Fees have been collected from the account and the funds has been transferred to the client.\n* CANCELLED - Fee collection has been cancelled.", "enum": [ "PROCESSING", "FINALISED", "CANCELLED" ] }, "period_start": { "type": "string", "format": "date", "description": "Start date of the fee collection period in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339" }, "period_end": { "type": "string", "format": "date", "description": "End date of the fee collection period in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339" }, "calculation_breakdown": { "type": "array", "description": "Breakdown of the fee collection by fee model and subperiod. Populated only for fee collections created from daily fee model calculations.", "items": { "title": "Fee Calculation Breakdown Item", "type": "object", "properties": { "fee_model_id": { "title": "Fee model unique identifier.", "type": "string", "description": "Fee model unique identifier.", "format": "uuid" }, "subperiod_start": { "type": "string", "format": "date", "description": "Start date of the fee subperiod in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339" }, "subperiod_end": { "type": "string", "format": "date", "description": "End date of the fee subperiod in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339" }, "subtotal_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "components": { "type": "array", "description": "Individual fee components contributing to the subtotal.", "items": { "title": "Fee Breakdown Component", "type": "object", "properties": { "type": { "type": "string", "description": "Type of the fee component\n* TRANSACTION_LUMP_SUM - Lump sum transaction fee\n* PLATFORM - Platform fee\n* SERVICE - Service fee (client portfolio)\n* VAT - Value-added tax", "enum": [ "TRANSACTION_LUMP_SUM", "PLATFORM", "SERVICE", "VAT" ] }, "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" } }, "required": [ "type", "amount" ], "additionalProperties": false } } }, "required": [ "fee_model_id", "subperiod_start", "subperiod_end", "subtotal_amount", "components" ], "additionalProperties": false } }, "replaced_collection_id": { "title": "Fee collection unique identifier.", "type": "string", "description": "Fee collection unique identifier.", "format": "uuid" } }, "required": [ "id", "account_id", "account_group_id", "type", "collection_amount", "processed_amount", "currency", "status", "period_start", "period_end", "created_at", "updated_at" ], "additionalProperties": false }, "example": { "id": "d77e6924-9bb7-4db0-addc-404442258f4b", "created_at": "2022-11-30T14:16:22Z", "updated_at": "2022-11-30T14:16:22Z", "account_id": "689f7566-2ca3-4007-b99d-e501be8c7783", "account_group_id": "999f7566-2ca3-4007-b99d-e501be8c7222", "type": "SERVICE_FEE", "collection_amount": "12.41", "processed_amount": { "cash_balance": "6.50", "sell_to_cover": "0" }, "currency": "EUR", "status": "PROCESSING", "period_start": "2022-11-01", "period_end": "2022-11-30" } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/fees/collections/{fee_collection_id}": { "parameters": [ { "name": "fee_collection_id", "in": "path", "required": true, "description": "The unique identifier of the fee collection. Universally Unique Identifier (UUID).", "schema": { "title": "Fee collection unique identifier.", "type": "string", "description": "Fee collection unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_fee_collection", "summary": "Get a fee collection by ID", "description": "Returns the fee collection specified by its ID.", "tags": [ "Fees" ], "security": [ { "oauth-client-credentials": [ "fees:read", "fees:admin" ] } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Fee Collection", "type": "object", "properties": { "id": { "title": "Fee collection unique identifier.", "type": "string", "description": "Fee collection unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "type": { "type": "string", "description": "Type of the fee collection\n* SERVICE_FEE - Service fee intake in a pre-defined cadence (e.g. monthly)\n* SERVICE_FEE_LIQUIDATION - Service fee intake as a result of a Portfolio liquidation", "enum": [ "SERVICE_FEE", "SERVICE_FEE_LIQUIDATION" ] }, "collection_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "processed_amount": { "type": "object", "properties": { "cash_balance": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "sell_to_cover": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "total_residual_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" } } }, "sell_to_cover_orders": { "type": "array", "items": { "title": "Sell to cover order details", "type": "object", "properties": { "id": { "title": "Sell to cover order id used to cover fee amount.", "type": "string", "description": "Sell to cover order id used to cover fee amount.", "format": "uuid" }, "residual_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" } }, "required": [ "id", "residual_amount" ], "additionalProperties": false } }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "status": { "type": "string", "description": "Status of the fee collection\n* PROCESSING - Fee collection is in progress.\n* FINALISED - Fees have been collected from the account and the funds has been transferred to the client.\n* CANCELLED - Fee collection has been cancelled.", "enum": [ "PROCESSING", "FINALISED", "CANCELLED" ] }, "period_start": { "type": "string", "format": "date", "description": "Start date of the fee collection period in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339" }, "period_end": { "type": "string", "format": "date", "description": "End date of the fee collection period in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339" }, "calculation_breakdown": { "type": "array", "description": "Breakdown of the fee collection by fee model and subperiod. Populated only for fee collections created from daily fee model calculations.", "items": { "title": "Fee Calculation Breakdown Item", "type": "object", "properties": { "fee_model_id": { "title": "Fee model unique identifier.", "type": "string", "description": "Fee model unique identifier.", "format": "uuid" }, "subperiod_start": { "type": "string", "format": "date", "description": "Start date of the fee subperiod in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339" }, "subperiod_end": { "type": "string", "format": "date", "description": "End date of the fee subperiod in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339" }, "subtotal_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "components": { "type": "array", "description": "Individual fee components contributing to the subtotal.", "items": { "title": "Fee Breakdown Component", "type": "object", "properties": { "type": { "type": "string", "description": "Type of the fee component\n* TRANSACTION_LUMP_SUM - Lump sum transaction fee\n* PLATFORM - Platform fee\n* SERVICE - Service fee (client portfolio)\n* VAT - Value-added tax", "enum": [ "TRANSACTION_LUMP_SUM", "PLATFORM", "SERVICE", "VAT" ] }, "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" } }, "required": [ "type", "amount" ], "additionalProperties": false } } }, "required": [ "fee_model_id", "subperiod_start", "subperiod_end", "subtotal_amount", "components" ], "additionalProperties": false } }, "replaced_collection_id": { "title": "Fee collection unique identifier.", "type": "string", "description": "Fee collection unique identifier.", "format": "uuid" } }, "required": [ "id", "account_id", "account_group_id", "type", "collection_amount", "processed_amount", "currency", "status", "period_start", "period_end", "created_at", "updated_at" ], "additionalProperties": false }, "example": { "id": "d77e6924-9bb7-4db0-addc-404442258f4b", "created_at": "2022-11-30T14:16:22Z", "updated_at": "2022-11-30T14:16:22Z", "account_id": "689f7566-2ca3-4007-b99d-e501be8c7783", "account_group_id": "999f7566-2ca3-4007-b99d-e501be8c7222", "type": "SERVICE_FEE", "collection_amount": "12.41", "processed_amount": { "cash_balance": "6.50", "sell_to_cover": "0" }, "currency": "EUR", "status": "PROCESSING", "period_start": "2022-11-01", "period_end": "2022-11-30", "calculation_breakdown": [ { "fee_model_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "subperiod_start": "2022-11-01", "subperiod_end": "2022-11-30", "subtotal_amount": "12.41", "components": [ { "type": "SERVICE", "amount": "10.00" }, { "type": "PLATFORM", "amount": "2.41" } ] } ] } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/tax_exemptions": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "post": { "operationId": "create_tax_exemption", "summary": "Create a tax exemption", "description": "Creates a tax exemption.", "tags": [ "Tax Exemptions" ], "security": [ { "oauth-client-credentials": [ "taxes:admin" ] } ], "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$", "example": "ccb07f42-4104-44ad-8e1f-c660bb7b269c" }, "description": "A UUID to be used as an idempotency key. This prevents a duplicate request from being replayed.\nhttps://docs.upvest.co/documentation/concepts/api_concepts/idempotency\n" } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Taxes - Tax Exemptions - Create - Request", "type": "object", "additionalProperties": false, "properties": { "user_ids": { "description": "Ids of the users for whom the tax exemption is to be created.", "type": "array", "items": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" } }, "tax_exemption_details": { "title": "Tax Exemption - Request - German Tax Exemption Details", "type": "object", "additionalProperties": false, "properties": { "tax_exemption_type": { "title": "Tax Exemption Type", "type": "string", "description": "Tax exemption type \n* SINGLE - Tax exemption for Individual. \n* MARRIED - Tax exemption for married couples.", "enum": [ "SINGLE", "MARRIED" ] }, "tax_exemption_amount": { "title": "Tax Exemption - Create - Request - Tax Exemption Details - Amount", "type": "object", "additionalProperties": false, "properties": { "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "tax_exemption_amount" ] }, "country": { "description": "Country code. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "pattern": "^[A-Z]{2}$" }, "valid_to_date": { "type": "string", "format": "date", "description": "Date until which the tax exemption is valid. If it is unlimited, it is omitted. For Germany it is always the last day of the year (YYYY-12-31). [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" } }, "required": [ "user_ids", "country", "tax_exemption_details" ] }, "example": { "user_ids": [ "70fd317b-81e1-4f21-9f7e-3b5cb4dfe686" ], "tax_exemption_details": { "tax_exemption_type": "SINGLE", "tax_exemption_amount": { "currency": "EUR", "amount": "1000" } }, "country": "DE", "valid_to_date": "2024-12-31" } } } }, "responses": { "202": { "description": "Creation request accepted.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Tax Exemptions - Create - Response", "type": "object", "additionalProperties": false, "properties": { "id": { "title": "Tax Exemption Unique Identifier", "type": "string", "description": "Tax Exemption Unique Identifier", "format": "uuid" } } }, "example": { "id": "f1a57a04-1a89-4dab-ae3a-ff9b2a9377c1" } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/tax_exemptions/{tax_exemption_id}": { "parameters": [ { "name": "tax_exemption_id", "description": "The unique identifier of the tax exemption. Universally Unique Identifier (UUID).", "in": "path", "required": true, "schema": { "title": "Tax Exemption Unique Identifier", "type": "string", "description": "Tax Exemption Unique Identifier", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_tax_exemption_by_id", "summary": "Get a tax exemption by ID", "description": "Returns the tax exemption specified by its ID", "tags": [ "Tax Exemptions" ], "security": [ { "oauth-client-credentials": [ "taxes:admin" ] } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Webhook - Tax exemption - Created - Tax exemption", "type": "object", "additionalProperties": false, "properties": { "id": { "title": "Tax Exemption Unique Identifier", "type": "string", "description": "Tax Exemption Unique Identifier", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "status": { "title": "Tax exemption status", "type": "string", "description": "Tax exemption status \n* NEW - The tax exemption request is created. \n* ACTIVE - The tax exemption is valid and active for the current year. \n* EXPIRED - The tax exemption is no longer `ACTIVE` and the `valid_to_date` already lies in the past. An update is not possible. \n* CANCELLED - The tax exemption could not be created or was cancelled.", "enum": [ "NEW", "ACTIVE", "EXPIRED", "CANCELLED" ] }, "user_ids": { "description": "Ids of the users for whom the tax exemption was created.", "type": "array", "items": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" } }, "country": { "description": "Country code. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "pattern": "^[A-Z]{2}$" }, "valid_from_date": { "type": "string", "format": "date", "description": "Date from which the tax exemption is valid. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" }, "valid_to_date": { "type": "string", "format": "date", "nullable": true, "description": "Date until which the tax exemption is valid. If it is unlimited, it is omitted. For Germany it is always the last day of the year (YYYY-12-31). [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" }, "tax_exemption_details": { "title": "Tax Exemption - German Tax Exemption Details", "type": "object", "additionalProperties": false, "properties": { "tax_exemption_type": { "title": "Tax Exemption Type", "type": "string", "description": "Tax exemption type \n* SINGLE - Tax exemption for Individual. \n* MARRIED - Tax exemption for married couples.", "enum": [ "SINGLE", "MARRIED" ] }, "tax_exemption_amount": { "title": "Tax Exemption - Create - Request - Tax Exemption Details - Amount", "type": "object", "additionalProperties": false, "properties": { "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] } }, "required": [ "amount", "currency" ] }, "utilized_amount": { "title": "Tax Exemption - Create - Request - Tax Exemption Details - Amount", "type": "object", "additionalProperties": false, "properties": { "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] } }, "required": [ "amount", "currency" ] }, "remaining_amount": { "title": "Tax Exemption - Create - Request - Tax Exemption Details - Amount", "type": "object", "additionalProperties": false, "properties": { "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "tax_exemption_type", "tax_exemption_amount", "utilized_amount", "remaining_amount" ] } }, "required": [ "id", "status", "user_ids", "country", "valid_from_date", "valid_to_date", "tax_exemption_details", "created_at", "updated_at" ] }, "example": { "id": "f1a57a04-1a89-4dab-ae3a-ff9b2a9377c1", "created_at": "2024-01-01T10:33:43Z", "updated_at": "2024-01-01T10:33:43Z", "status": "ACTIVE", "user_ids": [ "70821d79-366f-4873-804b-14857d690496" ], "country": "DE", "valid_from_date": "2024-01-01", "valid_to_date": "2024-12-31", "tax_exemption_details": { "tax_exemption_type": "SINGLE", "tax_exemption_amount": { "amount": "1000.00", "currency": "EUR" }, "utilized_amount": { "amount": "0.00", "currency": "EUR" }, "remaining_amount": { "amount": "1000.00", "currency": "EUR" } } } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "put": { "operationId": "update_tax_exemption", "summary": "Update a tax exemption", "description": "Updates a tax exemption specified by its ID.", "tags": [ "Tax Exemptions" ], "security": [ { "oauth-client-credentials": [ "taxes:admin" ] } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Taxes - Tax Exemptions - Update - Request", "type": "object", "additionalProperties": false, "properties": { "user_ids": { "description": "Ids of the users for whom the tax exemption is to be updated.", "type": "array", "items": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" } }, "tax_exemption_details": { "title": "Tax Exemption - Request - German Tax Exemption Details", "type": "object", "additionalProperties": false, "properties": { "tax_exemption_type": { "title": "Tax Exemption Type", "type": "string", "description": "Tax exemption type \n* SINGLE - Tax exemption for Individual. \n* MARRIED - Tax exemption for married couples.", "enum": [ "SINGLE", "MARRIED" ] }, "tax_exemption_amount": { "title": "Tax Exemption - Create - Request - Tax Exemption Details - Amount", "type": "object", "additionalProperties": false, "properties": { "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "tax_exemption_amount" ] }, "country": { "description": "Country code. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "pattern": "^[A-Z]{2}$" }, "valid_to_date": { "type": "string", "format": "date", "description": "Date until which the tax exemption is valid. If it is unlimited, it is omitted. For Germany it is always the last day of the year (YYYY-12-31). [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" } }, "required": [ "user_ids", "country", "tax_exemption_details" ] }, "example": { "user_ids": [ "70fd317b-81e1-4f21-9f7e-3b5cb4dfe686" ], "tax_exemption_details": { "tax_exemption_type": "SINGLE", "tax_exemption_amount": { "currency": "EUR", "amount": "955" } }, "country": "DE", "valid_to_date": "2024-12-31" } } } }, "responses": { "202": { "description": "The tax exemption update is submitted.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Tax Exemptions - Update - Response", "type": "object", "additionalProperties": false, "properties": { "id": { "title": "Tax Exemption Unique Identifier", "type": "string", "description": "Tax Exemption Unique Identifier", "format": "uuid" } } }, "example": { "id": "f1a57a04-1a89-4dab-ae3a-ff9b2a9377c1" } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "delete": { "operationId": "delete_tax_exemption", "summary": "Delete a tax exemption", "description": "Deletes a tax exemption specified by its ID.", "tags": [ "Tax Exemptions" ], "security": [ { "oauth-client-credentials": [ "taxes:admin" ] } ], "responses": { "202": { "description": "The request has been successfully accepted and will be processed asynchronously.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/users/{user_id}/tax_exemptions": { "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "The unique identifier of the user. Universally Unique Identifier (UUID).", "schema": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_tax_exemptions_for_user", "summary": "List tax exemptions for a user", "description": "Returns the tax exemptions of the user specified by ID.", "tags": [ "Tax Exemptions" ], "security": [ { "oauth-client-credentials": [ "taxes:admin" ] } ], "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at" ], "default": "created_at" }, "description": "Sort the result by `created_at`." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Tax Exemption - Retrieve For User - Response", "type": "object", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "items": { "title": "Webhook - Tax exemption - Created - Tax exemption", "type": "object", "additionalProperties": false, "properties": { "id": { "title": "Tax Exemption Unique Identifier", "type": "string", "description": "Tax Exemption Unique Identifier", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "status": { "title": "Tax exemption status", "type": "string", "description": "Tax exemption status \n* NEW - The tax exemption request is created. \n* ACTIVE - The tax exemption is valid and active for the current year. \n* EXPIRED - The tax exemption is no longer `ACTIVE` and the `valid_to_date` already lies in the past. An update is not possible. \n* CANCELLED - The tax exemption could not be created or was cancelled.", "enum": [ "NEW", "ACTIVE", "EXPIRED", "CANCELLED" ] }, "user_ids": { "description": "Ids of the users for whom the tax exemption was created.", "type": "array", "items": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" } }, "country": { "description": "Country code. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "pattern": "^[A-Z]{2}$" }, "valid_from_date": { "type": "string", "format": "date", "description": "Date from which the tax exemption is valid. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" }, "valid_to_date": { "type": "string", "format": "date", "nullable": true, "description": "Date until which the tax exemption is valid. If it is unlimited, it is omitted. For Germany it is always the last day of the year (YYYY-12-31). [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" }, "tax_exemption_details": { "title": "Tax Exemption - German Tax Exemption Details", "type": "object", "additionalProperties": false, "properties": { "tax_exemption_type": { "title": "Tax Exemption Type", "type": "string", "description": "Tax exemption type \n* SINGLE - Tax exemption for Individual. \n* MARRIED - Tax exemption for married couples.", "enum": [ "SINGLE", "MARRIED" ] }, "tax_exemption_amount": { "title": "Tax Exemption - Create - Request - Tax Exemption Details - Amount", "type": "object", "additionalProperties": false, "properties": { "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] } }, "required": [ "amount", "currency" ] }, "utilized_amount": { "title": "Tax Exemption - Create - Request - Tax Exemption Details - Amount", "type": "object", "additionalProperties": false, "properties": { "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] } }, "required": [ "amount", "currency" ] }, "remaining_amount": { "title": "Tax Exemption - Create - Request - Tax Exemption Details - Amount", "type": "object", "additionalProperties": false, "properties": { "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "tax_exemption_type", "tax_exemption_amount", "utilized_amount", "remaining_amount" ] } }, "required": [ "id", "status", "user_ids", "country", "valid_from_date", "valid_to_date", "tax_exemption_details", "created_at", "updated_at" ] } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "example": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1, "sort": "created_at", "order": "ASC" }, "data": [ { "id": "f1a57a04-1a89-4dab-ae3a-ff9b2a9377c1", "created_at": "2024-01-01T10:33:43Z", "updated_at": "2024-01-01T10:33:43Z", "status": "ACTIVE", "user_ids": [ "70821d79-366f-4873-804b-14857d690496" ], "country": "DE", "valid_from_date": "2024-01-01", "valid_to_date": "2024-12-31", "tax_exemption_details": { "tax_exemption_type": "SINGLE", "tax_exemption_amount": { "amount": "1000.00", "currency": "EUR" }, "utilized_amount": { "amount": "0.00", "currency": "EUR" }, "remaining_amount": { "amount": "1000.00", "currency": "EUR" } } } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "405": { "description": "Method Not Allowed. The requested method is not allowed on the requested resource.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 405, "type": "method_not_allowed" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/isa/wrappers": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "post": { "operationId": "create_isa_tax_wrapper", "summary": "Create a tax wrapper for ISA account", "description": "Creates a tax wrapper for ISA account.", "tags": [ "Tax Wrappers" ], "security": [ { "oauth-client-credentials": [ "taxes:admin" ] } ], "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$", "example": "ccb07f42-4104-44ad-8e1f-c660bb7b269c" }, "description": "A UUID to be used as an idempotency key. This prevents a duplicate request from being replayed.\nhttps://docs.upvest.co/documentation/concepts/api_concepts/idempotency\n" } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Tax Wrappers - Create ISA Tax Wrapper - Request", "type": "object", "additionalProperties": false, "properties": { "account_group_id": { "type": "string", "format": "uuid", "description": "The ID of the account group to which the tax wrapper belongs." }, "type": { "type": "string", "description": "Types of the ISA tax wrapper", "enum": [ "STOCKS_AND_SHARES_ISA" ], "default": "STOCKS_AND_SHARES_ISA" }, "is_flexible": { "type": "boolean", "description": "True if ISA is flexible." } }, "required": [ "type", "account_group_id", "is_flexible" ] }, "example": { "account_group_id": "0d68fea2-66e8-4ea8-b507-276e7a1eb4aa", "type": "STOCKS_AND_SHARES_ISA", "is_flexible": true } } } }, "responses": { "200": { "description": "ISA tax wrapper created.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Tax Wrappers - ISA Tax Wrapper", "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Tax wrapper unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "description": "The date and time the tax wrapper was created.", "format": "date-time" }, "updated_at": { "type": "string", "description": "The date and time the tax wrapper was last updated.", "format": "date-time" }, "account_group_id": { "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "is_flexible": { "type": "boolean", "description": "True if tax wrapper is flexible." }, "status": { "type": "string", "description": "Status of the tax wrapper\n* NEW - The tax wrapper is newly created and not yet active due to pending checks.\n* ACTIVE - The tax wrapper is currently active and in use.\n* INACTIVE - The tax wrapper is not currently active. New subscriptions not allowed.\n* CLOSED - The tax wrapper has been closed and is no longer available.", "enum": [ "NEW", "ACTIVE", "INACTIVE", "CLOSED" ] }, "type": { "type": "string", "description": "Types of the ISA tax wrapper", "enum": [ "STOCKS_AND_SHARES_ISA" ], "default": "STOCKS_AND_SHARES_ISA" } }, "required": [ "id", "created_at", "updated_at", "account_group_id", "is_flexible", "status", "type" ] }, "example": { "id": "f1a57a04-1a89-4dab-ae3a-ff9b2a9377c1", "created_at": "2025-10-05T14:48:00.000Z", "updated_at": "2025-10-05T14:48:00.000Z", "account_group_id": "0d68fea2-66e8-4ea8-b507-276e7a1eb4aa", "is_flexible": true, "status": "NEW", "type": "STOCKS_AND_SHARES_ISA" } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/isa/wrappers/{tax_wrapper_id}/allowances": { "parameters": [ { "name": "tax_wrapper_id", "description": "The unique identifier of the tax wrapper. Universally Unique Identifier (UUID).", "in": "path", "required": true, "schema": { "title": "Tax Wrapper Unique Identifier", "type": "string", "description": "Tax wrapper unique identifier", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_isa_allowances", "summary": "Retrieve ISA allowances", "description": "Retrieves ISA allowances", "tags": [ "Tax Wrappers" ], "security": [ { "oauth-client-credentials": [ "taxes:admin" ] } ], "parameters": [ { "name": "tax_year", "in": "query", "required": false, "description": "Filter allowances by tax_year YYYY/YYYY", "schema": { "type": "string", "pattern": "^[0-9]{4}\\/[0-9]{4}$" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort the result by `created_at` or `valid_from`", "schema": { "type": "string", "enum": [ "created_at", "valid_from" ], "default": "created_at" } }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Tax Wrappers - Retrieve ISA Allowances - Response", "type": "object", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "items": { "title": "Tax Wrappers - ISA Allowance", "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Allowance unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "description": "The date and time the tax wrapper was created.", "format": "date-time" }, "updated_at": { "type": "string", "description": "The date and time the tax wrapper was last updated.", "format": "date-time" }, "tax_wrapper_id": { "type": "string", "description": "Tax wrapper unique identifier.", "format": "uuid" }, "tax_year": { "oneOf": [ { "type": "null" }, { "type": "string", "description": "Tax year the allowance applies to, in the format 'YYYY/YYYY'.", "pattern": "^[0-9]{4}/[0-9]{4}$" } ] }, "type": { "type": "string", "description": "Type of the allowance:\n* ANNUAL - Allowance valid for a tax year.", "enum": [ "ANNUAL" ], "default": "ANNUAL" }, "status": { "type": "string", "description": "Status of the allowance:\n* ACTIVE - Current allowance.\n* EXPIRED - Allowance from previous years.", "enum": [ "ACTIVE", "EXPIRED" ] }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* GBP - British Pound Sterling", "enum": [ "GBP" ], "default": "GBP" }, "used_amount": { "type": "string", "pattern": "^-?[0-9]{1,9}(\\.[0-9]{2})?$" }, "remaining_amount": { "type": "string", "pattern": "^-?[0-9]{1,9}(\\.[0-9]{2})?$" }, "valid_from": { "type": "string", "description": "The date from which the allowance is valid.", "format": "date-time" }, "valid_to": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "date-time", "description": "The date until which the allowance is valid." } ] }, "first_subscription_at": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "date-time", "description": "The date of the first subscription that used this allowance." } ] } }, "required": [ "id", "created_at", "updated_at", "tax_wrapper_id", "type", "status", "currency", "used_amount", "remaining_amount", "valid_from" ] } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "example": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1, "sort": "valid_from", "order": "DESC" }, "data": [ { "id": "f1a57a04-1a89-4dab-ae3a-ff9b2a9377c1", "created_at": "2025-10-05T14:48:00.000Z", "updated_at": "2025-10-05T14:48:00.000Z", "tax_wrapper_id": "0d68fea2-66e8-4ea8-b507-276e7a1eb4aa", "tax_year": "2025/2026", "type": "ANNUAL", "status": "ACTIVE", "currency": "GBP", "used_amount": "0.00", "remaining_amount": "20000.00", "valid_from": "2025-04-06T00:00:00.000Z", "valid_to": "2026-04-05T23:59:59.000Z", "first_subscription_at": "2025-04-06T00:00:00.000Z" } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "405": { "description": "Method Not Allowed. The requested method is not allowed on the requested resource.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 405, "type": "method_not_allowed" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/instruments": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_instruments", "summary": "List instruments", "description": "List instruments", "tags": [ "Instruments" ], "security": [ { "oauth-client-credentials": [ "instruments:read" ] } ], "parameters": [ { "name": "trading_status", "in": "query", "required": false, "schema": { "title": "Instrument trading status", "description": "Instrument trading status\n* ACTIVE - The instrument can currently be traded on the Upvest platform. \n* INACTIVE - The instrument cannot currently be traded on the Upvest platform.", "type": "string", "enum": [ "ACTIVE", "INACTIVE" ] }, "description": "Filters the list to only show instruments with a certain status (e.g. only instruments that can be currently traded).", "example": "ACTIVE" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "updated_at" ], "default": "created_at" }, "description": "Sort the result by `created_at` or `updated_at`." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Instruments - List - Response", "type": "object", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "title": "Instrument unique identifier.", "type": "string", "description": "Instrument unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "isin": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, "wkn": { "title": "German securities identification code", "type": "string", "description": "German securities identification code known as [Wertpapierkennnummer](https://en.wikipedia.org/wiki/Wertpapierkennnummer).", "pattern": "^[A-HJ-NP-Z0-9]{6}$" }, "name": { "description": "Instrument name", "type": "string", "maxLength": 100 }, "fractional_trading": { "type": "boolean", "description": "Determines whether the platform can handle fractional investments within this instrument." }, "trading_status": { "title": "Instrument trading status", "description": "Instrument trading status\n* ACTIVE - The instrument can currently be traded on the Upvest platform. \n* INACTIVE - The instrument cannot currently be traded on the Upvest platform.", "type": "string", "enum": [ "ACTIVE", "INACTIVE" ] }, "details": { "title": "Details", "type": "object", "description": "Details", "properties": { "distribution_countries": { "title": "Distribution Countries", "description": "Distribution Countries", "type": "array", "items": { "description": "Country code. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "pattern": "^[A-Z]{2}$" } } } } }, "required": [ "id", "name", "fractional_trading", "trading_status", "created_at", "updated_at" ], "additionalProperties": false } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "example": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 10, "sort": "created_at", "order": "ASC" }, "data": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "created_at": "2022-08-31T17:28:00.00Z", "updated_at": "2022-08-31T17:28:00.00Z", "isin": "DE0007664005", "wkn": "766400", "name": "Volkswagen (VW) St. Aktie.", "fractional_trading": true, "trading_status": "ACTIVE" } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/instruments/{instrument_id}": { "parameters": [ { "name": "instrument_id", "in": "path", "required": true, "description": "The unique identifier of the instrument, provided as either an `isin:` URN or a `uuid:` URN.", "schema": { "title": "Instrument unique identifier", "description": "Instrument unique identifier.", "oneOf": [ { "title": "International securities identification number with 'isin:' URN namespace", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number), prefixed with a 'isin:' [URN scheme](https://datatracker.ietf.org/doc/html/rfc8141).", "pattern": "^(urn:)?isin:[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, { "title": "Universally Unique IDentifier (UUID) with 'uuid:' URN scheme", "type": "string", "description": "Universally Unique IDentifier (UUID) with 'uuid:' URN namespace, defined by [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122).", "pattern": "^(urn:)?uuid:[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$" } ] } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_instrument", "summary": "Get instrument", "description": "Returns the instrument.", "tags": [ "Instruments" ], "security": [ { "oauth-client-credentials": [ "instruments:read" ] } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "title": "Instrument unique identifier.", "type": "string", "description": "Instrument unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "isin": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, "wkn": { "title": "German securities identification code", "type": "string", "description": "German securities identification code known as [Wertpapierkennnummer](https://en.wikipedia.org/wiki/Wertpapierkennnummer).", "pattern": "^[A-HJ-NP-Z0-9]{6}$" }, "name": { "description": "Instrument name", "type": "string", "maxLength": 100 }, "fractional_trading": { "type": "boolean", "description": "Determines whether the platform can handle fractional investments within this instrument." }, "trading_status": { "title": "Instrument trading status", "description": "Instrument trading status\n* ACTIVE - The instrument can currently be traded on the Upvest platform. \n* INACTIVE - The instrument cannot currently be traded on the Upvest platform.", "type": "string", "enum": [ "ACTIVE", "INACTIVE" ] }, "details": { "title": "Details", "type": "object", "description": "Details", "properties": { "distribution_countries": { "title": "Distribution Countries", "description": "Distribution Countries", "type": "array", "items": { "description": "Country code. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "pattern": "^[A-Z]{2}$" } } } } }, "required": [ "id", "name", "fractional_trading", "trading_status", "created_at", "updated_at" ], "additionalProperties": false }, "example": { "id": "123e4567-e89b-12d3-a456-426614174000", "created_at": "2022-08-31T17:28:00.00Z", "updated_at": "2022-08-31T17:28:00.00Z", "isin": "DE0007664005", "wkn": "766400", "name": "Volkswagen (VW) St. Aktie.", "fractional_trading": true, "trading_status": "ACTIVE" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/instruments/{instrument_id}/venues": { "parameters": [ { "name": "instrument_id", "in": "path", "required": true, "description": "The unique identifier of the instrument, provided as either an `isin:` URN or a `uuid:` URN.", "schema": { "title": "Instrument unique identifier", "description": "Instrument unique identifier.", "oneOf": [ { "title": "International securities identification number with 'isin:' URN namespace", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number), prefixed with a 'isin:' [URN scheme](https://datatracker.ietf.org/doc/html/rfc8141).", "pattern": "^(urn:)?isin:[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, { "title": "Universally Unique IDentifier (UUID) with 'uuid:' URN scheme", "type": "string", "description": "Universally Unique IDentifier (UUID) with 'uuid:' URN namespace, defined by [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122).", "pattern": "^(urn:)?uuid:[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$" } ] } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_instrument_venues", "summary": "Get instrument venues", "description": "The venues where the instrument is traded and for which the price data is available.", "tags": [ "Price Data" ], "security": [ { "oauth-client-credentials": [ "prices:read" ] } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Venue", "title": "Venue", "properties": { "name": { "description": "The name of venue.", "title": "The name of venue.", "type": "string" }, "id": { "title": "Venue unique identifier.", "type": "string", "description": "Venue unique identifier.", "format": "uuid" }, "price_qualities": { "type": "array", "description": "The available price qualities.", "items": { "type": "string", "enum": [ "EOD", "REALTIME", "DELAYED" ] } } }, "required": [ "id" ] } } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": [ { "id": "20d6024b-2df4-41ae-8d42-62e4744e455b", "name": "Tradegate", "price_qualities": [ "EOD", "REALTIME" ] } ] } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/instruments/{instrument_id}/venues/{venue_id}/prices/latest": { "parameters": [ { "name": "instrument_id", "in": "path", "required": true, "description": "The unique identifier of the instrument, provided as either an `isin:` URN or a `uuid:` URN.", "schema": { "title": "Instrument unique identifier", "description": "Instrument unique identifier.", "oneOf": [ { "title": "International securities identification number with 'isin:' URN namespace", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number), prefixed with a 'isin:' [URN scheme](https://datatracker.ietf.org/doc/html/rfc8141).", "pattern": "^(urn:)?isin:[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, { "title": "Universally Unique IDentifier (UUID) with 'uuid:' URN scheme", "type": "string", "description": "Universally Unique IDentifier (UUID) with 'uuid:' URN namespace, defined by [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122).", "pattern": "^(urn:)?uuid:[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$" } ] } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" }, { "name": "venue_id", "in": "path", "required": true, "description": "The unique identifier of the trading venue. Universally Unique Identifier (UUID).", "schema": { "title": "Venue unique identifier.", "type": "string", "description": "Venue unique identifier.", "format": "uuid" } } ], "get": { "operationId": "retrieve_instrument_latest_price", "summary": "Get instrument latest price", "description": "Returns the instrument's latest price as available at the specified venue.\n\n**NOTE**: Please note that in live mode we provide the latest prices that we receive from our data provider. However, it is to be expected that such updates will only take place on trading days.", "tags": [ "Price Data" ], "parameters": [ { "name": "price_quality", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "HIGHEST_AVAILABLE" ], "default": "HIGHEST_AVAILABLE", "example": "HIGHEST_AVAILABLE" } } ], "security": [ { "oauth-client-credentials": [ "prices:read" ] } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "price_quality": { "description": "The retrieved price quality.\n* REALTIME - \n* DELAYED - ", "enum": [ "REALTIME", "DELAYED" ] }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "bids": { "description": "Bids for the instrument.", "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string", "format": "date-time", "description": "The date and time of data capture. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)." }, "price": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "size": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" } } } }, "asks": { "description": "Asks for the instrument.", "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string", "format": "date-time", "description": "The date and time of data capture. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)." }, "price": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "size": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" } } } }, "last_trade": { "type": "object", "properties": { "time": { "type": "string", "format": "date-time", "description": "The date and time of data capture. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)." }, "price": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "size": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" } } } }, "required": [ "price_quality", "currency" ], "additionalProperties": false }, "example": { "price_quality": "REALTIME", "currency": "EUR", "bids": [ { "time": "2023-01-09T13:02:15Z", "price": "210.01", "size": "100" } ], "asks": [ { "time": "2023-01-09T13:02:15Z", "price": "212.32", "size": "50" } ], "last_trade": { "time": "2023-01-09T12:59:04Z", "price": "211.32", "size": "40" } } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/instruments/{instrument_id}/venues/{venue_id}/prices/ohlc": { "parameters": [ { "name": "instrument_id", "in": "path", "required": true, "description": "The unique identifier of the instrument, provided as either an `isin:` URN or a `uuid:` URN.", "schema": { "title": "Instrument unique identifier", "description": "Instrument unique identifier.", "oneOf": [ { "title": "International securities identification number with 'isin:' URN namespace", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number), prefixed with a 'isin:' [URN scheme](https://datatracker.ietf.org/doc/html/rfc8141).", "pattern": "^(urn:)?isin:[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, { "title": "Universally Unique IDentifier (UUID) with 'uuid:' URN scheme", "type": "string", "description": "Universally Unique IDentifier (UUID) with 'uuid:' URN namespace, defined by [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122).", "pattern": "^(urn:)?uuid:[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$" } ] } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" }, { "name": "venue_id", "in": "path", "required": true, "description": "The unique identifier of the trading venue. Universally Unique Identifier (UUID).", "schema": { "title": "Venue unique identifier.", "type": "string", "description": "Venue unique identifier.", "format": "uuid" } } ], "get": { "operationId": "retrieve_instrument_prices_ohlc", "summary": "Get instrument OHLC prices", "description": "Returns OHLC prices for the instrument at the specified venue for the chosen time period.\n\nIf requested interval is `1d`, then the response also includes days with 0 volume. In these cases `open`, `high`, `low` are empty (`\"\"`), but `close` is provided. If requested interval is smaller than `1d`, then the intervals with 0 volume are omitted from the response.\n\n**NOTE**: Please note that in live mode we provide the latest prices that we receive from our data provider. However, it is to be expected that such updates will only take place on trading days.", "tags": [ "Price Data" ], "parameters": [ { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "title": "Date and time formatted as YYYY-MM-DD[THH:mm:ssZ]. The time part is optional. RFC 3339, section 5.6." }, "description": "Returns OHLC prices from and including this datetime (UTC). If not specified, OHLC prices are returned from 30 days before the specified `end_date`. Time part of the timestamp is optional.", "example": "2023-11-01T10:30:00Z" }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "title": "Date and time formatted as YYYY-MM-DD[THH:mm:ssZ]. The time part is optional. RFC 3339, section 5.6." }, "description": "Returns OHLC prices from and including this datetime (UTC). If not specified, OHLC prices are returned up to yesterday. Time part of the timestamp is optional.", "example": "2023-11-15T13:30:00Z" }, { "name": "adjusted_for", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "NONE", "ALL" ], "default": "ALL" }, "description": "Indication of the desired data adjustment. Prices are adjusted for corporate actions such as cash dividends and stock splits. Does not apply if intraday prices are being requested.", "example": "NONE" }, { "name": "interval", "in": "query", "required": false, "schema": { "type": "string", "default": "1d", "title": "Format is 1d for daily prices or any positive integer followed by h or m for hour or minute, respectively.", "pattern": "^1d|[1-9][0-9]*[hm]$" }, "description": "Indicates the maximum length of the interval each OHLC price tuple covers. If a price did not change subsequent price tuples are omitted. Allowed values are `1d` for daily prices or any positive integer followed by `h` or `m` for hour or minute, respectively. Requests are limited to a maximum of 1000 data points.", "example": "4h" } ], "security": [ { "oauth-client-credentials": [ "prices:read" ] } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "time": { "type": "string", "format": "date-time", "description": "The date and time indicating start of the interval. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "open": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "close": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "high": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "low": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "volume": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" } } } }, "meta": { "type": "object", "properties": { "count": { "type": "integer", "description": "Count of the resources returned in the response." } } } }, "required": [ "data", "meta" ], "additionalProperties": false }, "example": { "data": [ { "currency": "EUR", "time": "2023-01-09", "open": "213.32", "high": "215.32", "low": "210.32", "close": "213.22", "volume": "277973" }, { "currency": "EUR", "time": "2023-01-10", "open": "214.42", "high": "214.42", "low": "213.22", "close": "213.22", "volume": "260335" } ], "meta": { "count": 2 } } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/orders": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "post": { "operationId": "place_order", "summary": "Place an order", "description": "Places a new order for an instrument. After the request is accepted, the order is processed asynchronously — use the returned `id` to poll for status or subscribe to order webhook events.\n\nSee the Orders guide ([TOL](https://docs.upvest.co/products/tol/guides/orders) / [BYOL](https://docs.upvest.co/products/byol/guides/orders) / [Omnibus](https://docs.upvest.co/products/omnibus/guides/orders)) for order lifecycle details.", "tags": [ "Orders" ], "security": [ { "oauth-client-credentials": [ "orders:admin" ] } ], "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$", "example": "ccb07f42-4104-44ad-8e1f-c660bb7b269c" }, "description": "A UUID to be used as an idempotency key. This prevents a duplicate request from being replayed.\nhttps://docs.upvest.co/documentation/concepts/api_concepts/idempotency\n" } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Order - Place - Request", "type": "object", "description": "Request body for placing a new order. Either `cash_amount` or `quantity` must be provided, not both. `account_id`, `side`, `instrument_id`, and `instrument_id_type` are always required.", "properties": { "user_id": { "type": "string", "format": "uuid", "description": "The ID of the user. Either user ID or business ID must be specified." }, "business_id": { "type": "string", "format": "uuid", "description": "The ID of the business. Either user ID or business ID must be specified." }, "account_id": { "type": "string", "format": "uuid", "description": "The ID of the account that owns the order" }, "cash_amount": { "allOf": [ { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, { "description": "Cash amount for a nominal order, not required if a share quantity is specified." } ] }, "currency": { "allOf": [ { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound\n* USD - US Dollar", "enum": [ "EUR", "GBP", "USD" ] }, { "description": "The currency for the order." } ] }, "side": { "type": "string", "description": "Side of the order.\n* BUY — purchases the specified instrument.\n* SELL — disposes of the specified instrument.", "enum": [ "BUY", "SELL" ] }, "instrument_id": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, "instrument_id_type": { "description": "The type of the ID used in the request.\n* ISIN - ", "enum": [ "ISIN" ], "default": "ISIN", "type": "string" }, "order_type": { "type": "string", "description": "Type of the order.\n* MARKET — executes immediately at the best available market price.\n* LIMIT — executes only at or better than the specified `limit_price`.\n* STOP — triggers when the market price reaches `stop_price`, then executes at the prevailing market price.", "enum": [ "MARKET", "LIMIT", "STOP" ] }, "quantity": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "Quantity of securities for the order. Only required if the cash amount is not specified." } ] }, "user_instrument_fit_acknowledgement": { "type": "boolean", "description": "Only applicable if the user has failed the instrument fit check for the instrument type being ordered. True if the user has acknowledged their willingness to trade." }, "limit_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The limit price for orders of the type 'limit'." } ] }, "stop_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The stop price for orders of the type 'stop'." } ] }, "expiry_date": { "allOf": [ { "title": "Expiry date", "type": "string", "description": "Order expiration date in YYYY-MM-DD format. Only applicable to `LIMIT` and `STOP` orders — the order will not execute after this date. Defaults to order creation date plus 359 days.", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, { "description": "The order expiration date (last day the order can trade) in the YYYY-MM-DD format. The expiry date can only be set for LIMIT and STOP orders. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339. The default value is order creation date + 359 days" } ] }, "client_reference": { "type": "string", "description": "Immutable reference to the API flow that initiated the order. For client initiated API flows, this is a client provided ID. For internal initiations, it is set to the ID of the related object.", "maxLength": 100 }, "execution_flow": { "type": "string", "description": "Execution flow for order processing. Defaults to `STRAIGHT_THROUGH` if not specified.\n* STRAIGHT_THROUGH — the order is routed and executed directly without manual intervention.\n* BLOCK — the order is bundled with other orders for block execution.", "enum": [ "STRAIGHT_THROUGH", "BLOCK" ] }, "fee_configuration": { "type": "array", "description": "fee configuration", "items": { "title": "Fee", "description": "A fee applied to an order. Either a fixed absolute cash fee (`absolute_fee_configuration_item`) or a reference to a predefined transaction fee model.", "oneOf": [ { "title": "Absolute Fee", "type": "object", "description": "A fixed cash fee applied to an order, specified as an absolute amount in a given currency.", "properties": { "type": { "title": "Fee type", "description": "Fee type\n* TRANSACTION_FEE_BUY - \n* TRANSACTION_FEE_SELL - ", "type": "string", "enum": [ "TRANSACTION_FEE_BUY", "TRANSACTION_FEE_SELL" ] }, "value_type": { "type": "string", "default": "ABSOLUTE", "description": "The value type must be “ABSOLUTE”." }, "charge_method": { "title": "Fee charge method", "type": "string", "description": "Indicates whether the fee will be charged by client or by other methods.\n* CHARGED_BY_CLIENT - \n* COLLECTED_BY_UPVEST - ", "enum": [ "CHARGED_BY_CLIENT", "COLLECTED_BY_UPVEST" ] }, "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound\n* USD - US Dollar", "enum": [ "EUR", "GBP", "USD" ] } }, "required": [ "type", "value_type", "charge_method", "cash_amount", "currency" ], "additionalProperties": false }, { "title": "Transaction Fee Model", "type": "object", "description": "A fee configuration that references a predefined transaction fee model by its ID, rather than specifying a fee amount directly.", "properties": { "type": { "title": "Fee type", "description": "Fee type\n* TRANSACTION_FEE_BUY - \n* TRANSACTION_FEE_SELL - ", "type": "string", "enum": [ "TRANSACTION_FEE_BUY", "TRANSACTION_FEE_SELL" ] }, "transaction_fee_model_id": { "type": "string", "format": "uuid", "description": "The ID of the transaction fee model." } }, "required": [ "type", "transaction_fee_model_id" ], "additionalProperties": false } ] } }, "decision_maker_id": { "type": "string", "description": "ID of the user behind the decision to place an order. Required only if different from the user_id. (e.g. child account order placed by a guardian)" } }, "required": [ "account_id", "side", "instrument_id", "instrument_id_type" ], "additionalProperties": false }, "examples": { "place_nominal_buy": { "summary": "Nominal Buy Order Request", "value": { "user_id": "2dedfeb0-58cd-44f2-ae08-0e41fe0413d9", "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3", "cash_amount": "1000", "currency": "EUR", "side": "BUY", "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "order_type": "MARKET", "user_instrument_fit_acknowledgement": true, "limit_price": "", "stop_price": "" } }, "place_nominal_buy_with_fee_configuration": { "summary": "Nominal Buy Order Request with fee configuration", "value": { "user_id": "2dedfeb0-58cd-44f2-ae08-0e41fe0413d9", "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3", "cash_amount": "1000", "currency": "EUR", "side": "BUY", "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "order_type": "MARKET", "user_instrument_fit_acknowledgement": true, "limit_price": "", "stop_price": "", "fee_configuration": [ { "cash_amount": "0.90", "currency": "EUR", "type": "TRANSACTION_FEE_BUY", "charge_method": "CHARGED_BY_CLIENT", "value_type": "ABSOLUTE" } ] } }, "place_nominal_buy_with_fee_model": { "summary": "Nominal Buy Order Request with fee model", "value": { "user_id": "2dedfeb0-58cd-44f2-ae08-0e41fe0413d9", "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3", "cash_amount": "1000", "currency": "EUR", "side": "BUY", "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "order_type": "MARKET", "user_instrument_fit_acknowledgement": true, "limit_price": "", "stop_price": "", "fee_configuration": [ { "type": "TRANSACTION_FEE_BUY", "transaction_fee_model_id": "eb5ba93f-5dfe-4bf1-84da-0caacc80c000" } ] } }, "place_unit_sell": { "summary": "Unit Sell Order Request", "value": { "user_id": "2dedfeb0-58cd-44f2-ae08-0e41fe0413d9", "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3", "currency": "EUR", "side": "SELL", "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "order_type": "MARKET", "quantity": "10", "user_instrument_fit_acknowledgement": true, "limit_price": "", "stop_price": "" } }, "place_unit_sell_with_fee_configuration": { "summary": "Unit Sell Order Request with fee configuration", "value": { "user_id": "2dedfeb0-58cd-44f2-ae08-0e41fe0413d9", "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3", "currency": "EUR", "side": "SELL", "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "order_type": "MARKET", "quantity": "10", "user_instrument_fit_acknowledgement": true, "limit_price": "", "stop_price": "", "fee_configuration": [ { "cash_amount": "0.90", "currency": "EUR", "type": "TRANSACTION_FEE_SELL", "charge_method": "CHARGED_BY_CLIENT", "value_type": "ABSOLUTE" } ] } }, "place_unit_sell_with_fee_model": { "summary": "Unit Sell Order Request with fee configuration", "value": { "user_id": "2dedfeb0-58cd-44f2-ae08-0e41fe0413d9", "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3", "currency": "EUR", "side": "SELL", "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "order_type": "MARKET", "quantity": "10", "user_instrument_fit_acknowledgement": true, "limit_price": "", "stop_price": "", "fee_configuration": [ { "type": "TRANSACTION_FEE_SELL", "transaction_fee_model_id": "eb5ba93f-5dfe-4bf1-84da-0caacc80c000" } ] } } } } } }, "responses": { "202": { "description": "The request for the order creation has been accepted for processing.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Order", "type": "object", "description": "Represents an investment order placed by an end user or on their behalf. An order transitions through states (`NEW` → `PROCESSING` → `FILLED` or `CANCELLED`) as it is routed and executed.", "properties": { "id": { "title": "Order unique identifier", "type": "string", "description": "Unique identifier for an order. Universally Unique Identifier (UUID).", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "type": "string", "format": "uuid", "description": "The ID of the user. Either user ID or business ID must be specified." }, "business_id": { "type": "string", "format": "uuid", "description": "The ID of the business. Either user ID or business ID must be specified." }, "account_id": { "type": "string", "format": "uuid", "description": "The ID of the account that owns the order" }, "cash_amount": { "allOf": [ { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, { "description": "Cash amount for a nominal order, not required if a share quantity is specified." } ] }, "currency": { "allOf": [ { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound\n* USD - US Dollar", "enum": [ "EUR", "GBP", "USD" ] }, { "description": "The currency for the order." } ] }, "side": { "type": "string", "description": "Side of the order.\n* BUY — purchases the specified instrument.\n* SELL — disposes of the specified instrument.", "enum": [ "BUY", "SELL" ] }, "instrument_id": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, "instrument_id_type": { "description": "The type of the ID used in the request.\n* ISIN - ", "enum": [ "ISIN" ], "default": "ISIN", "type": "string" }, "order_type": { "type": "string", "description": "Type of the order.\n* MARKET — executes immediately at the best available market price.\n* LIMIT — executes only at or better than the specified `limit_price`.\n* STOP — triggers when the market price reaches `stop_price`, then executes at the prevailing market price.", "enum": [ "MARKET", "LIMIT", "STOP" ] }, "quantity": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "Quantity of securities for the order. Only required if the cash amount is not specified." } ] }, "user_instrument_fit_acknowledgement": { "type": "boolean", "description": "Only applicable if the user has failed the instrument fit check for the instrument type being ordered. True if the user has acknowledged their willingness to trade." }, "limit_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The limit price for orders of the type 'limit'." } ] }, "stop_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The stop price for orders of the type 'stop'." } ] }, "expiry_date": { "allOf": [ { "title": "Expiry date", "type": "string", "description": "Order expiration date in YYYY-MM-DD format. Only applicable to `LIMIT` and `STOP` orders — the order will not execute after this date. Defaults to order creation date plus 359 days.", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, { "description": "The order expiration date (last day the order can trade) in the YYYY-MM-DD format. The expiry date can only be set for LIMIT and STOP orders. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339. The default value is order creation date + 359 days" } ] }, "status": { "type": "string", "description": "The execution status of the order.\n* NEW — the order has been received and validated, awaiting routing.\n* PROCESSING — the order is being routed for execution.\n* FILLED — the order has been fully executed.\n* CANCELLED — the order was cancelled before being fully executed.", "enum": [ "NEW", "PROCESSING", "FILLED", "CANCELLED" ] }, "fee": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "cancellation_reason": { "type": "string", "description": "Reason for order cancellation. Present only when `status` is `CANCELLED`.\n* CANCELLED_BY_CLIENT — cancelled at the end user's or client's request via the API.\n* CANCELLED_BY_UPVEST_OPERATIONS — cancelled by Upvest operations.\n* CANCELLED_BY_TRADING_PARTNER — cancelled by the executing partner.\n* CANCELLED_BY_UPVEST_PLATFORM — cancelled automatically by the Upvest platform.", "enum": [ "CANCELLED_BY_CLIENT", "CANCELLED_BY_UPVEST_OPERATIONS", "CANCELLED_BY_TRADING_PARTNER", "CANCELLED_BY_UPVEST_PLATFORM" ] }, "initiation_flow": { "type": "string", "description": "Identifies what triggered the order.\n* API — initiated directly via the client API.\n* PORTFOLIO — initiated by a portfolio rebalancing flow.\n* CASH_DIVIDEND_REINVESTMENT — initiated as part of dividend reinvestment.\n* PORTFOLIO_REBALANCING — initiated by an automated rebalancing.\n* SELL_TO_COVER_FEES — initiated automatically to cover outstanding fees.\n* SELL_TO_COVER_TAXES — initiated automatically to cover tax obligations.\n* ACCOUNT_LIQUIDATION — initiated as part of an account liquidation.\n* UPVEST_OPERATIONS — initiated by Upvest operations.\n* SAVINGS_PLAN — initiated by a savings plan execution.\n* CLIENT_OPERATIONS — initiated by client operations.", "enum": [ "API", "PORTFOLIO", "CASH_DIVIDEND_REINVESTMENT", "PORTFOLIO_REBALANCING", "SELL_TO_COVER_FEES", "SELL_TO_COVER_TAXES", "ACCOUNT_LIQUIDATION", "UPVEST_OPERATIONS", "SAVINGS_PLAN", "CLIENT_OPERATIONS" ] }, "execution_flow": { "type": "string", "description": "Execution flow for order processing. Defaults to `STRAIGHT_THROUGH` if not specified.\n* STRAIGHT_THROUGH — the order is routed and executed directly without manual intervention.\n* BLOCK — the order is bundled with other orders for block execution.", "enum": [ "STRAIGHT_THROUGH", "BLOCK" ] }, "executions": { "type": "array", "description": "Order executions associated with this order", "items": { "title": "Order execution", "type": "object", "description": "Represents a single execution (trade fill) within an order. An order may have multiple executions if it is partially filled across several trades.", "properties": { "id": { "title": "Order execution unique identifier", "type": "string", "format": "uuid" }, "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "share_quantity": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "price": { "type": "string", "description": "Price of an instrument for a trade execution provided as a decimal string.", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,4})?$" }, "transaction_time": { "type": "string", "format": "date-time", "description": "Timestamp of when the trade was executed at the market. [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) date-time format." }, "taxes": { "type": "array", "description": "Taxes deducted as part of this execution.", "items": { "title": "Tax", "type": "object", "description": "Tax deducted as part of an order execution. Contains the tax type and the deducted amount.", "properties": { "type": { "type": "string", "description": "Tax type\n* TOTAL - ", "default": "TOTAL", "enum": [ "TOTAL" ] }, "amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" } }, "required": [ "type", "amount" ] } }, "order_id": { "title": "Order unique identifier", "type": "string", "description": "Unique identifier for an order. Universally Unique Identifier (UUID).", "format": "uuid" }, "status": { "type": "string", "description": "Status of the execution.\n* FILLED — the execution has been filled.\n* SETTLED — the execution has settled and securities and cash have been exchanged.\n* CANCELLED — the execution was cancelled before settlement.", "enum": [ "FILLED", "SETTLED", "CANCELLED" ] }, "side": { "type": "string", "description": "Side of the execution.\n* BUY — a buy execution.\n* SELL — a sell execution.", "enum": [ "BUY", "SELL" ] }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound\n* USD - US Dollar", "enum": [ "EUR", "GBP", "USD" ] }, "settlement_date": { "allOf": [ { "title": "Settlement date", "type": "string", "description": "Trade settlement date in YYYY-MM-DD format. The date on which securities and cash are exchanged following execution.", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, { "description": "Order execution settlement date in the YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339" } ] }, "venue_id": { "type": "string", "format": "uuid", "description": "The ID of the venue" } }, "required": [ "id", "cash_amount", "share_quantity", "price", "transaction_time", "taxes", "order_id", "status", "side", "currency", "venue_id" ], "additionalProperties": false } }, "client_reference": { "type": "string", "description": "Immutable reference to the API flow that initiated the order. For client initiated API flows, this is a client provided ID. For internal initiations, it is set to the ID of the related object.", "maxLength": 100 }, "fee_configuration": { "type": "array", "description": "Fee configuration applied to this order. Determines how the order fee is calculated.", "items": { "title": "Fee", "description": "A fee applied to an order. Either a fixed absolute cash fee (`absolute_fee_configuration_item`) or a reference to a predefined transaction fee model.", "oneOf": [ { "title": "Absolute Fee", "type": "object", "description": "A fixed cash fee applied to an order, specified as an absolute amount in a given currency.", "properties": { "type": { "title": "Fee type", "description": "Fee type\n* TRANSACTION_FEE_BUY - \n* TRANSACTION_FEE_SELL - ", "type": "string", "enum": [ "TRANSACTION_FEE_BUY", "TRANSACTION_FEE_SELL" ] }, "value_type": { "type": "string", "default": "ABSOLUTE", "description": "The value type must be “ABSOLUTE”." }, "charge_method": { "title": "Fee charge method", "type": "string", "description": "Indicates whether the fee will be charged by client or by other methods.\n* CHARGED_BY_CLIENT - \n* COLLECTED_BY_UPVEST - ", "enum": [ "CHARGED_BY_CLIENT", "COLLECTED_BY_UPVEST" ] }, "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound\n* USD - US Dollar", "enum": [ "EUR", "GBP", "USD" ] } }, "required": [ "type", "value_type", "charge_method", "cash_amount", "currency" ], "additionalProperties": false }, { "title": "Transaction Fee Model", "type": "object", "description": "A fee configuration that references a predefined transaction fee model by its ID, rather than specifying a fee amount directly.", "properties": { "type": { "title": "Fee type", "description": "Fee type\n* TRANSACTION_FEE_BUY - \n* TRANSACTION_FEE_SELL - ", "type": "string", "enum": [ "TRANSACTION_FEE_BUY", "TRANSACTION_FEE_SELL" ] }, "transaction_fee_model_id": { "type": "string", "format": "uuid", "description": "The ID of the transaction fee model." } }, "required": [ "type", "transaction_fee_model_id" ], "additionalProperties": false } ] } }, "decision_maker_id": { "type": "string", "description": "ID of the user behind the decision to place an order. Required only if different from the user_id. (e.g. child account order placed by a guardian)" } }, "required": [ "id", "created_at", "updated_at", "account_id", "cash_amount", "currency", "side", "instrument_id", "instrument_id_type", "order_type", "quantity", "status", "fee", "initiation_flow", "executions" ], "additionalProperties": false }, "examples": { "place_nominal_buy": { "summary": "Nominal Buy Order Response", "value": { "id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "user_id": "2dedfeb0-58cd-44f2-ae08-0e41fe0413d9", "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3", "cash_amount": "1000", "currency": "EUR", "side": "BUY", "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "order_type": "MARKET", "quantity": "0", "user_instrument_fit_acknowledgement": true, "limit_price": "", "stop_price": "", "status": "NEW", "fee": "0.0", "executions": [], "client_reference": "", "initiation_flow": "API" } }, "place_nominal_buy_with_fee_configuration": { "summary": "Nominal Buy Order Response with fee configuration", "value": { "id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "user_id": "2dedfeb0-58cd-44f2-ae08-0e41fe0413d9", "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3", "cash_amount": "1000", "currency": "EUR", "side": "BUY", "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "order_type": "MARKET", "quantity": "0", "user_instrument_fit_acknowledgement": true, "limit_price": "", "stop_price": "", "status": "NEW", "fee": "0.0", "executions": [], "client_reference": "", "initiation_flow": "API", "fee_configuration": [ { "cash_amount": "0.90", "currency": "EUR", "type": "TRANSACTION_FEE_BUY", "charge_method": "CHARGED_BY_CLIENT", "value_type": "ABSOLUTE" } ] } }, "place_nominal_buy_with_fee_model": { "summary": "Nominal Buy Order Response with fee model", "value": { "id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "user_id": "2dedfeb0-58cd-44f2-ae08-0e41fe0413d9", "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3", "cash_amount": "1000", "currency": "EUR", "side": "BUY", "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "order_type": "MARKET", "quantity": "0", "user_instrument_fit_acknowledgement": true, "limit_price": "", "stop_price": "", "status": "NEW", "fee": "0.0", "executions": [], "client_reference": "", "initiation_flow": "API", "fee_configuration": [ { "type": "TRANSACTION_FEE_BUY", "transaction_fee_model_id": "eb5ba93f-5dfe-4bf1-84da-0caacc80c000" } ] } }, "place_nominal_buy_executions": { "summary": "Nominal Buy Order Response with Executions", "value": { "id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "user_id": "2dedfeb0-58cd-44f2-ae08-0e41fe0413d9", "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3", "cash_amount": "1000", "currency": "EUR", "side": "BUY", "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "order_type": "MARKET", "quantity": "0", "user_instrument_fit_acknowledgement": true, "limit_price": "", "stop_price": "", "status": "FILLED", "fee": "0.0", "executions": [ { "id": "b9dc0676-8a7d-412d-802a-3b325eefd15e", "side": "BUY", "currency": "EUR", "status": "FILLED", "order_id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c", "cash_amount": "1000", "share_quantity": "11.734334663", "price": "85.22", "transaction_time": "2021-07-21T14:10:00.020Z", "taxes": [ { "type": "TOTAL", "amount": "0" } ], "venue_id": "20d6024b-2df4-41ae-8d42-62e4744e455b" } ], "client_reference": "", "initiation_flow": "API" } }, "place_unit_sell": { "summary": "Unit Sell Order Response", "value": { "id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "user_id": "2dedfeb0-58cd-44f2-ae08-0e41fe0413d9", "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3", "cash_amount": "0", "currency": "EUR", "side": "SELL", "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "order_type": "MARKET", "quantity": "10", "user_instrument_fit_acknowledgement": true, "limit_price": "", "stop_price": "", "status": "NEW", "fee": "0.0", "executions": [], "client_reference": "", "initiation_flow": "API" } }, "place_unit_sell_with_fee_configuration": { "summary": "Unit Sell Order Response with fee configuration", "value": { "id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "user_id": "2dedfeb0-58cd-44f2-ae08-0e41fe0413d9", "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3", "cash_amount": "0", "currency": "EUR", "side": "SELL", "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "order_type": "MARKET", "quantity": "10", "user_instrument_fit_acknowledgement": true, "limit_price": "", "stop_price": "", "status": "NEW", "fee": "0.0", "executions": [], "client_reference": "", "initiation_flow": "API", "fee_configuration": [ { "cash_amount": "0.90", "charge_method": "CHARGED_BY_CLIENT", "currency": "EUR", "type": "TRANSACTION_FEE_SELL", "value_type": "ABSOLUTE" } ] } }, "place_unit_sell_with_fee_model": { "summary": "Unit Sell Order Response with fee model", "value": { "id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "user_id": "2dedfeb0-58cd-44f2-ae08-0e41fe0413d9", "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3", "cash_amount": "0", "currency": "EUR", "side": "SELL", "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "order_type": "MARKET", "quantity": "10", "user_instrument_fit_acknowledgement": true, "limit_price": "", "stop_price": "", "status": "NEW", "fee": "0.0", "executions": [], "client_reference": "", "initiation_flow": "API", "fee_configuration": [ { "type": "TRANSACTION_FEE_SELL", "transaction_fee_model_id": "eb5ba93f-5dfe-4bf1-84da-0caacc80c000" } ] } }, "place_unit_sell_executions": { "summary": "Unit Sell Order Response with Executions", "value": { "id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "user_id": "2dedfeb0-58cd-44f2-ae08-0e41fe0413d9", "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3", "cash_amount": "0", "currency": "EUR", "side": "SELL", "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "order_type": "MARKET", "quantity": "10", "user_instrument_fit_acknowledgement": true, "limit_price": "", "stop_price": "", "status": "FILLED", "fee": "0.0", "executions": [ { "id": "b9dc0676-8a7d-412d-802a-3b325eefd15e", "side": "SELL", "currency": "EUR", "status": "FILLED", "order_id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c", "cash_amount": "852.20", "share_quantity": "10", "price": "85.22", "transaction_time": "2021-07-21T14:10:00.020Z", "taxes": [ { "type": "TOTAL", "amount": "23.45" } ], "venue_id": "20d6024b-2df4-41ae-8d42-62e4744e455b" } ], "client_reference": "", "initiation_flow": "API" } } } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "422": { "description": "Unprocessable Entity. The syntax of request is correct but server can't process it due a semantic error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 422, "type": "unprocessable_entity" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/orders/{order_id}": { "parameters": [ { "name": "order_id", "description": "The unique identifier of the order. Universally Unique Identifier (UUID).", "in": "path", "required": true, "schema": { "title": "Order unique identifier", "type": "string", "description": "Unique identifier for an order. Universally Unique Identifier (UUID).", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_order", "summary": "Get an order by ID", "description": "Returns the order specified by its ID, including its current status, executions, fee configuration, and any cancellation reason.\n\nSee the Orders guide ([TOL](https://docs.upvest.co/products/tol/guides/orders) / [BYOL](https://docs.upvest.co/products/byol/guides/orders) / [Omnibus](https://docs.upvest.co/products/omnibus/guides/orders)) for order lifecycle details.", "tags": [ "Orders" ], "security": [ { "oauth-client-credentials": [ "orders:read", "orders:admin" ] } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Order", "type": "object", "description": "Represents an investment order placed by an end user or on their behalf. An order transitions through states (`NEW` → `PROCESSING` → `FILLED` or `CANCELLED`) as it is routed and executed.", "properties": { "id": { "title": "Order unique identifier", "type": "string", "description": "Unique identifier for an order. Universally Unique Identifier (UUID).", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "type": "string", "format": "uuid", "description": "The ID of the user. Either user ID or business ID must be specified." }, "business_id": { "type": "string", "format": "uuid", "description": "The ID of the business. Either user ID or business ID must be specified." }, "account_id": { "type": "string", "format": "uuid", "description": "The ID of the account that owns the order" }, "cash_amount": { "allOf": [ { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, { "description": "Cash amount for a nominal order, not required if a share quantity is specified." } ] }, "currency": { "allOf": [ { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound\n* USD - US Dollar", "enum": [ "EUR", "GBP", "USD" ] }, { "description": "The currency for the order." } ] }, "side": { "type": "string", "description": "Side of the order.\n* BUY — purchases the specified instrument.\n* SELL — disposes of the specified instrument.", "enum": [ "BUY", "SELL" ] }, "instrument_id": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, "instrument_id_type": { "description": "The type of the ID used in the request.\n* ISIN - ", "enum": [ "ISIN" ], "default": "ISIN", "type": "string" }, "order_type": { "type": "string", "description": "Type of the order.\n* MARKET — executes immediately at the best available market price.\n* LIMIT — executes only at or better than the specified `limit_price`.\n* STOP — triggers when the market price reaches `stop_price`, then executes at the prevailing market price.", "enum": [ "MARKET", "LIMIT", "STOP" ] }, "quantity": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "Quantity of securities for the order. Only required if the cash amount is not specified." } ] }, "user_instrument_fit_acknowledgement": { "type": "boolean", "description": "Only applicable if the user has failed the instrument fit check for the instrument type being ordered. True if the user has acknowledged their willingness to trade." }, "limit_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The limit price for orders of the type 'limit'." } ] }, "stop_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The stop price for orders of the type 'stop'." } ] }, "expiry_date": { "allOf": [ { "title": "Expiry date", "type": "string", "description": "Order expiration date in YYYY-MM-DD format. Only applicable to `LIMIT` and `STOP` orders — the order will not execute after this date. Defaults to order creation date plus 359 days.", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, { "description": "The order expiration date (last day the order can trade) in the YYYY-MM-DD format. The expiry date can only be set for LIMIT and STOP orders. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339. The default value is order creation date + 359 days" } ] }, "status": { "type": "string", "description": "The execution status of the order.\n* NEW — the order has been received and validated, awaiting routing.\n* PROCESSING — the order is being routed for execution.\n* FILLED — the order has been fully executed.\n* CANCELLED — the order was cancelled before being fully executed.", "enum": [ "NEW", "PROCESSING", "FILLED", "CANCELLED" ] }, "fee": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "cancellation_reason": { "type": "string", "description": "Reason for order cancellation. Present only when `status` is `CANCELLED`.\n* CANCELLED_BY_CLIENT — cancelled at the end user's or client's request via the API.\n* CANCELLED_BY_UPVEST_OPERATIONS — cancelled by Upvest operations.\n* CANCELLED_BY_TRADING_PARTNER — cancelled by the executing partner.\n* CANCELLED_BY_UPVEST_PLATFORM — cancelled automatically by the Upvest platform.", "enum": [ "CANCELLED_BY_CLIENT", "CANCELLED_BY_UPVEST_OPERATIONS", "CANCELLED_BY_TRADING_PARTNER", "CANCELLED_BY_UPVEST_PLATFORM" ] }, "initiation_flow": { "type": "string", "description": "Identifies what triggered the order.\n* API — initiated directly via the client API.\n* PORTFOLIO — initiated by a portfolio rebalancing flow.\n* CASH_DIVIDEND_REINVESTMENT — initiated as part of dividend reinvestment.\n* PORTFOLIO_REBALANCING — initiated by an automated rebalancing.\n* SELL_TO_COVER_FEES — initiated automatically to cover outstanding fees.\n* SELL_TO_COVER_TAXES — initiated automatically to cover tax obligations.\n* ACCOUNT_LIQUIDATION — initiated as part of an account liquidation.\n* UPVEST_OPERATIONS — initiated by Upvest operations.\n* SAVINGS_PLAN — initiated by a savings plan execution.\n* CLIENT_OPERATIONS — initiated by client operations.", "enum": [ "API", "PORTFOLIO", "CASH_DIVIDEND_REINVESTMENT", "PORTFOLIO_REBALANCING", "SELL_TO_COVER_FEES", "SELL_TO_COVER_TAXES", "ACCOUNT_LIQUIDATION", "UPVEST_OPERATIONS", "SAVINGS_PLAN", "CLIENT_OPERATIONS" ] }, "execution_flow": { "type": "string", "description": "Execution flow for order processing. Defaults to `STRAIGHT_THROUGH` if not specified.\n* STRAIGHT_THROUGH — the order is routed and executed directly without manual intervention.\n* BLOCK — the order is bundled with other orders for block execution.", "enum": [ "STRAIGHT_THROUGH", "BLOCK" ] }, "executions": { "type": "array", "description": "Order executions associated with this order", "items": { "title": "Order execution", "type": "object", "description": "Represents a single execution (trade fill) within an order. An order may have multiple executions if it is partially filled across several trades.", "properties": { "id": { "title": "Order execution unique identifier", "type": "string", "format": "uuid" }, "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "share_quantity": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "price": { "type": "string", "description": "Price of an instrument for a trade execution provided as a decimal string.", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,4})?$" }, "transaction_time": { "type": "string", "format": "date-time", "description": "Timestamp of when the trade was executed at the market. [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) date-time format." }, "taxes": { "type": "array", "description": "Taxes deducted as part of this execution.", "items": { "title": "Tax", "type": "object", "description": "Tax deducted as part of an order execution. Contains the tax type and the deducted amount.", "properties": { "type": { "type": "string", "description": "Tax type\n* TOTAL - ", "default": "TOTAL", "enum": [ "TOTAL" ] }, "amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" } }, "required": [ "type", "amount" ] } }, "order_id": { "title": "Order unique identifier", "type": "string", "description": "Unique identifier for an order. Universally Unique Identifier (UUID).", "format": "uuid" }, "status": { "type": "string", "description": "Status of the execution.\n* FILLED — the execution has been filled.\n* SETTLED — the execution has settled and securities and cash have been exchanged.\n* CANCELLED — the execution was cancelled before settlement.", "enum": [ "FILLED", "SETTLED", "CANCELLED" ] }, "side": { "type": "string", "description": "Side of the execution.\n* BUY — a buy execution.\n* SELL — a sell execution.", "enum": [ "BUY", "SELL" ] }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound\n* USD - US Dollar", "enum": [ "EUR", "GBP", "USD" ] }, "settlement_date": { "allOf": [ { "title": "Settlement date", "type": "string", "description": "Trade settlement date in YYYY-MM-DD format. The date on which securities and cash are exchanged following execution.", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, { "description": "Order execution settlement date in the YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339" } ] }, "venue_id": { "type": "string", "format": "uuid", "description": "The ID of the venue" } }, "required": [ "id", "cash_amount", "share_quantity", "price", "transaction_time", "taxes", "order_id", "status", "side", "currency", "venue_id" ], "additionalProperties": false } }, "client_reference": { "type": "string", "description": "Immutable reference to the API flow that initiated the order. For client initiated API flows, this is a client provided ID. For internal initiations, it is set to the ID of the related object.", "maxLength": 100 }, "fee_configuration": { "type": "array", "description": "Fee configuration applied to this order. Determines how the order fee is calculated.", "items": { "title": "Fee", "description": "A fee applied to an order. Either a fixed absolute cash fee (`absolute_fee_configuration_item`) or a reference to a predefined transaction fee model.", "oneOf": [ { "title": "Absolute Fee", "type": "object", "description": "A fixed cash fee applied to an order, specified as an absolute amount in a given currency.", "properties": { "type": { "title": "Fee type", "description": "Fee type\n* TRANSACTION_FEE_BUY - \n* TRANSACTION_FEE_SELL - ", "type": "string", "enum": [ "TRANSACTION_FEE_BUY", "TRANSACTION_FEE_SELL" ] }, "value_type": { "type": "string", "default": "ABSOLUTE", "description": "The value type must be “ABSOLUTE”." }, "charge_method": { "title": "Fee charge method", "type": "string", "description": "Indicates whether the fee will be charged by client or by other methods.\n* CHARGED_BY_CLIENT - \n* COLLECTED_BY_UPVEST - ", "enum": [ "CHARGED_BY_CLIENT", "COLLECTED_BY_UPVEST" ] }, "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound\n* USD - US Dollar", "enum": [ "EUR", "GBP", "USD" ] } }, "required": [ "type", "value_type", "charge_method", "cash_amount", "currency" ], "additionalProperties": false }, { "title": "Transaction Fee Model", "type": "object", "description": "A fee configuration that references a predefined transaction fee model by its ID, rather than specifying a fee amount directly.", "properties": { "type": { "title": "Fee type", "description": "Fee type\n* TRANSACTION_FEE_BUY - \n* TRANSACTION_FEE_SELL - ", "type": "string", "enum": [ "TRANSACTION_FEE_BUY", "TRANSACTION_FEE_SELL" ] }, "transaction_fee_model_id": { "type": "string", "format": "uuid", "description": "The ID of the transaction fee model." } }, "required": [ "type", "transaction_fee_model_id" ], "additionalProperties": false } ] } }, "decision_maker_id": { "type": "string", "description": "ID of the user behind the decision to place an order. Required only if different from the user_id. (e.g. child account order placed by a guardian)" } }, "required": [ "id", "created_at", "updated_at", "account_id", "cash_amount", "currency", "side", "instrument_id", "instrument_id_type", "order_type", "quantity", "status", "fee", "initiation_flow", "executions" ], "additionalProperties": false }, "example": { "id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "user_id": "2dedfeb0-58cd-44f2-ae08-0e41fe0413d9", "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3", "cash_amount": "56.65", "currency": "EUR", "side": "BUY", "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "order_type": "MARKET", "quantity": "0.05", "user_instrument_fit_acknowledgement": true, "limit_price": "", "stop_price": "", "status": "NEW", "fee": "0.5", "executions": [], "client_reference": "", "initiation_flow": "API", "execution_flow": "STRAIGHT_THROUGH" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "delete": { "operationId": "cancel_order", "summary": "Cancel an order by ID", "description": "Cancels an order specified by its ID. It is possible to cancel an order in the `NEW` or `PROCESSING` status. Once a cancellation has been accepted, the further processing steps take place asynchronously and depending on the respective order status.", "tags": [ "Orders" ], "security": [ { "oauth-client-credentials": [ "orders:admin" ] } ], "responses": { "202": { "description": "The order cancelling request is accepted.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Order - Cancel - Response", "type": "object", "description": "Response returned when an order cancellation request is accepted. Contains the `id` of the order for which cancellation was requested.", "properties": { "id": { "title": "Order unique identifier", "type": "string", "description": "Unique identifier for an order. Universally Unique Identifier (UUID).", "format": "uuid" } }, "required": [ "id" ], "additionalProperties": false }, "example": { "id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/orders/{order_id}/executions/{execution_id}": { "parameters": [ { "name": "execution_id", "description": "The unique identifier of the order execution. Universally Unique Identifier (UUID).", "in": "path", "required": true, "schema": { "title": "Order execution unique identifier", "type": "string", "description": "Unique identifier for an order execution. Universally Unique Identifier (UUID).", "format": "uuid" } }, { "name": "order_id", "description": "The unique identifier of the order. Universally Unique Identifier (UUID).", "in": "path", "required": true, "schema": { "title": "Order unique identifier", "type": "string", "description": "Unique identifier for an order. Universally Unique Identifier (UUID).", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_order_execution", "summary": "Get an order execution by ID", "description": "Returns the order execution specified by its ID. An execution represents a single trade fill within an order; an order may have multiple executions if it is partially filled across several trades.\n\nSee the Orders guide ([TOL](https://docs.upvest.co/products/tol/guides/orders) / [BYOL](https://docs.upvest.co/products/byol/guides/orders) / [Omnibus](https://docs.upvest.co/products/omnibus/guides/orders)) for execution lifecycle details.", "tags": [ "Orders" ], "security": [ { "oauth-client-credentials": [ "orders:read", "orders:admin" ] } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Order execution", "type": "object", "description": "Represents a single execution (trade fill) within an order. An order may have multiple executions if it is partially filled across several trades.", "properties": { "id": { "title": "Order execution unique identifier", "type": "string", "format": "uuid" }, "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "share_quantity": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "price": { "type": "string", "description": "Price of an instrument for a trade execution provided as a decimal string.", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,4})?$" }, "transaction_time": { "type": "string", "format": "date-time", "description": "Timestamp of when the trade was executed at the market. [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) date-time format." }, "taxes": { "type": "array", "description": "Taxes deducted as part of this execution.", "items": { "title": "Tax", "type": "object", "description": "Tax deducted as part of an order execution. Contains the tax type and the deducted amount.", "properties": { "type": { "type": "string", "description": "Tax type\n* TOTAL - ", "default": "TOTAL", "enum": [ "TOTAL" ] }, "amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" } }, "required": [ "type", "amount" ] } }, "order_id": { "title": "Order unique identifier", "type": "string", "description": "Unique identifier for an order. Universally Unique Identifier (UUID).", "format": "uuid" }, "status": { "type": "string", "description": "Status of the execution.\n* FILLED — the execution has been filled.\n* SETTLED — the execution has settled and securities and cash have been exchanged.\n* CANCELLED — the execution was cancelled before settlement.", "enum": [ "FILLED", "SETTLED", "CANCELLED" ] }, "side": { "type": "string", "description": "Side of the execution.\n* BUY — a buy execution.\n* SELL — a sell execution.", "enum": [ "BUY", "SELL" ] }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound\n* USD - US Dollar", "enum": [ "EUR", "GBP", "USD" ] }, "settlement_date": { "allOf": [ { "title": "Settlement date", "type": "string", "description": "Trade settlement date in YYYY-MM-DD format. The date on which securities and cash are exchanged following execution.", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, { "description": "Order execution settlement date in the YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339" } ] }, "venue_id": { "type": "string", "format": "uuid", "description": "The ID of the venue" } }, "required": [ "id", "cash_amount", "share_quantity", "price", "transaction_time", "taxes", "order_id", "status", "side", "currency", "venue_id" ], "additionalProperties": false }, "example": { "id": "b9dc0676-8a7d-412d-802a-3b325eefd15e", "side": "BUY", "currency": "EUR", "status": "SETTLED", "order_id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c", "cash_amount": "56.65", "share_quantity": "0.05", "price": "130.65", "transaction_time": "2021-07-21T14:10:00.00Z", "taxes": [ { "amount": "1.3", "type": "TOTAL" } ], "settlement_date": "2021-07-23", "venue_id": "20d6024b-2df4-41ae-8d42-62e4744e455b" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/users/{user_id}/reports": { "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "The unique identifier of the user. Universally Unique Identifier (UUID).", "schema": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_user_reports", "summary": "List user reports", "description": "List user reports", "tags": [ "Reports" ], "security": [ { "oauth-client-credentials": [ "reports:read", "reports:admin" ] } ], "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "title": "Report type", "oneOf": [ { "title": "Report type", "description": "Report type\n* ACCOUNT_CLOSING - Securities account closure\n* ACCOUNT_OPENING - Securities account opening\n* AD_HOC_ACCOUNT_STATEMENT - Ad hoc account statement\n* ANNUAL_INCOME_STATEMENT - Annual tax income statement (\"Erträgnisaufstellung\")\n* ANNUAL_TAX_STATEMENT - Annual tax reporting\n* BANK_ACCOUNT_CONNECTED - Connect reference bank account\n* BUY_ORDER - Buy order\n* CANCELLED_ORDER - Cancelled buy or sell order (not yet executed, user cancels or trading venue cancelled)\n* CORPORATE_ACTION_CASH_TRANSACTION - cash transaction document (after corporate action)\n* CORPORATE_ACTION_SECURITY_TRANSACTION - security transaction document (after corporate action)\n* DIRECT_DEBIT_MANDATE - Creation of SEPA direct debit mandate\n* EX_POST_COST - Ex-post cost report\n* FEE_COLLECTION - Intake of service fees\n* FRENCH_IFU - French tax statement (Imprimé fiscal unique)\n* GENERIC_COMMUNICATION - Generic communication\n* INCOME_DISTRIBUTION - Income distribution report\n* LOSS_THRESHOLD - Notification that a holding has depreciated by 10%, or a multiple thereof, against its purchase value\n* MONTHLY_BILLING_STATEMENT - Monthly billing activities statement\n* QUARTERLY_ACCOUNT_STATEMENT - Quarterly account statement\n* REVOKED_ORDER - Revoked buy or sell order (\"Storno\")\n* SECURITIES_TRANSFER_INCOMING - Securities are transferred in\n* SECURITIES_TRANSFER_OUTGOING - Securities are being transferred out\n* SELL_ORDER - Sell order\n* TAX_CONSOLIDATED_CERTIFICATE_UK - UK Consolidated Tax Certificate\n* TAX_PAYMENT - Tax payment document\n* TAX_PREPAYMENT_DE - German tax prepayment (Vorabpauschale)\n* TAX_PREPAYMENT_DE_CANCELLATION - German tax prepayment (Vorabpauschale) cancellation\n* TAX_REFUND - Tax refund document (after tax optimization)", "type": "string", "enum": [ "ACCOUNT_CLOSING", "ACCOUNT_OPENING", "AD_HOC_ACCOUNT_STATEMENT", "ANNUAL_INCOME_STATEMENT", "ANNUAL_TAX_STATEMENT", "BANK_ACCOUNT_CONNECTED", "BUY_ORDER", "CANCELLED_ORDER", "CORPORATE_ACTION_CASH_TRANSACTION", "CORPORATE_ACTION_SECURITY_TRANSACTION", "DIRECT_DEBIT_MANDATE", "EX_POST_COST", "FEE_COLLECTION", "FRENCH_IFU", "GENERIC_COMMUNICATION", "INCOME_DISTRIBUTION", "LOSS_THRESHOLD", "MONTHLY_BILLING_STATEMENT", "QUARTERLY_ACCOUNT_STATEMENT", "REVOKED_ORDER", "SECURITIES_TRANSFER_INCOMING", "SECURITIES_TRANSFER_OUTGOING", "SELL_ORDER", "TAX_CONSOLIDATED_CERTIFICATE_UK", "TAX_PAYMENT", "TAX_PREPAYMENT_DE", "TAX_PREPAYMENT_DE_CANCELLATION", "TAX_REFUND" ] }, { "type": "string", "enum": [ "ORDER_EX_ANTE_COST", "ORDER_EX_ANTE_COST_SAVINGS_PLAN" ], "description": "The type of report must be “ORDER_EX_ANTE_COST” or “ORDER_EX_ANTE_COST_SAVINGS_PLAN”." } ] }, "description": "Filters the list to only show reports of a certain type (e.g. only buy order confirmations)", "example": "BUY_ORDER" }, { "name": "instrument", "in": "query", "required": false, "schema": { "oneOf": [ { "title": "International securities identification number, prefixed with string 'isin:'", "type": "string", "description": "International securities identification number, prefixed with string 'isin:'", "pattern": "^isin:[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, { "title": "Unique identifier, prefixed with string 'uuid:'", "type": "string", "description": "Unique identifier, prefixed with string 'uuid:'", "pattern": "^uuid:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } ], "example": "uuid:ebabcf4d-61c3-4942-875c-e265a7c2d062" }, "description": "Filters the list to only include reports concerning specified instrument" }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "title": "Date in YYYY-MM-DD format. RFC 3339, section 5.6", "description": "Returns reports generated starting from and including this date (UTC)" }, "example": "2020-08-21" }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "title": "Date in YYYY-MM-DD format. RFC 3339, section 5.6", "description": "Returns reports generated up until this date (UTC)" }, "example": "2020-09-25" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "id", "type", "created_at" ], "default": "created_at" }, "description": "Field of resource to sort by", "example": "id" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." } ], "responses": { "200": { "description": "Reports list", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Reports - List - Response", "type": "object", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count", "sort", "order" ] }, "data": { "type": "array", "items": { "title": "User Report", "type": "object", "properties": { "id": { "title": "Report unique identifier.", "type": "string", "description": "Report unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "type": { "title": "Report type", "description": "Report type\n* ACCOUNT_CLOSING - Securities account closure\n* ACCOUNT_OPENING - Securities account opening\n* AD_HOC_ACCOUNT_STATEMENT - Ad hoc account statement\n* ANNUAL_INCOME_STATEMENT - Annual tax income statement (\"Erträgnisaufstellung\")\n* ANNUAL_TAX_STATEMENT - Annual tax reporting\n* BANK_ACCOUNT_CONNECTED - Connect reference bank account\n* BUY_ORDER - Buy order\n* CANCELLED_ORDER - Cancelled buy or sell order (not yet executed, user cancels or trading venue cancelled)\n* CORPORATE_ACTION_CASH_TRANSACTION - cash transaction document (after corporate action)\n* CORPORATE_ACTION_SECURITY_TRANSACTION - security transaction document (after corporate action)\n* DIRECT_DEBIT_MANDATE - Creation of SEPA direct debit mandate\n* EX_POST_COST - Ex-post cost report\n* FEE_COLLECTION - Intake of service fees\n* FRENCH_IFU - French tax statement (Imprimé fiscal unique)\n* GENERIC_COMMUNICATION - Generic communication\n* INCOME_DISTRIBUTION - Income distribution report\n* LOSS_THRESHOLD - Notification that a holding has depreciated by 10%, or a multiple thereof, against its purchase value\n* MONTHLY_BILLING_STATEMENT - Monthly billing activities statement\n* QUARTERLY_ACCOUNT_STATEMENT - Quarterly account statement\n* REVOKED_ORDER - Revoked buy or sell order (\"Storno\")\n* SECURITIES_TRANSFER_INCOMING - Securities are transferred in\n* SECURITIES_TRANSFER_OUTGOING - Securities are being transferred out\n* SELL_ORDER - Sell order\n* TAX_CONSOLIDATED_CERTIFICATE_UK - UK Consolidated Tax Certificate\n* TAX_PAYMENT - Tax payment document\n* TAX_PREPAYMENT_DE - German tax prepayment (Vorabpauschale)\n* TAX_PREPAYMENT_DE_CANCELLATION - German tax prepayment (Vorabpauschale) cancellation\n* TAX_REFUND - Tax refund document (after tax optimization)", "type": "string", "enum": [ "ACCOUNT_CLOSING", "ACCOUNT_OPENING", "AD_HOC_ACCOUNT_STATEMENT", "ANNUAL_INCOME_STATEMENT", "ANNUAL_TAX_STATEMENT", "BANK_ACCOUNT_CONNECTED", "BUY_ORDER", "CANCELLED_ORDER", "CORPORATE_ACTION_CASH_TRANSACTION", "CORPORATE_ACTION_SECURITY_TRANSACTION", "DIRECT_DEBIT_MANDATE", "EX_POST_COST", "FEE_COLLECTION", "FRENCH_IFU", "GENERIC_COMMUNICATION", "INCOME_DISTRIBUTION", "LOSS_THRESHOLD", "MONTHLY_BILLING_STATEMENT", "QUARTERLY_ACCOUNT_STATEMENT", "REVOKED_ORDER", "SECURITIES_TRANSFER_INCOMING", "SECURITIES_TRANSFER_OUTGOING", "SELL_ORDER", "TAX_CONSOLIDATED_CERTIFICATE_UK", "TAX_PAYMENT", "TAX_PREPAYMENT_DE", "TAX_PREPAYMENT_DE_CANCELLATION", "TAX_REFUND" ] }, "substituted_report_id": { "oneOf": [ { "type": "null" }, { "title": "Substituted Report unique identifier.", "type": "string", "description": "References report that has been replaced by this one.", "format": "uuid" } ] }, "data": { "title": "Report Data", "type": "object", "description": "Contents of the report.", "properties": { "account": { "type": "object", "title": "Account.", "description": "Account information.", "properties": { "id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" } } }, "references": { "type": "array", "title": "References.", "items": { "title": "Report reference data", "type": "object", "description": "Reference data for a report", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "title": "Report reference type", "description": "Report reference type\n* CORPORATE_ACTION_TRANSACTION_ID - Corporate action transaction identifier\n* ACCOUNT_GROUP_ID - Account group identifier\n* ACCOUNT_ID - Account identifier\n* ORDER_ID - Order identifier", "type": "string", "enum": [ "CORPORATE_ACTION_TRANSACTION_ID", "ACCOUNT_GROUP_ID", "ACCOUNT_ID", "ORDER_ID" ] } } } } } } }, "required": [ "id", "user_id", "created_at", "type", "substituted_report_id" ], "additionalProperties": false } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "example": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1, "sort": "id", "order": "ASC" }, "data": [ { "id": "b96b1ee7-d491-43eb-b5e4-4833af9c9c2f", "created_at": "2020-08-24T14:15:22Z", "user_id": "d1a4be99-8bb6-4e78-b897-8168f6823ab5", "type": "CORPORATE_ACTION_CASH_TRANSACTION", "substituted_report_id": null, "data": { "account": { "id": "a9a4ad54-6dd1-419a-a98d-ab48f9f23bc8" }, "references": [ { "id": "b96b1ee7-d491-43eb-b5e4-4833af9c9c2f", "type": "CORPORATE_ACTION_TRANSACTION_ID" } ] } } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/reports": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "post": { "operationId": "create_report", "summary": "Create a user report", "description": "Create a user report", "tags": [ "Reports" ], "security": [ { "oauth-client-credentials": [ "reports:admin" ] } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Report - Order ex-ante cost - Create - Request", "description": "The order ex-ante cost report is generated by the client sharing the valid and relevant input data for the order.", "oneOf": [ { "title": "Report - Order ex-ante cost - Create - Request - Regular", "type": "object", "properties": { "type": { "type": "string", "default": "ORDER_EX_ANTE_COST", "description": "The type of report must be “ORDER_EX_ANTE_COST”." }, "order": { "title": "Order", "oneOf": [ { "title": "Ex-Ante cost user order", "type": "object", "description": "Ex-ante order details for a user.", "properties": { "user_id": { "type": "string", "format": "uuid", "description": "The user's ID." }, "account_id": { "type": "string", "format": "uuid", "description": "Account ID owning the order." }, "cash_amount": { "allOf": [ { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, { "description": "Cash amount for a nominal order." } ] }, "currency": { "allOf": [ { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, { "description": "The currency for the order." } ] }, "side": { "type": "string", "description": "Side of the order.\n* BUY - \n* SELL - ", "enum": [ "BUY", "SELL" ] }, "instrument_id": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, "instrument_id_type": { "description": "The type of the ID used in the request.\n* ISIN - ", "enum": [ "ISIN" ], "default": "ISIN", "type": "string" }, "order_type": { "type": "string", "description": "Order type.\n* MARKET - \n* LIMIT - \n* STOP - ", "enum": [ "MARKET", "LIMIT", "STOP" ] }, "quantity": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "Quantity of securities for the order." } ] }, "limit_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The limit price for orders of the type 'limit'." } ] }, "stop_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The stop price for orders of the type 'stop'." } ] } }, "additionalProperties": false, "required": [ "user_id", "instrument_id", "instrument_id_type", "account_id", "currency", "order_type", "side" ] }, { "title": "Ex-Ante Cost business order", "type": "object", "description": "Ex Ante Order details for a business.", "properties": { "business_id": { "type": "string", "format": "uuid", "description": "The business's ID" }, "account_id": { "type": "string", "format": "uuid", "description": "Account ID owning the order." }, "cash_amount": { "allOf": [ { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, { "description": "Cash amount for a nominal order." } ] }, "currency": { "allOf": [ { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, { "description": "The currency for the order." } ] }, "side": { "type": "string", "description": "Side of the order.\n* BUY - \n* SELL - ", "enum": [ "BUY", "SELL" ] }, "instrument_id": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, "instrument_id_type": { "description": "The type of the ID used in the request.\n* ISIN - ", "enum": [ "ISIN" ], "default": "ISIN", "type": "string" }, "order_type": { "type": "string", "description": "Order type.\n* MARKET - \n* LIMIT - \n* STOP - ", "enum": [ "MARKET", "LIMIT", "STOP" ] }, "quantity": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "Quantity of securities for the order." } ] }, "limit_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The limit price for orders of the type 'limit'." } ] }, "stop_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The stop price for orders of the type 'stop'." } ] } }, "additionalProperties": false, "required": [ "business_id", "instrument_id", "instrument_id_type", "account_id", "currency", "order_type", "side" ] } ] }, "fees": { "type": "array", "description": "Client fees.", "items": { "title": "Fee", "oneOf": [ { "title": "Absolute Fee", "type": "object", "properties": { "type": { "title": "Fee type", "description": "Fee type\n* TRANSACTION_FEE_BUY - \n* TRANSACTION_FEE_SELL - \n* ANNUAL_AUM_BASED_FEE - ", "type": "string", "enum": [ "TRANSACTION_FEE_BUY", "TRANSACTION_FEE_SELL", "ANNUAL_AUM_BASED_FEE" ] }, "value_type": { "type": "string", "default": "ABSOLUTE", "description": "The type of fee value must be “ABSOLUTE”." }, "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] } }, "required": [ "type", "value_type", "cash_amount", "currency" ], "additionalProperties": false }, { "title": "Relative Fee", "type": "object", "properties": { "type": { "title": "Fee type", "description": "Fee type\n* TRANSACTION_FEE_BUY - \n* TRANSACTION_FEE_SELL - \n* ANNUAL_AUM_BASED_FEE - ", "type": "string", "enum": [ "TRANSACTION_FEE_BUY", "TRANSACTION_FEE_SELL", "ANNUAL_AUM_BASED_FEE" ] }, "value_type": { "type": "string", "default": "RELATIVE", "description": "The type of fee value must be “RELATIVE”." }, "bps": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "A fee is charged based on transaction amount and is represented in basis points." } ] } }, "required": [ "type", "value_type", "bps" ], "additionalProperties": false }, { "title": "Transaction Fee", "type": "object", "properties": { "type": { "title": "Fee type", "description": "Fee type\n* TRANSACTION_FEE_BUY - \n* TRANSACTION_FEE_SELL -", "type": "string", "enum": [ "TRANSACTION_FEE_BUY", "TRANSACTION_FEE_SELL" ] }, "transaction_fee_model_id": { "type": "string", "format": "uuid", "description": "The ID of the transaction fee model." } }, "required": [ "type", "transaction_fee_model_id" ], "additionalProperties": false } ] } }, "inducements": { "type": "array", "description": "Client inducements.", "items": { "title": "Inducement", "type": "object", "properties": { "value_type": { "type": "string", "default": "ABSOLUTE", "description": "The type of inducement value must be “ABSOLUTE”." }, "cash_amount": { "type": "string", "pattern": "^-?[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] } }, "required": [ "value_type", "cash_amount", "currency" ], "additionalProperties": false } } }, "required": [ "type", "order" ], "additionalProperties": false }, { "title": "Report - Order ex-ante cost - Create - Request - Savings Plan", "type": "object", "properties": { "type": { "type": "string", "default": "ORDER_EX_ANTE_COST_SAVINGS_PLAN", "description": "The type of report must be “ORDER_EX_ANTE_COST_SAVINGS_PLAN”. Savings plan ex-ante reports are only supported for individual users, not for business entities." }, "order": { "title": "Ex-Ante Cost Savings Plan order", "type": "object", "description": "Savings Plan Order details.", "properties": { "user_id": { "type": "string", "format": "uuid", "description": "The ID of the user." }, "account_id": { "type": "string", "format": "uuid", "description": "Account ID owning the order." }, "cash_amount": { "allOf": [ { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, { "description": "Cash amount for a nominal order." } ] }, "currency": { "allOf": [ { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, { "description": "The currency for the order." } ] }, "side": { "type": "string", "description": "Side of the order.\n* BUY - \n* SELL - ", "enum": [ "BUY", "SELL" ] }, "instrument_id": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, "instrument_id_type": { "description": "The type of the ID used in the request.\n* ISIN - ", "enum": [ "ISIN" ], "default": "ISIN", "type": "string" }, "order_type": { "type": "string", "description": "Order type.\n* MARKET - \n* LIMIT - \n* STOP - ", "enum": [ "MARKET", "LIMIT", "STOP" ] }, "period": { "type": "string", "enum": [ "WEEK", "MONTH", "YEAR" ] }, "interval": { "type": "string", "pattern": "^[0-9]{1,63}$" } }, "required": [ "instrument_id", "instrument_id_type", "account_id", "user_id", "cash_amount", "currency", "order_type", "side", "period", "interval" ] }, "fees": { "type": "array", "description": "Client fees.", "items": { "title": "Fee", "oneOf": [ { "title": "Absolute Fee", "type": "object", "properties": { "type": { "title": "Fee type", "description": "Fee type\n* TRANSACTION_FEE_BUY - \n* TRANSACTION_FEE_SELL - \n* ANNUAL_AUM_BASED_FEE - ", "type": "string", "enum": [ "TRANSACTION_FEE_BUY", "TRANSACTION_FEE_SELL", "ANNUAL_AUM_BASED_FEE" ] }, "value_type": { "type": "string", "default": "ABSOLUTE", "description": "The type of fee value must be “ABSOLUTE”." }, "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] } }, "required": [ "type", "value_type", "cash_amount", "currency" ], "additionalProperties": false }, { "title": "Relative Fee", "type": "object", "properties": { "type": { "title": "Fee type", "description": "Fee type\n* TRANSACTION_FEE_BUY - \n* TRANSACTION_FEE_SELL - \n* ANNUAL_AUM_BASED_FEE - ", "type": "string", "enum": [ "TRANSACTION_FEE_BUY", "TRANSACTION_FEE_SELL", "ANNUAL_AUM_BASED_FEE" ] }, "value_type": { "type": "string", "default": "RELATIVE", "description": "The type of fee value must be “RELATIVE”." }, "bps": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "A fee is charged based on transaction amount and is represented in basis points." } ] } }, "required": [ "type", "value_type", "bps" ], "additionalProperties": false }, { "title": "Transaction Fee", "type": "object", "properties": { "type": { "title": "Fee type", "description": "Fee type\n* TRANSACTION_FEE_BUY - \n* TRANSACTION_FEE_SELL -", "type": "string", "enum": [ "TRANSACTION_FEE_BUY", "TRANSACTION_FEE_SELL" ] }, "transaction_fee_model_id": { "type": "string", "format": "uuid", "description": "The ID of the transaction fee model." } }, "required": [ "type", "transaction_fee_model_id" ], "additionalProperties": false } ] } }, "inducements": { "type": "array", "description": "Client inducements.", "items": { "title": "Inducement", "type": "object", "properties": { "value_type": { "type": "string", "default": "ABSOLUTE", "description": "The type of inducement value must be “ABSOLUTE”." }, "cash_amount": { "type": "string", "pattern": "^-?[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] } }, "required": [ "value_type", "cash_amount", "currency" ], "additionalProperties": false } } }, "required": [ "type", "order" ], "additionalProperties": false } ] }, "examples": { "business-nominal-sell-order-ex-ante-cost": { "summary": "Business - nominal sell order ex-ante cost report", "value": { "type": "ORDER_EX_ANTE_COST", "order": { "business_id": "d1a4be99-8bb6-4e78-b897-8168f6823ab5", "account_id": "c5034305-c441-4711-adbf-93cfbc13a695", "order_type": "MARKET", "side": "SELL", "instrument_id": "LU0274208692", "instrument_id_type": "ISIN", "currency": "EUR", "cash_amount": "1000.00" }, "fees": [ { "type": "TRANSACTION_FEE_BUY", "value_type": "ABSOLUTE", "cash_amount": "1.00", "currency": "EUR" }, { "type": "TRANSACTION_FEE_SELL", "transaction_fee_model_id": "eb5ba93f-5dfe-4bf1-84da-0caacc80c111" }, { "type": "ANNUAL_AUM_BASED_FEE", "value_type": "RELATIVE", "bps": "10" } ] } }, "business-unit-buy-order-ex-ante-cost": { "summary": "Business - unit buy order ex-ante cost report", "value": { "type": "ORDER_EX_ANTE_COST", "order": { "business_id": "d1a4be99-8bb6-4e78-b897-8168f6823ab5", "account_id": "c5034305-c441-4711-adbf-93cfbc13a695", "order_type": "MARKET", "side": "BUY", "instrument_id": "LU0274208692", "instrument_id_type": "ISIN", "currency": "EUR", "quantity": "15" }, "fees": [ { "type": "TRANSACTION_FEE_BUY", "transaction_fee_model_id": "eb5ba93f-5dfe-4bf1-84da-0caacc80c000" }, { "type": "TRANSACTION_FEE_SELL", "value_type": "ABSOLUTE", "cash_amount": "0.95", "currency": "EUR" }, { "type": "ANNUAL_AUM_BASED_FEE", "value_type": "RELATIVE", "bps": "37" } ], "inducements": [ { "value_type": "ABSOLUTE", "cash_amount": "0.10", "currency": "EUR" } ] } }, "nominal-sell-order-ex-ante-cost": { "summary": "Nominal sell order ex-ante cost report", "value": { "type": "ORDER_EX_ANTE_COST", "order": { "user_id": "d1a4be99-8bb6-4e78-b897-8168f6823ab5", "account_id": "c5034305-c441-4711-adbf-93cfbc13a695", "order_type": "MARKET", "side": "SELL", "instrument_id": "LU0274208692", "instrument_id_type": "ISIN", "currency": "EUR", "cash_amount": "1000.00" }, "fees": [ { "type": "TRANSACTION_FEE_BUY", "value_type": "ABSOLUTE", "cash_amount": "1.00", "currency": "EUR" }, { "type": "TRANSACTION_FEE_SELL", "transaction_fee_model_id": "eb5ba93f-5dfe-4bf1-84da-0caacc80c111" }, { "type": "ANNUAL_AUM_BASED_FEE", "value_type": "RELATIVE", "bps": "10" } ] } }, "savings-plan-ex-ante-cost": { "summary": "Savings plan ex-ante cost report", "value": { "type": "ORDER_EX_ANTE_COST_SAVINGS_PLAN", "order": { "user_id": "d1a4be99-8bb6-4e78-b897-8168f6823ab5", "account_id": "c5034305-c441-4711-adbf-93cfbc13a695", "cash_amount": "1000.00", "currency": "EUR", "side": "BUY", "instrument_id": "LU0274208692", "instrument_id_type": "ISIN", "order_type": "MARKET", "period": "WEEK", "interval": "2" }, "fees": [ { "type": "TRANSACTION_FEE_BUY", "value_type": "ABSOLUTE", "cash_amount": "0.80", "currency": "EUR" }, { "type": "TRANSACTION_FEE_SELL", "value_type": "ABSOLUTE", "cash_amount": "0.95", "currency": "EUR" }, { "type": "ANNUAL_AUM_BASED_FEE", "value_type": "RELATIVE", "bps": "37" } ], "inducements": [ { "value_type": "ABSOLUTE", "cash_amount": "0.10", "currency": "EUR" } ] } }, "unit-buy-order-ex-ante-cost": { "summary": "Unit buy order ex-ante cost report", "value": { "type": "ORDER_EX_ANTE_COST", "order": { "user_id": "d1a4be99-8bb6-4e78-b897-8168f6823ab5", "account_id": "c5034305-c441-4711-adbf-93cfbc13a695", "order_type": "MARKET", "side": "BUY", "instrument_id": "LU0274208692", "instrument_id_type": "ISIN", "currency": "EUR", "quantity": "15" }, "fees": [ { "type": "TRANSACTION_FEE_BUY", "transaction_fee_model_id": "eb5ba93f-5dfe-4bf1-84da-0caacc80c000" }, { "type": "TRANSACTION_FEE_SELL", "value_type": "ABSOLUTE", "cash_amount": "0.95", "currency": "EUR" }, { "type": "ANNUAL_AUM_BASED_FEE", "value_type": "RELATIVE", "bps": "37" } ], "inducements": [ { "value_type": "ABSOLUTE", "cash_amount": "0.10", "currency": "EUR" } ] } } } } } }, "responses": { "200": { "description": "Report", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Report - Order ex-ante cost", "oneOf": [ { "title": "User Report - Order ex-ante cost", "type": "object", "properties": { "id": { "title": "Report unique identifier.", "type": "string", "description": "Report unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "type": { "type": "string", "enum": [ "ORDER_EX_ANTE_COST", "ORDER_EX_ANTE_COST_SAVINGS_PLAN" ], "description": "The type of report must be “ORDER_EX_ANTE_COST” or “ORDER_EX_ANTE_COST_SAVINGS_PLAN”." }, "substituted_report_id": { "oneOf": [ { "type": "null" }, { "title": "Substituted Report unique identifier.", "type": "string", "description": "References report that has been replaced by this one.", "format": "uuid" } ] }, "data": { "title": "User Report Data - Order ex-ante cost", "type": "object", "description": "Contents of the order-ex-ante cost report for a user.", "properties": { "holding_period": { "type": "object", "description": "Holding period.", "properties": { "unit": { "type": "string", "description": "Unit of time. \n* YEAR - ", "enum": [ "YEAR" ], "default": "YEAR" }, "quantity": { "description": "Quantity of time units.", "type": "integer" } } }, "instrument": { "type": "object", "description": "Instrument details.", "properties": { "isin": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, "short_name": { "description": "Instrument short name.", "type": "string", "maxLength": 100 } } }, "venue": { "type": "object", "description": "Venue details.", "properties": { "name": { "description": "Venue name.", "type": "string", "maxLength": 100 } } }, "account": { "type": "object", "description": "Account details.", "properties": { "id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "account_number": { "type": "integer", "description": "The serial account number of the account in the account group.", "minimum": 1 } } }, "account_group": { "type": "object", "description": "Account group details.", "properties": { "id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "securities_account_number": { "type": "string", "description": "Securities account number.", "pattern": "^[0-9]{9}$" } } }, "user": { "type": "object", "description": "User details.", "properties": { "first_name": { "type": "string", "maxLength": 100, "minLength": 2, "description": "First name of the user." }, "last_name": { "type": "string", "maxLength": 100, "minLength": 2, "description": "Last name of the user." }, "salutation": { "type": "string", "description": "Salutation of the user used in reports and statements.\n* (empty string) - \n* SALUTATION_MALE - \n* SALUTATION_FEMALE - \n* SALUTATION_FEMALE_MARRIED - \n* SALUTATION_DIVERSE - ", "enum": [ "", "SALUTATION_MALE", "SALUTATION_FEMALE", "SALUTATION_FEMALE_MARRIED", "SALUTATION_DIVERSE" ], "default": "" }, "title": { "type": "string", "description": "Addressed user's title is used in reports and statements.\n* (empty string) - \n* DR - Doctor\n* PROF - Professor\n* PROF_DR - \n* DIPL_ING - Graduate engineer (Diplom-Ingenieur)\n* MAGISTER - ", "enum": [ "", "DR", "PROF", "PROF_DR", "DIPL_ING", "MAGISTER" ], "default": "" }, "address": { "type": "object", "description": "User residential address.", "properties": { "address_line1": { "type": "string", "description": "First line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Country code. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "pattern": "^[A-Z]{2}$" }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } } } } }, "order": { "type": "object", "description": "Order details.", "properties": { "user_id": { "type": "string", "format": "uuid", "description": "The ID of the user." }, "account_id": { "type": "string", "format": "uuid", "description": "The ID of the account that owns the order." }, "cash_amount": { "allOf": [ { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, { "description": "Cash amount for a nominal order." } ] }, "currency": { "allOf": [ { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, { "description": "The currency for the order." } ] }, "side": { "type": "string", "description": "Side of the order.\n* BUY - \n* SELL - ", "enum": [ "BUY", "SELL" ] }, "instrument_id": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, "instrument_id_type": { "description": "The type of the ID used in the request.\n* ISIN - ", "enum": [ "ISIN" ], "default": "ISIN", "type": "string" }, "order_type": { "type": "string", "description": "Order type.\n* MARKET - \n* LIMIT - \n* STOP - ", "enum": [ "MARKET", "LIMIT", "STOP" ] }, "quantity": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "Quantity of securities for the order." } ] }, "limit_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The limit price for orders of the type 'limit'." } ] }, "stop_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The stop price for orders of the type 'stop'." } ] }, "price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The estimated price for the order. In case of LIMIT or STOP order provided LIMIT/STOP price will be used." } ] } } }, "return_impact": { "type": "object", "description": "Return impact.", "properties": { "year_one": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "year_two": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "year_three": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false } } }, "total_cost": { "title": "Order ex-ante aggregated cost", "type": "object", "description": "Aggregated totals of product costs, service costs and third party payments.", "properties": { "product": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "service": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "third_party": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "total": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false } }, "additionalProperties": false }, "product_cost": { "title": "Order ex-ante product cost", "type": "object", "description": "All costs and associated charges related to the financial instrument.", "properties": { "one_off": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "ongoing": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "transaction": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "incidental": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "total": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false } }, "additionalProperties": false }, "service_cost": { "title": "Order ex-ante service cost", "type": "object", "description": "All costs and associated charges related to the investment service(s) and/or ancillary services.", "properties": { "one_off": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "ongoing": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "transaction": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "ancillary": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "incidental": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "total": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false } }, "additionalProperties": false }, "third_party_payments": { "type": "object", "description": "Third-party payments associated with the investment service.", "properties": { "total": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "received_by_client": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "received_by_upvest": { "allOf": [ { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, { "description": "Third-party payments received by Upvest. Only returned when Upvest holds the investment-firm licence for the account (TOL). Omitted for tenants operating on their own licence (BYOL), where Upvest's share is not disclosed. It stays part of `total` either way, so `total` is not always the sum of the returned properties." } ] } }, "additionalProperties": false } }, "required": [ "user" ], "additionalProperties": false } }, "required": [ "id", "user_id", "created_at", "type", "substituted_report_id" ], "additionalProperties": false }, { "title": "Business Report - Order ex-ante cost", "type": "object", "properties": { "id": { "title": "Report unique identifier.", "type": "string", "description": "Report unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "business_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "type": { "title": "Business report type", "type": "string", "enum": [ "ORDER_EX_ANTE_COST" ], "description": "The type of report must be “ORDER_EX_ANTE_COST”. Savings plan ex-ante reports are not supported for business entities." }, "substituted_report_id": { "oneOf": [ { "type": "null" }, { "title": "Substituted Report unique identifier.", "type": "string", "description": "References report that has been replaced by this one.", "format": "uuid" } ] }, "data": { "title": "Business Report Data - Order ex-ante cost", "type": "object", "description": "Contents of the order ex-ante cost report for a business.", "properties": { "holding_period": { "type": "object", "description": "Holding period.", "properties": { "unit": { "type": "string", "description": "Unit of time. \n* YEAR - ", "enum": [ "YEAR" ], "default": "YEAR" }, "quantity": { "description": "Quantity of time units.", "type": "integer" } } }, "instrument": { "type": "object", "description": "Instrument details.", "properties": { "isin": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, "short_name": { "description": "Instrument short name.", "type": "string", "maxLength": 100 } } }, "venue": { "type": "object", "description": "Venue details.", "properties": { "name": { "description": "Venue name.", "type": "string", "maxLength": 100 } } }, "account": { "type": "object", "description": "Account details.", "properties": { "id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "account_number": { "type": "integer", "description": "The serial account number of the account in the account group.", "minimum": 1 } } }, "account_group": { "type": "object", "description": "Account group details.", "properties": { "id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "securities_account_number": { "type": "string", "description": "Securities account number.", "pattern": "^[0-9]{9}$" } } }, "business": { "type": "object", "description": "Business details.", "properties": { "company_name": { "type": "string", "description": "Name of the company." }, "address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] } } }, "order": { "type": "object", "description": "Order details.", "properties": { "business_id": { "type": "string", "format": "uuid", "description": "The ID of the business." }, "account_id": { "type": "string", "format": "uuid", "description": "The ID of the account that owns the order." }, "cash_amount": { "allOf": [ { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, { "description": "Cash amount for a nominal order." } ] }, "currency": { "allOf": [ { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, { "description": "The currency for the order." } ] }, "side": { "type": "string", "description": "Side of the order.\n* BUY - \n* SELL - ", "enum": [ "BUY", "SELL" ] }, "instrument_id": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, "instrument_id_type": { "description": "The type of the ID used in the request.\n* ISIN - ", "enum": [ "ISIN" ], "default": "ISIN", "type": "string" }, "order_type": { "type": "string", "description": "Order type.\n* MARKET - \n* LIMIT - \n* STOP - ", "enum": [ "MARKET", "LIMIT", "STOP" ] }, "quantity": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "Quantity of securities for the order." } ] }, "limit_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The limit price for orders of the type 'limit'." } ] }, "stop_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The stop price for orders of the type STOP." } ] }, "price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The estimated price for the order. In case of LIMIT or STOP order provided LIMIT/STOP price will be used." } ] } } }, "return_impact": { "type": "object", "description": "Return impact.", "properties": { "year_one": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "year_two": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "year_three": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false } } }, "total_cost": { "title": "Order ex-ante aggregated cost", "type": "object", "description": "Aggregated totals of product costs, service costs and third party payments.", "properties": { "product": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "service": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "third_party": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "total": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false } }, "additionalProperties": false }, "product_cost": { "title": "Order ex-ante product cost", "type": "object", "description": "All costs and associated charges related to the financial instrument.", "properties": { "one_off": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "ongoing": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "transaction": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "incidental": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "total": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false } }, "additionalProperties": false }, "service_cost": { "title": "Order ex-ante service cost", "type": "object", "description": "All costs and associated charges related to the investment service(s) and/or ancillary services.", "properties": { "one_off": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "ongoing": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "transaction": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "ancillary": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "incidental": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "total": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false } }, "additionalProperties": false }, "third_party_payments": { "type": "object", "description": "Third party payments associated with the investment service.", "properties": { "total": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "received_by_client": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "received_by_upvest": { "allOf": [ { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, { "description": "Third-party payments received by Upvest. Only returned when Upvest holds the investment-firm licence for the account (TOL). Omitted for tenants operating on their own licence (BYOL), where Upvest's share is not disclosed. It stays part of `total` either way, so `total` is not always the sum of the returned properties." } ] } }, "additionalProperties": false } }, "required": [ "business" ], "additionalProperties": false } }, "required": [ "id", "business_id", "created_at", "type", "substituted_report_id" ], "additionalProperties": false } ] }, "examples": { "business-order-ex-ante-cost": { "summary": "Business order ex-ante cost report", "value": { "id": "b96b1ee7-d491-43eb-b5e4-4833af9c9c2f", "created_at": "2023-08-24T14:15:22Z", "business_id": "d1a4be99-8bb6-4e78-b897-8168f6823ab5", "type": "ORDER_EX_ANTE_COST", "substituted_report_id": null, "data": { "account": { "id": "c5034305-c441-4711-adbf-93cfbc13a695", "account_number": 1 }, "account_group": { "id": "9d95820d-4333-46b6-98de-04ab7512e76f", "securities_account_number": "123456789" }, "business": { "company_name": "Acme Corporation", "address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "country": "DE" } }, "instrument": { "isin": "LU0274208692", "short_name": "XTR.MSCI WORLD SWAP 1C" }, "venue": { "name": "Tradegate" }, "order": { "business_id": "d1a4be99-8bb6-4e78-b897-8168f6823ab5", "instrument_id": "LU0274208692", "instrument_id_type": "ISIN", "account_id": "c5034305-c441-4711-adbf-93cfbc13a695", "order_type": "MARKET", "side": "BUY", "quantity": "15", "cash_amount": "1220.85", "currency": "EUR", "price": "81.39" }, "holding_period": { "unit": "YEAR", "quantity": 3 }, "total_cost": { "product": { "cash_amount": "17.48", "currency": "EUR", "as_percentage": "1.43" }, "service": { "cash_amount": "6.88", "currency": "EUR", "as_percentage": "0.56" }, "third_party": { "cash_amount": "0.70", "currency": "EUR", "as_percentage": "0.06" }, "total": { "cash_amount": "25.06", "currency": "EUR", "as_percentage": "2.05" } }, "product_cost": { "one_off": { "cash_amount": "0.20", "currency": "EUR", "as_percentage": "0.02" }, "ongoing": { "cash_amount": "16.48", "currency": "EUR", "as_percentage": "1.35" }, "transaction": { "cash_amount": "0.80", "currency": "EUR", "as_percentage": "0.07" }, "incidental": { "cash_amount": "0.00", "currency": "EUR", "as_percentage": "0.00" }, "total": { "cash_amount": "17.48", "currency": "EUR", "as_percentage": "1.43" } }, "service_cost": { "one_off": { "cash_amount": "0.49", "currency": "EUR", "as_percentage": "0.04" }, "ongoing": { "cash_amount": "4.39", "currency": "EUR", "as_percentage": "0.36" }, "transaction": { "cash_amount": "2.00", "currency": "EUR", "as_percentage": "0.16" }, "ancillary": { "cash_amount": "0.00", "currency": "EUR", "as_percentage": "0.00" }, "incidental": { "cash_amount": "0.00", "currency": "EUR", "as_percentage": "0.00" }, "total": { "cash_amount": "6.88", "currency": "EUR", "as_percentage": "0.56" } }, "third_party_payments": { "total": { "cash_amount": "0.70", "currency": "EUR", "as_percentage": "0.06" }, "received_by_client": { "cash_amount": "0.35", "currency": "EUR", "as_percentage": "0.03" }, "received_by_upvest": { "cash_amount": "0.35", "currency": "EUR", "as_percentage": "0.03" } }, "return_impact": { "year_one": { "cash_amount": "9.05", "currency": "EUR", "as_percentage": "0.74" }, "year_two": { "cash_amount": "6.96", "currency": "EUR", "as_percentage": "0.57" }, "year_three": { "cash_amount": "8.36", "currency": "EUR", "as_percentage": "0.68" } } } } }, "order-ex-ante-cost": { "summary": "Order ex-ante cost report", "value": { "id": "b96b1ee7-d491-43eb-b5e4-4833af9c9c2f", "created_at": "2023-08-24T14:15:22Z", "user_id": "d1a4be99-8bb6-4e78-b897-8168f6823ab5", "type": "ORDER_EX_ANTE_COST", "substituted_report_id": null, "data": { "account": { "id": "c5034305-c441-4711-adbf-93cfbc13a695", "account_number": 1 }, "account_group": { "id": "9d95820d-4333-46b6-98de-04ab7512e76f", "securities_account_number": "123456789" }, "user": { "salutation": "SALUTATION_MALE", "title": "DR", "first_name": "Karl", "last_name": "Schmidt", "address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "country": "DE" } }, "instrument": { "isin": "LU0274208692", "short_name": "XTR.MSCI WORLD SWAP 1C" }, "venue": { "name": "Tradegate" }, "order": { "user_id": "d1a4be99-8bb6-4e78-b897-8168f6823ab5", "instrument_id": "LU0274208692", "instrument_id_type": "ISIN", "account_id": "c5034305-c441-4711-adbf-93cfbc13a695", "order_type": "MARKET", "side": "BUY", "quantity": "15", "cash_amount": "1220.85", "currency": "EUR", "price": "81.39" }, "holding_period": { "unit": "YEAR", "quantity": 3 }, "total_cost": { "product": { "cash_amount": "17.48", "currency": "EUR", "as_percentage": "1.43" }, "service": { "cash_amount": "6.88", "currency": "EUR", "as_percentage": "0.56" }, "third_party": { "cash_amount": "0.70", "currency": "EUR", "as_percentage": "0.06" }, "total": { "cash_amount": "25.06", "currency": "EUR", "as_percentage": "2.05" } }, "product_cost": { "one_off": { "cash_amount": "0.20", "currency": "EUR", "as_percentage": "0.02" }, "ongoing": { "cash_amount": "16.48", "currency": "EUR", "as_percentage": "1.35" }, "transaction": { "cash_amount": "0.80", "currency": "EUR", "as_percentage": "0.07" }, "incidental": { "cash_amount": "0.00", "currency": "EUR", "as_percentage": "0.00" }, "total": { "cash_amount": "17.48", "currency": "EUR", "as_percentage": "1.43" } }, "service_cost": { "one_off": { "cash_amount": "0.49", "currency": "EUR", "as_percentage": "0.04" }, "ongoing": { "cash_amount": "4.39", "currency": "EUR", "as_percentage": "0.36" }, "transaction": { "cash_amount": "2.00", "currency": "EUR", "as_percentage": "0.16" }, "ancillary": { "cash_amount": "0.00", "currency": "EUR", "as_percentage": "0.00" }, "incidental": { "cash_amount": "0.00", "currency": "EUR", "as_percentage": "0.00" }, "total": { "cash_amount": "6.88", "currency": "EUR", "as_percentage": "0.56" } }, "third_party_payments": { "total": { "cash_amount": "0.70", "currency": "EUR", "as_percentage": "0.06" }, "received_by_client": { "cash_amount": "0.35", "currency": "EUR", "as_percentage": "0.03" }, "received_by_upvest": { "cash_amount": "0.35", "currency": "EUR", "as_percentage": "0.03" } }, "return_impact": { "year_one": { "cash_amount": "9.05", "currency": "EUR", "as_percentage": "0.74" }, "year_two": { "cash_amount": "6.96", "currency": "EUR", "as_percentage": "0.57" }, "year_three": { "cash_amount": "8.36", "currency": "EUR", "as_percentage": "0.68" } } } } } } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/reports/{report_id}": { "parameters": [ { "name": "report_id", "in": "path", "required": true, "description": "The unique identifier of the report. Universally Unique Identifier (UUID).", "schema": { "title": "Report unique identifier.", "type": "string", "description": "Report unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_report", "summary": "Retrieve a report", "description": "Retrieve a report for either a natural person or a business entity.", "tags": [ "Reports" ], "security": [ { "oauth-client-credentials": [ "reports:read", "reports:admin" ] } ], "parameters": [ { "name": "accept", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "application/json", "application/pdf" ], "description": "Report format", "default": "application/json" }, "description": "Report format" } ], "responses": { "200": { "description": "Report", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Report", "anyOf": [ { "title": "User Report", "type": "object", "properties": { "id": { "title": "Report unique identifier.", "type": "string", "description": "Report unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "type": { "title": "Report type", "description": "Report type\n* ACCOUNT_CLOSING - Securities account closure\n* ACCOUNT_OPENING - Securities account opening\n* AD_HOC_ACCOUNT_STATEMENT - Ad hoc account statement\n* ANNUAL_INCOME_STATEMENT - Annual tax income statement (\"Erträgnisaufstellung\")\n* ANNUAL_TAX_STATEMENT - Annual tax reporting\n* BANK_ACCOUNT_CONNECTED - Connect reference bank account\n* BUY_ORDER - Buy order\n* CANCELLED_ORDER - Cancelled buy or sell order (not yet executed, user cancels or trading venue cancelled)\n* CORPORATE_ACTION_CASH_TRANSACTION - cash transaction document (after corporate action)\n* CORPORATE_ACTION_SECURITY_TRANSACTION - security transaction document (after corporate action)\n* DIRECT_DEBIT_MANDATE - Creation of SEPA direct debit mandate\n* EX_POST_COST - Ex-post cost report\n* FEE_COLLECTION - Intake of service fees\n* FRENCH_IFU - French tax statement (Imprimé fiscal unique)\n* GENERIC_COMMUNICATION - Generic communication\n* INCOME_DISTRIBUTION - Income distribution report\n* LOSS_THRESHOLD - Notification that a holding has depreciated by 10%, or a multiple thereof, against its purchase value\n* MONTHLY_BILLING_STATEMENT - Monthly billing activities statement\n* QUARTERLY_ACCOUNT_STATEMENT - Quarterly account statement\n* REVOKED_ORDER - Revoked buy or sell order (\"Storno\")\n* SECURITIES_TRANSFER_INCOMING - Securities are transferred in\n* SECURITIES_TRANSFER_OUTGOING - Securities are being transferred out\n* SELL_ORDER - Sell order\n* TAX_CONSOLIDATED_CERTIFICATE_UK - UK Consolidated Tax Certificate\n* TAX_PAYMENT - Tax payment document\n* TAX_PREPAYMENT_DE - German tax prepayment (Vorabpauschale)\n* TAX_PREPAYMENT_DE_CANCELLATION - German tax prepayment (Vorabpauschale) cancellation\n* TAX_REFUND - Tax refund document (after tax optimization)", "type": "string", "enum": [ "ACCOUNT_CLOSING", "ACCOUNT_OPENING", "AD_HOC_ACCOUNT_STATEMENT", "ANNUAL_INCOME_STATEMENT", "ANNUAL_TAX_STATEMENT", "BANK_ACCOUNT_CONNECTED", "BUY_ORDER", "CANCELLED_ORDER", "CORPORATE_ACTION_CASH_TRANSACTION", "CORPORATE_ACTION_SECURITY_TRANSACTION", "DIRECT_DEBIT_MANDATE", "EX_POST_COST", "FEE_COLLECTION", "FRENCH_IFU", "GENERIC_COMMUNICATION", "INCOME_DISTRIBUTION", "LOSS_THRESHOLD", "MONTHLY_BILLING_STATEMENT", "QUARTERLY_ACCOUNT_STATEMENT", "REVOKED_ORDER", "SECURITIES_TRANSFER_INCOMING", "SECURITIES_TRANSFER_OUTGOING", "SELL_ORDER", "TAX_CONSOLIDATED_CERTIFICATE_UK", "TAX_PAYMENT", "TAX_PREPAYMENT_DE", "TAX_PREPAYMENT_DE_CANCELLATION", "TAX_REFUND" ] }, "substituted_report_id": { "oneOf": [ { "type": "null" }, { "title": "Substituted Report unique identifier.", "type": "string", "description": "References report that has been replaced by this one.", "format": "uuid" } ] }, "data": { "title": "Report Data", "type": "object", "description": "Contents of the report.", "properties": { "account": { "type": "object", "title": "Account.", "description": "Account information.", "properties": { "id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" } } }, "references": { "type": "array", "title": "References.", "items": { "title": "Report reference data", "type": "object", "description": "Reference data for a report", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "title": "Report reference type", "description": "Report reference type\n* CORPORATE_ACTION_TRANSACTION_ID - Corporate action transaction identifier\n* ACCOUNT_GROUP_ID - Account group identifier\n* ACCOUNT_ID - Account identifier\n* ORDER_ID - Order identifier", "type": "string", "enum": [ "CORPORATE_ACTION_TRANSACTION_ID", "ACCOUNT_GROUP_ID", "ACCOUNT_ID", "ORDER_ID" ] } } } } } } }, "required": [ "id", "user_id", "created_at", "type", "substituted_report_id" ], "additionalProperties": false }, { "title": "Business Report", "type": "object", "properties": { "id": { "title": "Report unique identifier.", "type": "string", "description": "Report unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "business_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "type": { "title": "Report type", "description": "Report type\n* ACCOUNT_CLOSING - Securities account closure\n* ACCOUNT_OPENING - Securities account opening\n* AD_HOC_ACCOUNT_STATEMENT - Ad hoc account statement\n* ANNUAL_INCOME_STATEMENT - Annual tax income statement (\"Erträgnisaufstellung\")\n* ANNUAL_TAX_STATEMENT - Annual tax reporting\n* BANK_ACCOUNT_CONNECTED - Connect reference bank account\n* BUY_ORDER - Buy order\n* CANCELLED_ORDER - Cancelled buy or sell order (not yet executed, user cancels or trading venue cancelled)\n* CORPORATE_ACTION_CASH_TRANSACTION - cash transaction document (after corporate action)\n* CORPORATE_ACTION_SECURITY_TRANSACTION - security transaction document (after corporate action)\n* DIRECT_DEBIT_MANDATE - Creation of SEPA direct debit mandate\n* EX_POST_COST - Ex-post cost report\n* FEE_COLLECTION - Intake of service fees\n* FRENCH_IFU - French tax statement (Imprimé fiscal unique)\n* GENERIC_COMMUNICATION - Generic communication\n* INCOME_DISTRIBUTION - Income distribution report\n* LOSS_THRESHOLD - Notification that a holding has depreciated by 10%, or a multiple thereof, against its purchase value\n* MONTHLY_BILLING_STATEMENT - Monthly billing activities statement\n* QUARTERLY_ACCOUNT_STATEMENT - Quarterly account statement\n* REVOKED_ORDER - Revoked buy or sell order (\"Storno\")\n* SECURITIES_TRANSFER_INCOMING - Securities are transferred in\n* SECURITIES_TRANSFER_OUTGOING - Securities are being transferred out\n* SELL_ORDER - Sell order\n* TAX_CONSOLIDATED_CERTIFICATE_UK - UK Consolidated Tax Certificate\n* TAX_PAYMENT - Tax payment document\n* TAX_PREPAYMENT_DE - German tax prepayment (Vorabpauschale)\n* TAX_PREPAYMENT_DE_CANCELLATION - German tax prepayment (Vorabpauschale) cancellation\n* TAX_REFUND - Tax refund document (after tax optimization)", "type": "string", "enum": [ "ACCOUNT_CLOSING", "ACCOUNT_OPENING", "AD_HOC_ACCOUNT_STATEMENT", "ANNUAL_INCOME_STATEMENT", "ANNUAL_TAX_STATEMENT", "BANK_ACCOUNT_CONNECTED", "BUY_ORDER", "CANCELLED_ORDER", "CORPORATE_ACTION_CASH_TRANSACTION", "CORPORATE_ACTION_SECURITY_TRANSACTION", "DIRECT_DEBIT_MANDATE", "EX_POST_COST", "FEE_COLLECTION", "FRENCH_IFU", "GENERIC_COMMUNICATION", "INCOME_DISTRIBUTION", "LOSS_THRESHOLD", "MONTHLY_BILLING_STATEMENT", "QUARTERLY_ACCOUNT_STATEMENT", "REVOKED_ORDER", "SECURITIES_TRANSFER_INCOMING", "SECURITIES_TRANSFER_OUTGOING", "SELL_ORDER", "TAX_CONSOLIDATED_CERTIFICATE_UK", "TAX_PAYMENT", "TAX_PREPAYMENT_DE", "TAX_PREPAYMENT_DE_CANCELLATION", "TAX_REFUND" ] }, "substituted_report_id": { "oneOf": [ { "type": "null" }, { "title": "Substituted Report unique identifier.", "type": "string", "description": "References report that has been replaced by this one.", "format": "uuid" } ] }, "data": { "title": "Report Data", "type": "object", "description": "Contents of the report.", "properties": { "account": { "type": "object", "title": "Account.", "description": "Account information.", "properties": { "id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" } } }, "references": { "type": "array", "title": "References.", "items": { "title": "Report reference data", "type": "object", "description": "Reference data for a report", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "title": "Report reference type", "description": "Report reference type\n* CORPORATE_ACTION_TRANSACTION_ID - Corporate action transaction identifier\n* ACCOUNT_GROUP_ID - Account group identifier\n* ACCOUNT_ID - Account identifier\n* ORDER_ID - Order identifier", "type": "string", "enum": [ "CORPORATE_ACTION_TRANSACTION_ID", "ACCOUNT_GROUP_ID", "ACCOUNT_ID", "ORDER_ID" ] } } } } } } }, "required": [ "id", "business_id", "created_at", "type", "substituted_report_id" ], "additionalProperties": false }, { "title": "User Report - Order ex-ante cost", "type": "object", "properties": { "id": { "title": "Report unique identifier.", "type": "string", "description": "Report unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "type": { "type": "string", "enum": [ "ORDER_EX_ANTE_COST", "ORDER_EX_ANTE_COST_SAVINGS_PLAN" ], "description": "The type of report must be “ORDER_EX_ANTE_COST” or “ORDER_EX_ANTE_COST_SAVINGS_PLAN”." }, "substituted_report_id": { "oneOf": [ { "type": "null" }, { "title": "Substituted Report unique identifier.", "type": "string", "description": "References report that has been replaced by this one.", "format": "uuid" } ] }, "data": { "title": "User Report Data - Order ex-ante cost", "type": "object", "description": "Contents of the order-ex-ante cost report for a user.", "properties": { "holding_period": { "type": "object", "description": "Holding period.", "properties": { "unit": { "type": "string", "description": "Unit of time. \n* YEAR - ", "enum": [ "YEAR" ], "default": "YEAR" }, "quantity": { "description": "Quantity of time units.", "type": "integer" } } }, "instrument": { "type": "object", "description": "Instrument details.", "properties": { "isin": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, "short_name": { "description": "Instrument short name.", "type": "string", "maxLength": 100 } } }, "venue": { "type": "object", "description": "Venue details.", "properties": { "name": { "description": "Venue name.", "type": "string", "maxLength": 100 } } }, "account": { "type": "object", "description": "Account details.", "properties": { "id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "account_number": { "type": "integer", "description": "The serial account number of the account in the account group.", "minimum": 1 } } }, "account_group": { "type": "object", "description": "Account group details.", "properties": { "id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "securities_account_number": { "type": "string", "description": "Securities account number.", "pattern": "^[0-9]{9}$" } } }, "user": { "type": "object", "description": "User details.", "properties": { "first_name": { "type": "string", "maxLength": 100, "minLength": 2, "description": "First name of the user." }, "last_name": { "type": "string", "maxLength": 100, "minLength": 2, "description": "Last name of the user." }, "salutation": { "type": "string", "description": "Salutation of the user used in reports and statements.\n* (empty string) - \n* SALUTATION_MALE - \n* SALUTATION_FEMALE - \n* SALUTATION_FEMALE_MARRIED - \n* SALUTATION_DIVERSE - ", "enum": [ "", "SALUTATION_MALE", "SALUTATION_FEMALE", "SALUTATION_FEMALE_MARRIED", "SALUTATION_DIVERSE" ], "default": "" }, "title": { "type": "string", "description": "Addressed user's title is used in reports and statements.\n* (empty string) - \n* DR - Doctor\n* PROF - Professor\n* PROF_DR - \n* DIPL_ING - Graduate engineer (Diplom-Ingenieur)\n* MAGISTER - ", "enum": [ "", "DR", "PROF", "PROF_DR", "DIPL_ING", "MAGISTER" ], "default": "" }, "address": { "type": "object", "description": "User residential address.", "properties": { "address_line1": { "type": "string", "description": "First line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Country code. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "pattern": "^[A-Z]{2}$" }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } } } } }, "order": { "type": "object", "description": "Order details.", "properties": { "user_id": { "type": "string", "format": "uuid", "description": "The ID of the user." }, "account_id": { "type": "string", "format": "uuid", "description": "The ID of the account that owns the order." }, "cash_amount": { "allOf": [ { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, { "description": "Cash amount for a nominal order." } ] }, "currency": { "allOf": [ { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, { "description": "The currency for the order." } ] }, "side": { "type": "string", "description": "Side of the order.\n* BUY - \n* SELL - ", "enum": [ "BUY", "SELL" ] }, "instrument_id": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, "instrument_id_type": { "description": "The type of the ID used in the request.\n* ISIN - ", "enum": [ "ISIN" ], "default": "ISIN", "type": "string" }, "order_type": { "type": "string", "description": "Order type.\n* MARKET - \n* LIMIT - \n* STOP - ", "enum": [ "MARKET", "LIMIT", "STOP" ] }, "quantity": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "Quantity of securities for the order." } ] }, "limit_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The limit price for orders of the type 'limit'." } ] }, "stop_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The stop price for orders of the type 'stop'." } ] }, "price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The estimated price for the order. In case of LIMIT or STOP order provided LIMIT/STOP price will be used." } ] } } }, "return_impact": { "type": "object", "description": "Return impact.", "properties": { "year_one": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "year_two": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "year_three": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false } } }, "total_cost": { "title": "Order ex-ante aggregated cost", "type": "object", "description": "Aggregated totals of product costs, service costs and third party payments.", "properties": { "product": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "service": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "third_party": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "total": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false } }, "additionalProperties": false }, "product_cost": { "title": "Order ex-ante product cost", "type": "object", "description": "All costs and associated charges related to the financial instrument.", "properties": { "one_off": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "ongoing": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "transaction": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "incidental": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "total": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false } }, "additionalProperties": false }, "service_cost": { "title": "Order ex-ante service cost", "type": "object", "description": "All costs and associated charges related to the investment service(s) and/or ancillary services.", "properties": { "one_off": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "ongoing": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "transaction": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "ancillary": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "incidental": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "total": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false } }, "additionalProperties": false }, "third_party_payments": { "type": "object", "description": "Third-party payments associated with the investment service.", "properties": { "total": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "received_by_client": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "received_by_upvest": { "allOf": [ { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, { "description": "Third-party payments received by Upvest. Only returned when Upvest holds the investment-firm licence for the account (TOL). Omitted for tenants operating on their own licence (BYOL), where Upvest's share is not disclosed. It stays part of `total` either way, so `total` is not always the sum of the returned properties." } ] } }, "additionalProperties": false } }, "required": [ "user" ], "additionalProperties": false } }, "required": [ "id", "user_id", "created_at", "type", "substituted_report_id" ], "additionalProperties": false }, { "title": "Business Report - Order ex-ante cost", "type": "object", "properties": { "id": { "title": "Report unique identifier.", "type": "string", "description": "Report unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "business_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "type": { "title": "Business report type", "type": "string", "enum": [ "ORDER_EX_ANTE_COST" ], "description": "The type of report must be “ORDER_EX_ANTE_COST”. Savings plan ex-ante reports are not supported for business entities." }, "substituted_report_id": { "oneOf": [ { "type": "null" }, { "title": "Substituted Report unique identifier.", "type": "string", "description": "References report that has been replaced by this one.", "format": "uuid" } ] }, "data": { "title": "Business Report Data - Order ex-ante cost", "type": "object", "description": "Contents of the order ex-ante cost report for a business.", "properties": { "holding_period": { "type": "object", "description": "Holding period.", "properties": { "unit": { "type": "string", "description": "Unit of time. \n* YEAR - ", "enum": [ "YEAR" ], "default": "YEAR" }, "quantity": { "description": "Quantity of time units.", "type": "integer" } } }, "instrument": { "type": "object", "description": "Instrument details.", "properties": { "isin": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, "short_name": { "description": "Instrument short name.", "type": "string", "maxLength": 100 } } }, "venue": { "type": "object", "description": "Venue details.", "properties": { "name": { "description": "Venue name.", "type": "string", "maxLength": 100 } } }, "account": { "type": "object", "description": "Account details.", "properties": { "id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "account_number": { "type": "integer", "description": "The serial account number of the account in the account group.", "minimum": 1 } } }, "account_group": { "type": "object", "description": "Account group details.", "properties": { "id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "securities_account_number": { "type": "string", "description": "Securities account number.", "pattern": "^[0-9]{9}$" } } }, "business": { "type": "object", "description": "Business details.", "properties": { "company_name": { "type": "string", "description": "Name of the company." }, "address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] } } }, "order": { "type": "object", "description": "Order details.", "properties": { "business_id": { "type": "string", "format": "uuid", "description": "The ID of the business." }, "account_id": { "type": "string", "format": "uuid", "description": "The ID of the account that owns the order." }, "cash_amount": { "allOf": [ { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, { "description": "Cash amount for a nominal order." } ] }, "currency": { "allOf": [ { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, { "description": "The currency for the order." } ] }, "side": { "type": "string", "description": "Side of the order.\n* BUY - \n* SELL - ", "enum": [ "BUY", "SELL" ] }, "instrument_id": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, "instrument_id_type": { "description": "The type of the ID used in the request.\n* ISIN - ", "enum": [ "ISIN" ], "default": "ISIN", "type": "string" }, "order_type": { "type": "string", "description": "Order type.\n* MARKET - \n* LIMIT - \n* STOP - ", "enum": [ "MARKET", "LIMIT", "STOP" ] }, "quantity": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "Quantity of securities for the order." } ] }, "limit_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The limit price for orders of the type 'limit'." } ] }, "stop_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The stop price for orders of the type STOP." } ] }, "price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The estimated price for the order. In case of LIMIT or STOP order provided LIMIT/STOP price will be used." } ] } } }, "return_impact": { "type": "object", "description": "Return impact.", "properties": { "year_one": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "year_two": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "year_three": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false } } }, "total_cost": { "title": "Order ex-ante aggregated cost", "type": "object", "description": "Aggregated totals of product costs, service costs and third party payments.", "properties": { "product": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "service": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "third_party": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "total": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false } }, "additionalProperties": false }, "product_cost": { "title": "Order ex-ante product cost", "type": "object", "description": "All costs and associated charges related to the financial instrument.", "properties": { "one_off": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "ongoing": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "transaction": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "incidental": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "total": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false } }, "additionalProperties": false }, "service_cost": { "title": "Order ex-ante service cost", "type": "object", "description": "All costs and associated charges related to the investment service(s) and/or ancillary services.", "properties": { "one_off": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "ongoing": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "transaction": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "ancillary": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "incidental": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "total": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false } }, "additionalProperties": false }, "third_party_payments": { "type": "object", "description": "Third party payments associated with the investment service.", "properties": { "total": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "received_by_client": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "received_by_upvest": { "allOf": [ { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, { "description": "Third-party payments received by Upvest. Only returned when Upvest holds the investment-firm licence for the account (TOL). Omitted for tenants operating on their own licence (BYOL), where Upvest's share is not disclosed. It stays part of `total` either way, so `total` is not always the sum of the returned properties." } ] } }, "additionalProperties": false } }, "required": [ "business" ], "additionalProperties": false } }, "required": [ "id", "business_id", "created_at", "type", "substituted_report_id" ], "additionalProperties": false } ] }, "examples": { "business-order-ex-ante-cost": { "summary": "Business order ex-ante cost report", "value": { "id": "b96b1ee7-d491-43eb-b5e4-4833af9c9c2f", "created_at": "2023-08-24T14:15:22Z", "business_id": "d1a4be99-8bb6-4e78-b897-8168f6823ab5", "type": "ORDER_EX_ANTE_COST", "substituted_report_id": null, "data": { "account": { "id": "c5034305-c441-4711-adbf-93cfbc13a695", "account_number": 1 }, "account_group": { "id": "9d95820d-4333-46b6-98de-04ab7512e76f", "securities_account_number": "123456789" }, "business": { "company_name": "Acme Corporation", "address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "country": "DE" } }, "instrument": { "isin": "LU0274208692", "short_name": "XTR.MSCI WORLD SWAP 1C" }, "venue": { "name": "Tradegate" }, "order": { "business_id": "d1a4be99-8bb6-4e78-b897-8168f6823ab5", "instrument_id": "LU0274208692", "instrument_id_type": "ISIN", "account_id": "c5034305-c441-4711-adbf-93cfbc13a695", "order_type": "MARKET", "side": "BUY", "quantity": "15", "cash_amount": "1220.85", "currency": "EUR", "price": "81.39" }, "holding_period": { "unit": "YEAR", "quantity": 3 }, "total_cost": { "product": { "cash_amount": "17.48", "currency": "EUR", "as_percentage": "1.43" }, "service": { "cash_amount": "6.88", "currency": "EUR", "as_percentage": "0.56" }, "third_party": { "cash_amount": "0.70", "currency": "EUR", "as_percentage": "0.06" }, "total": { "cash_amount": "25.06", "currency": "EUR", "as_percentage": "2.05" } }, "product_cost": { "one_off": { "cash_amount": "0.20", "currency": "EUR", "as_percentage": "0.02" }, "ongoing": { "cash_amount": "16.48", "currency": "EUR", "as_percentage": "1.35" }, "transaction": { "cash_amount": "0.80", "currency": "EUR", "as_percentage": "0.07" }, "incidental": { "cash_amount": "0.00", "currency": "EUR", "as_percentage": "0.00" }, "total": { "cash_amount": "17.48", "currency": "EUR", "as_percentage": "1.43" } }, "service_cost": { "one_off": { "cash_amount": "0.49", "currency": "EUR", "as_percentage": "0.04" }, "ongoing": { "cash_amount": "4.39", "currency": "EUR", "as_percentage": "0.36" }, "transaction": { "cash_amount": "2.00", "currency": "EUR", "as_percentage": "0.16" }, "ancillary": { "cash_amount": "0.00", "currency": "EUR", "as_percentage": "0.00" }, "incidental": { "cash_amount": "0.00", "currency": "EUR", "as_percentage": "0.00" }, "total": { "cash_amount": "6.88", "currency": "EUR", "as_percentage": "0.56" } }, "third_party_payments": { "total": { "cash_amount": "0.70", "currency": "EUR", "as_percentage": "0.06" }, "received_by_client": { "cash_amount": "0.35", "currency": "EUR", "as_percentage": "0.03" }, "received_by_upvest": { "cash_amount": "0.35", "currency": "EUR", "as_percentage": "0.03" } }, "return_impact": { "year_one": { "cash_amount": "9.05", "currency": "EUR", "as_percentage": "0.74" }, "year_two": { "cash_amount": "6.96", "currency": "EUR", "as_percentage": "0.57" }, "year_three": { "cash_amount": "8.36", "currency": "EUR", "as_percentage": "0.68" } } } } }, "order-ex-ante-cost": { "summary": "Order ex-ante cost report", "value": { "id": "b96b1ee7-d491-43eb-b5e4-4833af9c9c2f", "created_at": "2023-08-24T14:15:22Z", "user_id": "d1a4be99-8bb6-4e78-b897-8168f6823ab5", "type": "ORDER_EX_ANTE_COST", "substituted_report_id": null, "data": { "account": { "id": "c5034305-c441-4711-adbf-93cfbc13a695", "account_number": 1 }, "account_group": { "id": "9d95820d-4333-46b6-98de-04ab7512e76f", "securities_account_number": "123456789" }, "user": { "salutation": "SALUTATION_MALE", "title": "DR", "first_name": "Karl", "last_name": "Schmidt", "address": { "address_line1": "Rosenweg 221", "address_line2": "apt. 33", "postcode": "45678", "city": "Berlin", "country": "DE" } }, "instrument": { "isin": "LU0274208692", "short_name": "XTR.MSCI WORLD SWAP 1C" }, "venue": { "name": "Tradegate" }, "order": { "user_id": "d1a4be99-8bb6-4e78-b897-8168f6823ab5", "instrument_id": "LU0274208692", "instrument_id_type": "ISIN", "account_id": "c5034305-c441-4711-adbf-93cfbc13a695", "order_type": "MARKET", "side": "BUY", "quantity": "15", "cash_amount": "1220.85", "currency": "EUR", "price": "81.39" }, "holding_period": { "unit": "YEAR", "quantity": 3 }, "total_cost": { "product": { "cash_amount": "17.48", "currency": "EUR", "as_percentage": "1.43" }, "service": { "cash_amount": "6.88", "currency": "EUR", "as_percentage": "0.56" }, "third_party": { "cash_amount": "0.70", "currency": "EUR", "as_percentage": "0.06" }, "total": { "cash_amount": "25.06", "currency": "EUR", "as_percentage": "2.05" } }, "product_cost": { "one_off": { "cash_amount": "0.20", "currency": "EUR", "as_percentage": "0.02" }, "ongoing": { "cash_amount": "16.48", "currency": "EUR", "as_percentage": "1.35" }, "transaction": { "cash_amount": "0.80", "currency": "EUR", "as_percentage": "0.07" }, "incidental": { "cash_amount": "0.00", "currency": "EUR", "as_percentage": "0.00" }, "total": { "cash_amount": "17.48", "currency": "EUR", "as_percentage": "1.43" } }, "service_cost": { "one_off": { "cash_amount": "0.49", "currency": "EUR", "as_percentage": "0.04" }, "ongoing": { "cash_amount": "4.39", "currency": "EUR", "as_percentage": "0.36" }, "transaction": { "cash_amount": "2.00", "currency": "EUR", "as_percentage": "0.16" }, "ancillary": { "cash_amount": "0.00", "currency": "EUR", "as_percentage": "0.00" }, "incidental": { "cash_amount": "0.00", "currency": "EUR", "as_percentage": "0.00" }, "total": { "cash_amount": "6.88", "currency": "EUR", "as_percentage": "0.56" } }, "third_party_payments": { "total": { "cash_amount": "0.70", "currency": "EUR", "as_percentage": "0.06" }, "received_by_client": { "cash_amount": "0.35", "currency": "EUR", "as_percentage": "0.03" }, "received_by_upvest": { "cash_amount": "0.35", "currency": "EUR", "as_percentage": "0.03" } }, "return_impact": { "year_one": { "cash_amount": "9.05", "currency": "EUR", "as_percentage": "0.74" }, "year_two": { "cash_amount": "6.96", "currency": "EUR", "as_percentage": "0.57" }, "year_three": { "cash_amount": "8.36", "currency": "EUR", "as_percentage": "0.68" } } } } }, "report": { "summary": "Report", "value": { "id": "b96b1ee7-d491-43eb-b5e4-4833af9c9c2f", "created_at": "2020-08-24T14:15:22Z", "user_id": "d1a4be99-8bb6-4e78-b897-8168f6823ab5", "type": "BUY_ORDER", "substituted_report_id": null, "data": { "account": { "id": "a9a4ad54-6dd1-419a-a98d-ab48f9f23bc8" } } } }, "business-report": { "summary": "Business report", "value": { "id": "b96b1ee7-d491-43eb-b5e4-4833af9c9c2f", "created_at": "2020-08-24T14:15:22Z", "business_id": "a9a72268-4f3c-4de2-abb9-a553a3bb7608", "type": "BUY_ORDER", "substituted_report_id": null, "data": { "account": { "id": "a9a4ad54-6dd1-419a-a98d-ab48f9f23bc8" } } } } } }, "application/pdf": { "schema": { "title": "Report" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/users/{user_id}/tax_residencies": { "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "The unique identifier of the user. Universally Unique Identifier (UUID).", "schema": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_tax_residencies", "summary": "Retrieve tax residencies", "description": "Returns the tax residencies currently on file for the user identified by `user_id`.\n\nSee the User tax onboarding guide ([TOL](https://docs.upvest.co/products/tol/guides/users/users_tax_onboarding) / [BYOL](https://docs.upvest.co/products/byol/guides/users/users_tax_onboarding)) for tax residency requirements.", "tags": [ "Tax Residencies" ], "security": [ { "oauth-client-credentials": [ "taxes:read", "taxes:admin" ] } ], "responses": { "200": { "description": "User tax residencies", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Tax residency Record", "type": "object", "description": "A set of tax residencies submitted for a user, with the processing status and timestamps. The record is `PENDING` until processed by Upvest, then `ACTIVE` when in use.", "properties": { "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "tax_residencies": { "type": "array", "description": "Tax residencies contained in this record", "items": { "title": "Tax residency", "description": "A single tax residency of a user. Provide either a tax identifier number for the country, or a reason why the TIN is missing.", "oneOf": [ { "type": "object", "title": "With tax identifier number", "properties": { "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "tax_identifier_number": { "type": "string", "maxLength": 20, "minLength": 1, "description": "Tax identification number (TIN) issued to the user by the tax authorities of the given country" } }, "required": [ "country", "tax_identifier_number" ] }, { "type": "object", "title": "Without tax identifier number", "properties": { "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "missing_tin_reason": { "type": "string", "enum": [ "TIN_NOT_YET_ASSIGNED", "COUNTRY_HAS_NO_TIN", "OTHER_REASONS" ], "description": "Reason why TIN is missing\n* TIN_NOT_YET_ASSIGNED - Indicates that the tax identification number has not yet been assigned by the tax authorities. A common example is, that a user has moved to a country and thus became taxable, but that the tax authorities have not yet assigned the TIN to this user.\n* COUNTRY_HAS_NO_TIN - Indicates that the specific country does not provide a TIN.\n* OTHER_REASONS - Applies in case of other reasons - i.e. when a user does not have the TIN at hand. Note this may cause additional inquiries by our customer service team." } }, "required": [ "country", "missing_tin_reason" ] } ] } }, "status": { "type": "string", "enum": [ "PENDING", "ACTIVE" ], "description": "Tax residency status\n* PENDING - It indicates that the tax residency records are not yet processed by Upvest.\n* ACTIVE - It indicates that tax residency records are processed, and the tax residency record is the one in use." } }, "required": [ "updated_at", "created_at", "tax_residencies", "status" ], "additionalProperties": false }, "example": { "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "status": "ACTIVE", "tax_residencies": [ { "country": "IT", "tax_identifier_number": "LLLLLL99L99L999L" }, { "country": "FR", "missing_tin_reason": "COUNTRY_HAS_NO_TIN" }, { "country": "DE", "tax_identifier_number": "12345678901" } ] } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "405": { "description": "Method Not Allowed. The requested method is not allowed on the requested resource.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 405, "type": "method_not_allowed" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "post": { "operationId": "set_tax_residencies", "summary": "Update tax residencies", "description": "Records the tax residencies for the user identified by `user_id`, replacing any previously submitted set.\n\nSee the User tax onboarding guide ([TOL](https://docs.upvest.co/products/tol/guides/users/users_tax_onboarding) / [BYOL](https://docs.upvest.co/products/byol/guides/users/users_tax_onboarding)) for tax residency requirements.", "tags": [ "Tax Residencies" ], "security": [ { "oauth-client-credentials": [ "taxes:admin" ] } ], "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$", "example": "ccb07f42-4104-44ad-8e1f-c660bb7b269c" }, "description": "A UUID to be used as an idempotency key. This prevents a duplicate request from being replayed.\nhttps://docs.upvest.co/documentation/concepts/api_concepts/idempotency\n" } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Tax Residencies - Set - Request", "type": "object", "description": "Request payload for setting a user's tax residencies. The submitted set replaces any previously recorded tax residencies.", "properties": { "tax_residencies": { "type": "array", "minItems": 1, "description": "Tax residencies to record for the user. Must contain at least one entry", "items": { "title": "Tax residency for Create Request", "description": "A single tax residency submitted in a set request. Provide either a tax identifier number for the country, or a reason why the TIN is missing.", "oneOf": [ { "type": "object", "title": "With tax identifier number", "properties": { "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "tax_identifier_number": { "type": "string", "maxLength": 20, "minLength": 1, "description": "Tax identification number (TIN) issued to the user by the tax authorities of the given country" } }, "required": [ "country", "tax_identifier_number" ] }, { "type": "object", "title": "Without tax identifier number", "properties": { "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "missing_tin_reason": { "type": "string", "enum": [ "TIN_NOT_YET_ASSIGNED", "COUNTRY_HAS_NO_TIN", "OTHER_REASONS" ], "description": "Reason why TIN is missing\n* TIN_NOT_YET_ASSIGNED - Indicates that the tax identification number has not yet been assigned by the tax authorities. A common example is, that a user has moved to a country and thus became taxable, but that the tax authorities have not yet assigned the TIN to this user.\n* COUNTRY_HAS_NO_TIN - Indicates that the specific country does not provide a TIN.\n* OTHER_REASONS - Applies in case of other reasons - i.e. when a user does not have the TIN at hand. Note this may cause additional inquiries by our customer service team." } }, "required": [ "country", "missing_tin_reason" ] } ] } } }, "required": [ "tax_residencies" ], "additionalProperties": false }, "examples": { "one": { "summary": "One residency", "value": { "tax_residencies": [ { "country": "DE", "tax_identifier_number": "12345678901" } ] } }, "multiple": { "summary": "Multiple residencies", "value": { "tax_residencies": [ { "country": "IT", "tax_identifier_number": "ABCDEF12G34H567I" }, { "country": "FR", "missing_tin_reason": "TIN_NOT_YET_ASSIGNED" }, { "country": "DE", "tax_identifier_number": "12345678901" } ] } } } } } }, "responses": { "200": { "description": "User tax residencies", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Tax residency Record", "type": "object", "description": "A set of tax residencies submitted for a user, with the processing status and timestamps. The record is `PENDING` until processed by Upvest, then `ACTIVE` when in use.", "properties": { "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "tax_residencies": { "type": "array", "description": "Tax residencies contained in this record", "items": { "title": "Tax residency", "description": "A single tax residency of a user. Provide either a tax identifier number for the country, or a reason why the TIN is missing.", "oneOf": [ { "type": "object", "title": "With tax identifier number", "properties": { "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "tax_identifier_number": { "type": "string", "maxLength": 20, "minLength": 1, "description": "Tax identification number (TIN) issued to the user by the tax authorities of the given country" } }, "required": [ "country", "tax_identifier_number" ] }, { "type": "object", "title": "Without tax identifier number", "properties": { "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "missing_tin_reason": { "type": "string", "enum": [ "TIN_NOT_YET_ASSIGNED", "COUNTRY_HAS_NO_TIN", "OTHER_REASONS" ], "description": "Reason why TIN is missing\n* TIN_NOT_YET_ASSIGNED - Indicates that the tax identification number has not yet been assigned by the tax authorities. A common example is, that a user has moved to a country and thus became taxable, but that the tax authorities have not yet assigned the TIN to this user.\n* COUNTRY_HAS_NO_TIN - Indicates that the specific country does not provide a TIN.\n* OTHER_REASONS - Applies in case of other reasons - i.e. when a user does not have the TIN at hand. Note this may cause additional inquiries by our customer service team." } }, "required": [ "country", "missing_tin_reason" ] } ] } }, "status": { "type": "string", "enum": [ "PENDING", "ACTIVE" ], "description": "Tax residency status\n* PENDING - It indicates that the tax residency records are not yet processed by Upvest.\n* ACTIVE - It indicates that tax residency records are processed, and the tax residency record is the one in use." } }, "required": [ "updated_at", "created_at", "tax_residencies", "status" ], "additionalProperties": false }, "example": { "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "tax_residencies": [ { "country": "AT", "missing_tin_reason": "TIN_NOT_YET_ASSIGNED" }, { "country": "DE", "tax_identifier_number": "12345678901" } ], "status": "ACTIVE" } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/portfolios/allocations": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_portfolios_allocations", "summary": "List portfolios allocations", "description": "Returns a paginated list of portfolio allocations for the authenticated client.\n\nAllocations define the target instrument weights that portfolio configurations use to invest and rebalance.\n\nSee the Portfolios guide ([TOL](https://docs.upvest.co/products/tol/guides/portfolios) / [BYOL](https://docs.upvest.co/products/byol/guides/portfolios)) for implementation details.", "tags": [ "Portfolios" ], "security": [ { "oauth-client-credentials": [ "portfolios:read", "portfolios:admin" ] } ], "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "id" ], "default": "id" }, "description": "Sort the result by `id`." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. By default, only ASC for ascending sort." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "title": "Date in YYYY-MM-DD format. RFC 3339, section 5.6" }, "description": "Returns portfolio allocations with dates starting from and including this date (UTC)", "example": "2022-10-14T10:10:10Z" }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "title": "Date in YYYY-MM-DD format. RFC 3339, section 5.6" }, "description": "Returns portfolio allocations with dates up until this date (UTC)", "example": "2022-10-14T10:10:10Z" }, { "name": "instrument_ids", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filters portfolio allocations containing the instruments ID's", "example": "bf72bdc1-b342-494f-9739-b27ae9011b86,dcbe2cf4-4f37-4fe5-9393-4fb52bb87fab" } ], "responses": { "200": { "description": "Portfolios allocations", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Portfolios allocations - List - Response", "type": "object", "description": "Paginated list of portfolio allocations, including cursor-based pagination metadata.", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "items": { "title": "Portfolios allocation", "type": "object", "description": "Defines a named set of instrument weights for a portfolio. The `allocation` array specifies each instrument (by ISIN or Upvest UUID) and its target weight percentage. Weights must sum to 100.", "properties": { "id": { "title": "Portfolio allocation unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio allocation.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "name": { "description": "Allocation name", "type": "string" }, "allocation": { "description": "List of portfolios allocations", "type": "array", "items": { "type": "object", "properties": { "instrument_id": { "oneOf": [ { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, { "title": "Unique identifier", "description": "UPVEST instrument identifier", "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$" } ] }, "instrument_id_type": { "description": "The type of the ID used in the request.\n* ISIN - International Securities Identification Number\n* UPVEST - UPVEST's unique instrument identifier", "enum": [ "ISIN", "UPVEST" ], "default": "ISIN", "type": "string" }, "weight": { "description": "Instrument allocation weight", "type": "string", "pattern": "^(100|[0-9]{1,2}(\\.[0-9]{1,5})?)$" } }, "required": [ "instrument_id", "instrument_id_type", "weight" ], "additionalProperties": false } } }, "required": [ "id", "created_at", "updated_at", "name", "allocation" ], "additionalProperties": false } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "example": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1, "sort": "id", "order": "ASC" }, "data": [ { "id": "c27c1fdc-b129-4d7a-95ac-c8a4f05d2804", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "name": "Allocation 1", "allocation": [ { "instrument_id": "IE00B0M62Q58", "instrument_id_type": "ISIN", "weight": "0.7" }, { "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "weight": "0.3" } ] } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "405": { "description": "Method Not Allowed. The requested method is not allowed on the requested resource.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 405, "type": "method_not_allowed" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "post": { "operationId": "create_portfolios_allocation", "summary": "Create portfolios allocation", "description": "Creates a named portfolio allocation specifying a set of instrument weights.\n\nThe `allocation` array must contain at least one instrument entry. Weights are expressed as percentages and must sum to 100.\n\nSee the Portfolios guide ([TOL](https://docs.upvest.co/products/tol/guides/portfolios) / [BYOL](https://docs.upvest.co/products/byol/guides/portfolios)) for implementation details.", "tags": [ "Portfolios" ], "security": [ { "oauth-client-credentials": [ "portfolios:admin" ] } ], "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$", "example": "ccb07f42-4104-44ad-8e1f-c660bb7b269c" }, "description": "A UUID to be used as an idempotency key. This prevents a duplicate request from being replayed.\nhttps://docs.upvest.co/documentation/concepts/api_concepts/idempotency\n" } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Portfolios allocation - Create - Request", "type": "object", "description": "Request body for creating a portfolio allocation. Specifies the allocation name, instrument weights, and optional rebalancing strategy IDs.", "properties": { "name": { "description": "Allocation name", "type": "string" }, "allocation": { "description": "List of portfolios allocations", "type": "array", "items": { "type": "object", "properties": { "instrument_id": { "oneOf": [ { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, { "title": "Unique identifier", "description": "UPVEST instrument identifier", "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$" } ] }, "instrument_id_type": { "description": "The type of the ID used in the request.\n* ISIN - International Securities Identification Number\n* UPVEST - UPVEST's unique instrument identifier", "enum": [ "ISIN", "UPVEST" ], "default": "ISIN", "type": "string" }, "weight": { "description": "Instrument allocation weight", "type": "string", "pattern": "^(100|[0-9]{1,2}(\\.[0-9]{1,5})?)$" } }, "required": [ "instrument_id", "instrument_id_type", "weight" ], "additionalProperties": false } }, "rebalancing_strategy_ids": { "description": "List of rebalancing strategy ids", "type": "array", "items": { "title": "Portfolio rebalancing strategy unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio rebalancing strategy.", "format": "uuid" } } }, "required": [ "allocation" ], "additionalProperties": false }, "example": { "name": "Allocation 1", "allocation": [ { "instrument_id": "IE00B0M62Q58", "instrument_id_type": "ISIN", "weight": "0.7" }, { "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "weight": "0.3" } ] } } } }, "responses": { "200": { "description": "Portfolios allocation", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Portfolios allocation", "type": "object", "description": "Defines a named set of instrument weights for a portfolio. The `allocation` array specifies each instrument (by ISIN or Upvest UUID) and its target weight percentage. Weights must sum to 100.", "properties": { "id": { "title": "Portfolio allocation unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio allocation.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "name": { "description": "Allocation name", "type": "string" }, "allocation": { "description": "List of portfolios allocations", "type": "array", "items": { "type": "object", "properties": { "instrument_id": { "oneOf": [ { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, { "title": "Unique identifier", "description": "UPVEST instrument identifier", "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$" } ] }, "instrument_id_type": { "description": "The type of the ID used in the request.\n* ISIN - International Securities Identification Number\n* UPVEST - UPVEST's unique instrument identifier", "enum": [ "ISIN", "UPVEST" ], "default": "ISIN", "type": "string" }, "weight": { "description": "Instrument allocation weight", "type": "string", "pattern": "^(100|[0-9]{1,2}(\\.[0-9]{1,5})?)$" } }, "required": [ "instrument_id", "instrument_id_type", "weight" ], "additionalProperties": false } } }, "required": [ "id", "created_at", "updated_at", "name", "allocation" ], "additionalProperties": false }, "example": { "id": "436244bb-4afd-4002-b53b-b1d7a3bca032", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "name": "Allocation 1", "allocation": [ { "instrument_id": "IE00B0M62Q58", "instrument_id_type": "ISIN", "weight": "0.7" }, { "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "weight": "0.3" } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/portfolios/allocations/{allocation_id}": { "parameters": [ { "name": "allocation_id", "in": "path", "required": true, "description": "The unique identifier of the portfolio allocation. Universally Unique Identifier (UUID).", "schema": { "title": "Portfolio allocation unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio allocation.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_portfolios_allocation", "summary": "Retrieve portfolios allocation", "description": "Retrieves a portfolio allocation by its ID, including its name, instrument weights, and associated rebalancing strategy IDs.\n\nSee the Portfolios guide ([TOL](https://docs.upvest.co/products/tol/guides/portfolios) / [BYOL](https://docs.upvest.co/products/byol/guides/portfolios)) for implementation details.", "tags": [ "Portfolios" ], "security": [ { "oauth-client-credentials": [ "portfolios:read", "portfolios:admin" ] } ], "responses": { "200": { "description": "Portfolios allocation", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Portfolios allocation", "type": "object", "description": "Defines a named set of instrument weights for a portfolio. The `allocation` array specifies each instrument (by ISIN or Upvest UUID) and its target weight percentage. Weights must sum to 100.", "properties": { "id": { "title": "Portfolio allocation unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio allocation.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "name": { "description": "Allocation name", "type": "string" }, "allocation": { "description": "List of portfolios allocations", "type": "array", "items": { "type": "object", "properties": { "instrument_id": { "oneOf": [ { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, { "title": "Unique identifier", "description": "UPVEST instrument identifier", "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$" } ] }, "instrument_id_type": { "description": "The type of the ID used in the request.\n* ISIN - International Securities Identification Number\n* UPVEST - UPVEST's unique instrument identifier", "enum": [ "ISIN", "UPVEST" ], "default": "ISIN", "type": "string" }, "weight": { "description": "Instrument allocation weight", "type": "string", "pattern": "^(100|[0-9]{1,2}(\\.[0-9]{1,5})?)$" } }, "required": [ "instrument_id", "instrument_id_type", "weight" ], "additionalProperties": false } } }, "required": [ "id", "created_at", "updated_at", "name", "allocation" ], "additionalProperties": false }, "example": { "id": "bf5f2676-4535-403d-bc66-06ec38cc70af", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "name": "Allocation 1", "allocation": [ { "instrument_id": "IE00B0M62Q58", "instrument_id_type": "ISIN", "weight": "0.7" }, { "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "weight": "0.3" } ] } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "put": { "operationId": "update_portfolios_allocation", "summary": "Update portfolios allocation", "description": "Updates the name and/or instrument weights of an existing portfolio allocation.\n\nAccounts with a portfolio configuration referencing this allocation will use the new weights on their next rebalancing.\n\nSee the Portfolios guide ([TOL](https://docs.upvest.co/products/tol/guides/portfolios) / [BYOL](https://docs.upvest.co/products/byol/guides/portfolios)) for implementation details.", "tags": [ "Portfolios" ], "security": [ { "oauth-client-credentials": [ "portfolios:admin" ] } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Portfolios allocation - Update - Request", "type": "object", "description": "Request body for updating a portfolio allocation. Updates the name and/or instrument weights. Updated weights must still sum to 100.", "properties": { "name": { "description": "Allocation name", "type": "string" }, "allocation": { "description": "List of portfolios allocations", "type": "array", "items": { "type": "object", "properties": { "instrument_id": { "oneOf": [ { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, { "title": "Unique identifier", "description": "UPVEST instrument identifier", "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$" } ] }, "instrument_id_type": { "description": "The type of the ID used in the request.\n* ISIN - International Securities Identification Number\n* UPVEST - UPVEST's unique instrument identifier", "enum": [ "ISIN", "UPVEST" ], "default": "ISIN", "type": "string" }, "weight": { "description": "Instrument allocation weight", "type": "string", "pattern": "^(100|[0-9]{1,2}(\\.[0-9]{1,5})?)$" } }, "required": [ "instrument_id", "instrument_id_type", "weight" ], "additionalProperties": false } } }, "required": [ "allocation" ], "additionalProperties": false }, "examples": { "ordinary": { "summary": "Generic instruments", "value": { "allocation": [ { "instrument_id": "IE00B0M62Q58", "instrument_id_type": "ISIN", "weight": "0.6" }, { "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "weight": "0.4" } ] } }, "upvest": { "summary": "Including Upvest-specific instruments", "value": { "allocation": [ { "instrument_id": "IE00B0M62Q58", "instrument_id_type": "ISIN", "weight": "0.5" }, { "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "weight": "0.25" }, { "instrument_id": "c2721bc0-9f65-474b-a846-b237eb17fb05", "instrument_id_type": "UPVEST", "weight": "0.25" } ] } } } } } }, "responses": { "200": { "description": "Portfolios allocation", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Portfolios allocation", "type": "object", "description": "Defines a named set of instrument weights for a portfolio. The `allocation` array specifies each instrument (by ISIN or Upvest UUID) and its target weight percentage. Weights must sum to 100.", "properties": { "id": { "title": "Portfolio allocation unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio allocation.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "name": { "description": "Allocation name", "type": "string" }, "allocation": { "description": "List of portfolios allocations", "type": "array", "items": { "type": "object", "properties": { "instrument_id": { "oneOf": [ { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, { "title": "Unique identifier", "description": "UPVEST instrument identifier", "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$" } ] }, "instrument_id_type": { "description": "The type of the ID used in the request.\n* ISIN - International Securities Identification Number\n* UPVEST - UPVEST's unique instrument identifier", "enum": [ "ISIN", "UPVEST" ], "default": "ISIN", "type": "string" }, "weight": { "description": "Instrument allocation weight", "type": "string", "pattern": "^(100|[0-9]{1,2}(\\.[0-9]{1,5})?)$" } }, "required": [ "instrument_id", "instrument_id_type", "weight" ], "additionalProperties": false } } }, "required": [ "id", "created_at", "updated_at", "name", "allocation" ], "additionalProperties": false }, "example": { "id": "436244bb-4afd-4002-b53b-b1d7a3bca032", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-22T15:10:00.00Z", "name": "Allocation 1", "allocation": [ { "instrument_id": "IE00B0M62Q58", "instrument_id_type": "ISIN", "weight": "0.6" }, { "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "weight": "0.4" } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/portfolios/configurations": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_portfolios_configurations", "summary": "List portfolios configurations", "description": "Returns a paginated list of portfolio configurations for the authenticated client.\n\nEach configuration links an account to an allocation and defines which rebalancing strategies apply to that account.\n\nSee the Portfolios guide ([TOL](https://docs.upvest.co/products/tol/guides/portfolios) / [BYOL](https://docs.upvest.co/products/byol/guides/portfolios)) for implementation details.", "tags": [ "Portfolios" ], "security": [ { "oauth-client-credentials": [ "portfolios:read", "portfolios:admin" ] } ], "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "account_id" ], "default": "account_id" }, "description": "Sort the result by `account_id`." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. By default, only ASC for ascending sort." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "title": "Date in YYYY-MM-DD format. RFC 3339, section 5.6" }, "description": "Returns portfolio configurations with dates starting from and including this date (UTC)", "example": "2022-10-14T10:10:10Z" }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "title": "Date in YYYY-MM-DD format. RFC 3339, section 5.6" }, "description": "Returns portfolio configurations with dates up until this date (UTC)", "example": "2022-10-14T10:10:10Z" }, { "name": "account_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filters portfolio configurations by account ID", "example": "3ada8e9e-82c4-4c78-a43d-a691b1636509" }, { "name": "allocation_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filters portfolio configurations by allocation ID", "example": "f6c2b02a-3214-4a40-82ae-6c76df50bc8c" } ], "responses": { "200": { "description": "Portfolios configurations", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Portfolios configurations - List - Response", "type": "object", "description": "Paginated list of portfolio configurations, including cursor-based pagination metadata.", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "items": { "title": "Portfolios configuration", "type": "object", "description": "Links an investment account to a portfolio allocation and optional rebalancing strategies. Determines which allocation the account follows and which strategies govern automatic rebalancing.", "properties": { "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "allocation_id": { "title": "Portfolio allocation unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio allocation.", "format": "uuid" }, "rebalancing_strategy_ids": { "description": "List of rebalancing strategy ids", "type": "array", "items": { "title": "Portfolio rebalancing strategy unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio rebalancing strategy.", "format": "uuid" } } }, "required": [ "created_at", "updated_at", "account_id", "allocation_id" ], "additionalProperties": false } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "example": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1, "sort": "account_id", "order": "ASC" }, "data": [ { "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "account_id": "4ca934ae-66b2-4494-86f9-df6ab89351f1", "allocation_id": "65c69f95-c7b9-4c93-9943-a8c7fe4f7aef", "rebalancing_strategy_ids": [ "7a7322f5-b45d-4aba-aae4-c12797938c93", "d7b4291b-5a26-40c2-a8dd-235bd904a2ed" ] }, { "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "account_id": "a46c4531-ec90-4ac3-ac6b-356d743a3859", "allocation_id": "a4117e26-7c31-43ad-af47-0784a4957da9", "rebalancing_strategy_ids": [ "7a7322f5-b45d-4aba-aae4-c12797938c93", "692e318a-d6d0-43ac-999a-b84a82dbe304" ] } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "405": { "description": "Method Not Allowed. The requested method is not allowed on the requested resource.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 405, "type": "method_not_allowed" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "post": { "operationId": "create_portfolios_configuration", "summary": "Create portfolios configuration", "description": "Creates a portfolio configuration for an investment account, associating it with a target allocation and optional rebalancing strategies.\n\nOnly one active configuration per account is permitted.\n\nSee the Portfolios guide ([TOL](https://docs.upvest.co/products/tol/guides/portfolios) / [BYOL](https://docs.upvest.co/products/byol/guides/portfolios)) for implementation details.", "tags": [ "Portfolios" ], "security": [ { "oauth-client-credentials": [ "portfolios:admin" ] } ], "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$", "example": "ccb07f42-4104-44ad-8e1f-c660bb7b269c" }, "description": "A UUID to be used as an idempotency key. This prevents a duplicate request from being replayed.\nhttps://docs.upvest.co/documentation/concepts/api_concepts/idempotency\n" } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Portfolios configuration - Create - Request", "type": "object", "description": "Request body for creating a portfolio configuration for an account. Links the account to a target allocation and optional rebalancing strategies.", "properties": { "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "allocation_id": { "title": "Portfolio allocation unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio allocation.", "format": "uuid" }, "rebalancing_strategy_ids": { "description": "List of rebalancing strategy ids", "type": "array", "items": { "title": "Portfolio rebalancing strategy unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio rebalancing strategy.", "format": "uuid" } } }, "required": [ "account_id", "allocation_id" ], "additionalProperties": false }, "example": { "account_id": "f2f7d2c7-d79b-4de2-ae9b-d01646259f9e", "allocation_id": "eb68abce-29f4-483f-a384-7f243e77851f" } } } }, "responses": { "200": { "description": "Portfolios configuration", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Portfolios configuration", "type": "object", "description": "Links an investment account to a portfolio allocation and optional rebalancing strategies. Determines which allocation the account follows and which strategies govern automatic rebalancing.", "properties": { "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "allocation_id": { "title": "Portfolio allocation unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio allocation.", "format": "uuid" }, "rebalancing_strategy_ids": { "description": "List of rebalancing strategy ids", "type": "array", "items": { "title": "Portfolio rebalancing strategy unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio rebalancing strategy.", "format": "uuid" } } }, "required": [ "created_at", "updated_at", "account_id", "allocation_id" ], "additionalProperties": false }, "example": { "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "account_id": "f2f7d2c7-d79b-4de2-ae9b-d01646259f9e", "allocation_id": "eb68abce-29f4-483f-a384-7f243e77851f", "rebalancing_strategy_ids": [ "7a7322f5-b45d-4aba-aae4-c12797938c93", "fd8e5363-a89c-4a2f-b3c6-5f857721625f" ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "422": { "description": "Unprocessable Entity. The syntax of request is correct but server can't process it due a semantic error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 422, "type": "unprocessable_entity" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/portfolios/configurations/{account_id}": { "parameters": [ { "name": "account_id", "in": "path", "required": true, "description": "The unique identifier of the account. Universally Unique Identifier (UUID).", "schema": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_portfolios_configuration", "summary": "Retrieve portfolios configuration", "description": "Retrieves a portfolio configuration by its ID, including the linked allocation and any associated rebalancing strategies.\n\nSee the Portfolios guide ([TOL](https://docs.upvest.co/products/tol/guides/portfolios) / [BYOL](https://docs.upvest.co/products/byol/guides/portfolios)) for implementation details.", "tags": [ "Portfolios" ], "security": [ { "oauth-client-credentials": [ "portfolios:read", "portfolios:admin" ] } ], "responses": { "200": { "description": "Portfolios", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Portfolios configuration", "type": "object", "description": "Links an investment account to a portfolio allocation and optional rebalancing strategies. Determines which allocation the account follows and which strategies govern automatic rebalancing.", "properties": { "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "allocation_id": { "title": "Portfolio allocation unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio allocation.", "format": "uuid" }, "rebalancing_strategy_ids": { "description": "List of rebalancing strategy ids", "type": "array", "items": { "title": "Portfolio rebalancing strategy unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio rebalancing strategy.", "format": "uuid" } } }, "required": [ "created_at", "updated_at", "account_id", "allocation_id" ], "additionalProperties": false }, "example": { "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "account_id": "f2f7d2c7-d79b-4de2-ae9b-d01646259f9e", "allocation_id": "eb68abce-29f4-483f-a384-7f243e77851f", "rebalancing_strategy_ids": [ "7a7322f5-b45d-4aba-aae4-c12797938c93", "fd8e5363-a89c-4a2f-b3c6-5f857721625f" ] } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "405": { "description": "Method Not Allowed. The requested method is not allowed on the requested resource.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 405, "type": "method_not_allowed" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "patch": { "operationId": "update_portfolios_configuration", "summary": "Update portfolios configuration", "description": "Updates the allocation or rebalancing strategies of an existing portfolio configuration.\n\nSee the Portfolios guide ([TOL](https://docs.upvest.co/products/tol/guides/portfolios) / [BYOL](https://docs.upvest.co/products/byol/guides/portfolios)) for implementation details.", "tags": [ "Portfolios" ], "security": [ { "oauth-client-credentials": [ "portfolios:admin" ] } ], "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$", "example": "ccb07f42-4104-44ad-8e1f-c660bb7b269c" }, "description": "A UUID to be used as an idempotency key. This prevents a duplicate request from being replayed.\nhttps://docs.upvest.co/documentation/concepts/api_concepts/idempotency\n" } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Portfolios configuration - Update - Request", "type": "object", "description": "Request body for updating a portfolio configuration. Updates the target allocation and/or associated rebalancing strategies.", "properties": { "allocation_id": { "title": "Portfolio allocation unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio allocation.", "format": "uuid" }, "rebalancing_strategy_ids": { "description": "List of rebalancing strategy ids", "type": "array", "items": { "title": "Portfolio rebalancing strategy unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio rebalancing strategy.", "format": "uuid" } } }, "additionalProperties": false }, "example": { "allocation_id": "359e9c9e-b91c-4853-8674-e6657af609fc" } } } }, "responses": { "200": { "description": "Portfolio", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Portfolios configuration", "type": "object", "description": "Links an investment account to a portfolio allocation and optional rebalancing strategies. Determines which allocation the account follows and which strategies govern automatic rebalancing.", "properties": { "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "allocation_id": { "title": "Portfolio allocation unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio allocation.", "format": "uuid" }, "rebalancing_strategy_ids": { "description": "List of rebalancing strategy ids", "type": "array", "items": { "title": "Portfolio rebalancing strategy unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio rebalancing strategy.", "format": "uuid" } } }, "required": [ "created_at", "updated_at", "account_id", "allocation_id" ], "additionalProperties": false }, "example": { "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-22T15:10:00.00Z", "account_id": "f2f7d2c7-d79b-4de2-ae9b-d01646259f9e", "allocation_id": "359e9c9e-b91c-4853-8674-e6657af609fc", "rebalancing_strategy_ids": [ "7a7322f5-b45d-4aba-aae4-c12797938c93", "fd8e5363-a89c-4a2f-b3c6-5f857721625f" ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "delete": { "operationId": "delete_portfolios_configuration", "summary": "Delete portfolios configuration", "description": "Delete portfolios configuration (hard delete)", "tags": [ "Portfolios" ], "security": [ { "oauth-client-credentials": [ "portfolios:admin" ] } ], "responses": { "204": { "description": "Request has been processed successfully.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/portfolios/orders": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_portfolios_orders", "summary": "List portfolios orders", "description": "Returns a paginated list of portfolio orders for the authenticated client.\n\nPortfolio orders represent buy or sell instructions that invest or withdraw a cash amount across all instruments in the account's current allocation.\n\nSee the Portfolios guide ([TOL](https://docs.upvest.co/products/tol/guides/portfolios) / [BYOL](https://docs.upvest.co/products/byol/guides/portfolios)) for order lifecycle details.", "tags": [ "Portfolios" ], "security": [ { "oauth-client-credentials": [ "portfolios:read", "portfolios:admin" ] } ], "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "id" ], "default": "id" }, "description": "Sort the result by `id`." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. By default, only ASC for ascending sort." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "title": "Date in YYYY-MM-DD format. RFC 3339, section 5.6" }, "description": "Returns portfolio orders with dates starting from and including this date (UTC)", "example": "2022-10-14T10:10:10Z" }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "title": "Date in YYYY-MM-DD format. RFC 3339, section 5.6" }, "description": "Returns portfolio orders with dates up until this date (UTC)", "example": "2022-10-14T10:10:10Z" }, { "name": "allocation_id", "in": "query", "required": false, "schema": { "title": "Portfolio allocation unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio allocation.", "format": "uuid" }, "example": "f96eaefd-b4c6-477a-9bbe-c744bf26172f", "description": "Filters portfolio orders containing the allocation id" }, { "name": "account_id", "in": "query", "required": false, "schema": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "example": "2c865aab-6737-4b0e-9154-69a4622b2727", "description": "Filters portfolio orders containing the account id" } ], "responses": { "200": { "description": "Portfolios orders", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Portfolios orders - List - Response", "type": "object", "description": "Paginated list of portfolio orders, including cursor-based pagination metadata.", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "items": { "title": "Portfolios order", "type": "object", "description": "Represents a portfolio order — a BUY or SELL instruction that invests or withdraws a cash amount distributed across all instruments in the account's current allocation.", "properties": { "id": { "title": "Portfolios order unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio order.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "allocation_id": { "title": "Portfolio allocation unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio allocation.", "format": "uuid" }, "cash_amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "status": { "type": "string", "description": "Execution status of the Portfolio Order.\n* NEW - \n* PROCESSING - \n* FILLED - \n* SETTLED - \n* CANCELLED - ", "enum": [ "NEW", "PROCESSING", "FILLED", "SETTLED", "CANCELLED" ] }, "type": { "type": "string", "description": "Type of the Portfolio Order.\n* BUY - \n* SELL - \n* REBALANCING - ", "enum": [ "BUY", "SELL", "REBALANCING" ] }, "post_tax": { "type": "boolean", "description": "Cash amount is post-tax value", "default": false }, "orders": { "type": "array", "description": "Orders associated with this portfolio order", "items": { "title": "Portfolios order", "type": "object", "description": "An individual instrument order within a portfolio order, representing the BUY or SELL of a single instrument.", "properties": { "id": { "title": "Order unique identifier", "type": "string", "description": "Unique identifier for an order. Universally Unique Identifier (UUID).", "format": "uuid" }, "side": { "type": "string", "description": "Side of the portfolio order.\n* BUY - \n* SELL - ", "enum": [ "BUY", "SELL" ] }, "status": { "type": "string", "description": "The execution status of the order.\n* NEW — the order has been received and validated, awaiting routing.\n* PROCESSING — the order is being routed for execution.\n* FILLED — the order has been fully executed.\n* CANCELLED — the order was cancelled before being fully executed.", "enum": [ "NEW", "PROCESSING", "FILLED", "CANCELLED" ] } }, "required": [ "id", "side", "status" ], "additionalProperties": false } }, "client_reference": { "title": "An ID provided by the client", "type": "string", "description": "A reference string provided by the client to correlate the portfolio order with a record in the client's own system." }, "initiation_flow": { "title": "Initiation flow used during order creation", "description": "What triggered the order creation .\n* API - \n* SAVINGS_PLAN - ", "type": "string", "enum": [ "API", "SAVINGS_PLAN" ] }, "cancellation_reason": { "title": "Cancellation reason code", "description": "Explains the reason why the order was cancelled .\n* ACCOUNT_IS_EMPTY - \n* CANCELLED_BY_CLIENT - \n* CANCELLED_BY_UPVEST - \n* PORTFOLIO_IS_BALANCED - \n* SELL_LIMIT_EXCEEDED - ", "type": "string", "enum": [ "ACCOUNT_IS_EMPTY", "CANCELLED_BY_CLIENT", "CANCELLED_BY_UPVEST", "PORTFOLIO_IS_BALANCED", "SELL_LIMIT_EXCEEDED" ] }, "cancellation_details": { "type": "string" } }, "required": [ "id", "created_at", "updated_at", "account_id", "cash_amount", "currency", "status", "post_tax", "client_reference", "initiation_flow", "orders" ], "additionalProperties": false } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "example": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1, "sort": "id", "order": "ASC" }, "data": [ { "id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c", "created_at": "2021-07-21T14:10:00.000Z", "updated_at": "2021-07-21T14:10:00.000Z", "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3", "allocation_id": "eb68abce-29f4-483f-a384-7f243e77851f", "cash_amount": "1000", "currency": "EUR", "status": "PROCESSING", "type": "SELL", "post_tax": false, "client_reference": "", "initiation_flow": "API", "orders": [ { "id": "b291d8a4-21f5-4c52-8590-4f90ce54d0b1", "side": "SELL", "status": "NEW" }, { "id": "81d02bd9-7b9d-443d-bbfa-31df4d543f7d", "side": "SELL", "status": "PROCESSING" }, { "id": "e97fb564-ebb4-4f37-930a-bda49c09a2e4", "side": "SELL", "status": "FILLED" } ] } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "405": { "description": "Method Not Allowed. The requested method is not allowed on the requested resource.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 405, "type": "method_not_allowed" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "post": { "operationId": "create_portfolios_order", "summary": "Create portfolios order", "description": "Places a buy or sell portfolio order for the specified account, distributing the cash amount across instruments according to the account's allocation weights.\n\nOne underlying instrument order is generated per instrument in the allocation.\n\nSee the Portfolios guide ([TOL](https://docs.upvest.co/products/tol/guides/portfolios) / [BYOL](https://docs.upvest.co/products/byol/guides/portfolios)) for implementation details.", "tags": [ "Portfolios" ], "security": [ { "oauth-client-credentials": [ "portfolios:admin" ] } ], "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$", "example": "ccb07f42-4104-44ad-8e1f-c660bb7b269c" }, "description": "A UUID to be used as an idempotency key. This prevents a duplicate request from being replayed.\nhttps://docs.upvest.co/documentation/concepts/api_concepts/idempotency\n" } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Portfolios order - Place - Request", "type": "object", "description": "Request body for placing a portfolio order. Specifies the account, cash amount, currency, and order side (`BUY` or `SELL`).", "properties": { "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "cash_amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "side": { "type": "string", "description": "Side of the portfolio order.\n* BUY - \n* SELL - ", "enum": [ "BUY", "SELL" ] }, "post_tax": { "type": "boolean", "description": "Cash amount is post-tax value", "default": false } }, "required": [ "user_id", "account_id", "side", "cash_amount", "currency" ], "additionalProperties": false }, "examples": { "buy": { "summary": "Buy", "value": { "user_id": "4b9732bd-7496-4e91-8a5f-6360479d7fed", "account_id": "00ef0be8-d564-43af-b3c7-11b7a2188030", "cash_amount": "100.00", "currency": "EUR", "side": "BUY" } }, "sell": { "summary": "Sell", "value": { "user_id": "4b9732bd-7496-4e91-8a5f-6360479d7fed", "account_id": "00ef0be8-d564-43af-b3c7-11b7a2188030", "cash_amount": "1000.00", "currency": "EUR", "side": "SELL" } } } } } }, "responses": { "200": { "description": "Portfolios order", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Portfolios order", "type": "object", "description": "Represents a portfolio order — a BUY or SELL instruction that invests or withdraws a cash amount distributed across all instruments in the account's current allocation.", "properties": { "id": { "title": "Portfolios order unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio order.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "allocation_id": { "title": "Portfolio allocation unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio allocation.", "format": "uuid" }, "cash_amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "status": { "type": "string", "description": "Execution status of the Portfolio Order.\n* NEW - \n* PROCESSING - \n* FILLED - \n* SETTLED - \n* CANCELLED - ", "enum": [ "NEW", "PROCESSING", "FILLED", "SETTLED", "CANCELLED" ] }, "type": { "type": "string", "description": "Type of the Portfolio Order.\n* BUY - \n* SELL - \n* REBALANCING - ", "enum": [ "BUY", "SELL", "REBALANCING" ] }, "post_tax": { "type": "boolean", "description": "Cash amount is post-tax value", "default": false }, "orders": { "type": "array", "description": "Orders associated with this portfolio order", "items": { "title": "Portfolios order", "type": "object", "description": "An individual instrument order within a portfolio order, representing the BUY or SELL of a single instrument.", "properties": { "id": { "title": "Order unique identifier", "type": "string", "description": "Unique identifier for an order. Universally Unique Identifier (UUID).", "format": "uuid" }, "side": { "type": "string", "description": "Side of the portfolio order.\n* BUY - \n* SELL - ", "enum": [ "BUY", "SELL" ] }, "status": { "type": "string", "description": "The execution status of the order.\n* NEW — the order has been received and validated, awaiting routing.\n* PROCESSING — the order is being routed for execution.\n* FILLED — the order has been fully executed.\n* CANCELLED — the order was cancelled before being fully executed.", "enum": [ "NEW", "PROCESSING", "FILLED", "CANCELLED" ] } }, "required": [ "id", "side", "status" ], "additionalProperties": false } }, "client_reference": { "title": "An ID provided by the client", "type": "string", "description": "A reference string provided by the client to correlate the portfolio order with a record in the client's own system." }, "initiation_flow": { "title": "Initiation flow used during order creation", "description": "What triggered the order creation .\n* API - \n* SAVINGS_PLAN - ", "type": "string", "enum": [ "API", "SAVINGS_PLAN" ] }, "cancellation_reason": { "title": "Cancellation reason code", "description": "Explains the reason why the order was cancelled .\n* ACCOUNT_IS_EMPTY - \n* CANCELLED_BY_CLIENT - \n* CANCELLED_BY_UPVEST - \n* PORTFOLIO_IS_BALANCED - \n* SELL_LIMIT_EXCEEDED - ", "type": "string", "enum": [ "ACCOUNT_IS_EMPTY", "CANCELLED_BY_CLIENT", "CANCELLED_BY_UPVEST", "PORTFOLIO_IS_BALANCED", "SELL_LIMIT_EXCEEDED" ] }, "cancellation_details": { "type": "string" } }, "required": [ "id", "created_at", "updated_at", "account_id", "cash_amount", "currency", "status", "post_tax", "client_reference", "initiation_flow", "orders" ], "additionalProperties": false }, "example": { "id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c", "created_at": "2021-07-21T14:10:00.000Z", "updated_at": "2021-07-21T14:10:00.000Z", "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3", "allocation_id": "eb68abce-29f4-483f-a384-7f243e77851f", "cash_amount": "1000", "currency": "EUR", "status": "NEW", "type": "BUY", "post_tax": false, "client_reference": "", "initiation_flow": "API", "orders": [] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/portfolios/orders/{portfolio_order_id}": { "parameters": [ { "name": "portfolio_order_id", "in": "path", "required": true, "description": "The unique identifier of the portfolio order. Universally Unique Identifier (UUID).", "schema": { "title": "Portfolios order unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio order.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_portfolios_order", "summary": "Retrieve portfolios order", "description": "Retrieves a portfolio order by its ID, including the status and details of each underlying instrument order.\n\nSee the Portfolios guide ([TOL](https://docs.upvest.co/products/tol/guides/portfolios) / [BYOL](https://docs.upvest.co/products/byol/guides/portfolios)) for order lifecycle details.", "tags": [ "Portfolios" ], "security": [ { "oauth-client-credentials": [ "portfolios:read", "portfolios:admin" ] } ], "responses": { "200": { "description": "Portfolios order", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Portfolios order", "type": "object", "description": "Represents a portfolio order — a BUY or SELL instruction that invests or withdraws a cash amount distributed across all instruments in the account's current allocation.", "properties": { "id": { "title": "Portfolios order unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio order.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "allocation_id": { "title": "Portfolio allocation unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio allocation.", "format": "uuid" }, "cash_amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "status": { "type": "string", "description": "Execution status of the Portfolio Order.\n* NEW - \n* PROCESSING - \n* FILLED - \n* SETTLED - \n* CANCELLED - ", "enum": [ "NEW", "PROCESSING", "FILLED", "SETTLED", "CANCELLED" ] }, "type": { "type": "string", "description": "Type of the Portfolio Order.\n* BUY - \n* SELL - \n* REBALANCING - ", "enum": [ "BUY", "SELL", "REBALANCING" ] }, "post_tax": { "type": "boolean", "description": "Cash amount is post-tax value", "default": false }, "orders": { "type": "array", "description": "Orders associated with this portfolio order", "items": { "title": "Portfolios order", "type": "object", "description": "An individual instrument order within a portfolio order, representing the BUY or SELL of a single instrument.", "properties": { "id": { "title": "Order unique identifier", "type": "string", "description": "Unique identifier for an order. Universally Unique Identifier (UUID).", "format": "uuid" }, "side": { "type": "string", "description": "Side of the portfolio order.\n* BUY - \n* SELL - ", "enum": [ "BUY", "SELL" ] }, "status": { "type": "string", "description": "The execution status of the order.\n* NEW — the order has been received and validated, awaiting routing.\n* PROCESSING — the order is being routed for execution.\n* FILLED — the order has been fully executed.\n* CANCELLED — the order was cancelled before being fully executed.", "enum": [ "NEW", "PROCESSING", "FILLED", "CANCELLED" ] } }, "required": [ "id", "side", "status" ], "additionalProperties": false } }, "client_reference": { "title": "An ID provided by the client", "type": "string", "description": "A reference string provided by the client to correlate the portfolio order with a record in the client's own system." }, "initiation_flow": { "title": "Initiation flow used during order creation", "description": "What triggered the order creation .\n* API - \n* SAVINGS_PLAN - ", "type": "string", "enum": [ "API", "SAVINGS_PLAN" ] }, "cancellation_reason": { "title": "Cancellation reason code", "description": "Explains the reason why the order was cancelled .\n* ACCOUNT_IS_EMPTY - \n* CANCELLED_BY_CLIENT - \n* CANCELLED_BY_UPVEST - \n* PORTFOLIO_IS_BALANCED - \n* SELL_LIMIT_EXCEEDED - ", "type": "string", "enum": [ "ACCOUNT_IS_EMPTY", "CANCELLED_BY_CLIENT", "CANCELLED_BY_UPVEST", "PORTFOLIO_IS_BALANCED", "SELL_LIMIT_EXCEEDED" ] }, "cancellation_details": { "type": "string" } }, "required": [ "id", "created_at", "updated_at", "account_id", "cash_amount", "currency", "status", "post_tax", "client_reference", "initiation_flow", "orders" ], "additionalProperties": false }, "examples": { "ordinary": { "summary": "Ordinary", "value": { "id": "29bc9a26-a6ee-47a3-b609-47d30a737afc", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "user_id": "4b9732bd-7496-4e91-8a5f-6360479d7fed", "account_id": "f2f7d2c7-d79b-4de2-ae9b-d01646259f9e", "allocation_id": "19a902ac-1c01-4c45-bd5d-62fd496805c8", "cash_amount": "100.00", "currency": "EUR", "status": "PROCESSING", "type": "BUY", "client_reference": "fd1ae99e-772a-11ee-b962-0242ac120002", "initiation_flow": "SAVINGS_PLAN", "post_tax": false, "orders": [ { "id": "79f2c816-13ed-4588-85e6-f3398b0b5825", "side": "BUY", "status": "NEW" }, { "id": "44f50a4e-7ce8-4eae-a078-f4b3d8ab4708", "side": "BUY", "status": "NEW" } ] } }, "rebalancing": { "summary": "Rebalancing", "value": { "id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c", "created_at": "2021-07-21T14:10:00.000Z", "updated_at": "2021-07-21T14:10:00.000Z", "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3", "allocation_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3", "cash_amount": "0", "currency": "EUR", "status": "PROCESSING", "type": "REBALANCING", "client_reference": "", "initiation_flow": "API", "post_tax": false, "orders": [ { "id": "e7aecb80-5e84-4bf7-984b-b39ab77eb0a8", "side": "SELL", "status": "NEW" }, { "id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c", "side": "SELL", "status": "PROCESSING" }, { "id": "d8a85120-2941-4ed6-8d57-e80401a4779c", "side": "SELL", "status": "FILLED" } ] } }, "cancelled": { "summary": "Cancelled", "value": { "id": "29bc9a26-a6ee-47a3-b609-47d30a737afc", "created_at": "2021-07-21T14:10:00.000Z", "updated_at": "2021-07-21T14:10:00.000Z", "user_id": "4b9732bd-7496-4e91-8a5f-6360479d7fed", "account_id": "f2f7d2c7-d79b-4de2-ae9b-d01646259f9e", "allocation_id": "19a902ac-1c01-4c45-bd5d-62fd496805c8", "cash_amount": "100.00", "currency": "EUR", "status": "CANCELLED", "type": "BUY", "client_reference": "fd1ae99e-772a-11ee-b962-0242ac120002", "initiation_flow": "API", "post_tax": false, "cancellation_reason": "CANCELLED_BY_CLIENT", "cancellation_details": "Cancelled as a result of client's request.", "orders": [] } } } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "delete": { "operationId": "cancel_portfolios_order", "summary": "Cancel portfolios order", "description": "Cancel portfolios order. Cancellations may not be possible - in rare situations, some individual orders within portfolios order may already have been filled. In this case, cancellation could result in a mix of cancelled and filled orders.", "tags": [ "Portfolios" ], "security": [ { "oauth-client-credentials": [ "portfolios:admin" ] } ], "responses": { "202": { "description": "The request has been successfully accepted and will be processed asynchronously.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/portfolios/rebalancings/executions": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "post": { "operationId": "trigger_portfolio_rebalancing", "summary": "Trigger portfolio rebalancing", "description": "Triggers an immediate rebalancing execution for all accounts linked to the specified allocation.\n\nThe rebalancing adjusts each account's positions to match the current target allocation weights. In rare situations, individual orders within the rebalancing may not be cancellable once submitted.\n\nSee the Portfolios rebalancing guide ([TOL](https://docs.upvest.co/products/tol/guides/portfolios/rebalancing/rebalancing) / [BYOL](https://docs.upvest.co/products/byol/guides/portfolios/rebalancing/rebalancing)) for implementation details.", "tags": [ "Portfolios Rebalancing" ], "security": [ { "oauth-client-credentials": [ "portfolios:admin" ] } ], "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$", "example": "ccb07f42-4104-44ad-8e1f-c660bb7b269c" }, "description": "A UUID to be used as an idempotency key. This prevents a duplicate request from being replayed.\nhttps://docs.upvest.co/documentation/concepts/api_concepts/idempotency\n" } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Trigger portfolio rebalancing - Request", "oneOf": [ { "title": "Accounts", "type": "object", "properties": { "accounts": { "type": "array", "description": "List of accounts", "items": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" } } }, "required": [ "accounts" ], "additionalProperties": false }, { "title": "Allocations", "type": "object", "properties": { "allocations": { "type": "array", "description": "List of allocations", "items": { "title": "Portfolio allocation unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio allocation.", "format": "uuid" } } }, "required": [ "allocations" ], "additionalProperties": false } ] }, "examples": { "accounts": { "summary": "Accounts", "value": { "accounts": [ "43801b85-bbcf-41c7-8389-b018082a5ec5", "20151679-c159-4f16-b8a2-267b3d968c6f" ] } }, "allocations": { "summary": "Allocations", "value": { "allocations": [ "eafa39e3-7837-476f-8af1-49fa604e3f49" ] } } } } } }, "responses": { "200": { "description": "Portfolio", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Trigger portfolio rebalancing - Response", "type": "object", "description": "Response returned after triggering a portfolio rebalancing, containing the `id` of the rebalancing execution created.", "properties": { "id": { "title": "Portfolio rebalancing execution unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio rebalancing execution.", "format": "uuid" } }, "required": [ "id" ], "additionalProperties": false }, "example": { "id": "735381ce-8380-4b07-9e42-97e2b6d3643e" } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/portfolios/rebalancings/executions/{execution_id}": { "parameters": [ { "name": "execution_id", "description": "The unique identifier of the order execution. Universally Unique Identifier (UUID).", "in": "path", "required": true, "schema": { "title": "Order execution unique identifier", "type": "string", "description": "Unique identifier for an order execution. Universally Unique Identifier (UUID).", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_portfolios_rebalancing_execution", "summary": "Retrieve portfolios rebalancing execution", "description": "Retrieve portfolios rebalancing execution", "tags": [ "Portfolios Rebalancing" ], "security": [ { "oauth-client-credentials": [ "portfolios:read", "portfolios:admin" ] } ], "responses": { "200": { "description": "Portfolios", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Portfolios rebalancing execution", "type": "object", "description": "Represents a rebalancing execution — a batch event that rebalances one or more accounts to match their target allocations. Contains references to the affected accounts and allocations.", "properties": { "id": { "title": "Portfolios order unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio order.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "accounts": { "type": "array", "description": "Accounts associated with this rebalancing execution", "items": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" } }, "allocations": { "type": "array", "description": "Allocations associated with this rebalancing execution", "items": { "title": "Portfolio allocation unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio allocation.", "format": "uuid" } } }, "required": [ "id", "created_at", "updated_at" ], "additionalProperties": false }, "example": { "id": "735381ce-8380-4b07-9e42-97e2b6d3643e", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "accounts": [ "43801b85-bbcf-41c7-8389-b018082a5ec5", "20151679-c159-4f16-b8a2-267b3d968c6f" ], "allocations": [] } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "405": { "description": "Method Not Allowed. The requested method is not allowed on the requested resource.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 405, "type": "method_not_allowed" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/portfolios/rebalancings/executions/{execution_id}/orders": { "parameters": [ { "name": "execution_id", "description": "The unique identifier of the order execution. Universally Unique Identifier (UUID).", "in": "path", "required": true, "schema": { "title": "Order execution unique identifier", "type": "string", "description": "Unique identifier for an order execution. Universally Unique Identifier (UUID).", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_portfolio_rebalancing_execution_orders", "summary": "List portfolio rebalancing execution orders", "description": "List portfolio rebalancing execution orders", "tags": [ "Portfolios Rebalancing" ], "security": [ { "oauth-client-credentials": [ "portfolios:read", "portfolios:admin" ] } ], "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "status" ], "default": "status" }, "description": "Sort the result by `status`." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. By default, only ASC for ascending sort." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "title": "Date in YYYY-MM-DD format. RFC 3339, section 5.6" }, "description": "Returns rebalancing orders with dates starting from and including this date (UTC)", "example": "2022-10-14T10:10:10Z" }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "title": "Date in YYYY-MM-DD format. RFC 3339, section 5.6" }, "description": "Returns rebalancing orders with dates up until this date (UTC)", "example": "2022-10-14T10:10:10Z" } ], "responses": { "200": { "description": "Portfolios", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Portfolios rebalancing execution order - List - Response", "type": "object", "description": "Paginated list of rebalancing execution orders for a given rebalancing execution, including cursor-based pagination metadata.", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "items": { "title": "Portfolios rebalancing execution order", "type": "object", "description": "An individual account-level order within a rebalancing execution. Each entry corresponds to a single account being rebalanced and has its own status lifecycle.", "properties": { "id": { "title": "Rebalancing execution order unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a rebalancing execution order.", "format": "uuid" }, "execution_id": { "title": "Portfolio rebalancing execution unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio rebalancing execution.", "format": "uuid" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "portfolio_order_id": { "oneOf": [ { "title": "Portfolios order unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio order.", "format": "uuid" }, { "type": "null" } ] }, "status": { "type": "string", "description": "Status of the Rebalancing Execution Order.\n* NEW - \n* PROCESSING - \n* FILLED - \n* CANCELLED - ", "enum": [ "NEW", "PROCESSING", "FILLED", "CANCELLED" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "cancellation_reason": { "type": "string", "description": "Reason for Rebalancing Execution Order Cancellation. The field is present in case the Order has a status of CANCELLED.\n* ACCOUNT_IS_EMPTY - \n* ACCOUNT_NOT_FOUND - \n* CANCELLED_BY_CLIENT - \n* CANCELLED_BY_UPVEST - \n* CONFIGURATION_IS_MISSING - \n* INVALID_ACCOUNT_TYPE - \n* PORTFOLIO_IS_BALANCED - \n* UNKNOWN - ", "enum": [ "ACCOUNT_IS_EMPTY", "ACCOUNT_NOT_FOUND", "CANCELLED_BY_CLIENT", "CANCELLED_BY_UPVEST", "CONFIGURATION_IS_MISSING", "INVALID_ACCOUNT_TYPE", "PORTFOLIO_IS_BALANCED", "UNKNOWN" ] }, "cancellation_details": { "type": "string" } }, "required": [ "id", "execution_id", "account_id", "portfolio_order_id", "status", "created_at", "updated_at" ], "additionalProperties": false } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "example": { "meta": { "count": 2, "limit": 10, "offset": 0, "order": "ASC", "sort": "state", "total_count": 2 }, "data": [ { "id": "adf706aa-4fac-4e1d-878b-5b225f7b7354", "created_at": "2022-09-28T09:14:02Z", "updated_at": "2022-09-28T09:14:02Z", "execution_id": "edc74b48-a377-4b93-84fb-543b1137de05", "account_id": "100bb408-149c-4e6f-8697-837c2a144a29", "portfolio_order_id": "b31723e0-8c8c-4bd0-a962-8bd26c5aee4d", "status": "FILLED" }, { "id": "1dd8cede-a326-43b3-a54c-9d2d0e80edb5", "created_at": "2022-09-28T09:14:02Z", "updated_at": "2022-09-28T09:14:02Z", "execution_id": "f678fe2b-ffd8-4b99-844f-a8f78a67e528", "account_id": "98b21a45-5ea0-481f-bb1e-880aab0d154d", "portfolio_order_id": "411c625e-b2f4-4af4-ac21-e17846fb6bcc", "status": "PROCESSING" }, { "id": "1bf46252-ad90-4e22-8717-9586d2b86327", "created_at": "2022-09-28T09:14:02Z", "updated_at": "2022-09-28T09:14:02Z", "execution_id": "9275e08d-012f-40bd-80b7-58037bdc7ab6", "portfolio_order_id": null, "account_id": "98b21a45-5ea0-481f-bb1e-880aab0d154d", "status": "NEW" }, { "id": "1bf46252-ad90-4e22-8717-9586d2b86327", "created_at": "2022-09-28T09:14:02Z", "updated_at": "2022-09-28T09:14:02Z", "execution_id": "9275e08d-012f-40bd-80b7-58037bdc7ab6", "portfolio_order_id": null, "account_id": "98b21a45-5ea0-481f-bb1e-880aab0d154d", "status": "CANCELLED", "cancellation_reason": "PORTFOLIO_IS_BALANCED", "cancellation_details": "Portfolio is balanced, no need to rebalance." } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "405": { "description": "Method Not Allowed. The requested method is not allowed on the requested resource.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 405, "type": "method_not_allowed" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/portfolios/allocations/{allocation_id}/accounts": { "parameters": [ { "name": "allocation_id", "in": "path", "required": true, "description": "The unique identifier of the portfolio allocation. Universally Unique Identifier (UUID).", "schema": { "title": "Portfolio allocation unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio allocation.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_portfolios_allocation_accounts", "summary": "List portfolios allocation accounts", "description": "Returns a paginated list of accounts associated with a specific portfolio allocation.\n\nSee the Portfolios guide ([TOL](https://docs.upvest.co/products/tol/guides/portfolios) / [BYOL](https://docs.upvest.co/products/byol/guides/portfolios)) for implementation details.", "tags": [ "Portfolios" ], "security": [ { "oauth-client-credentials": [ "portfolios:read", "portfolios:admin" ] } ], "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "id" ], "default": "id" }, "description": "Sort the result by `id`." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. By default, only ASC for ascending sort." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." } ], "responses": { "200": { "description": "Portfolios allocation accounts", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Portfolios allocation accounts - List - Response", "type": "object", "description": "Paginated list of accounts associated with a portfolio allocation, including cursor-based pagination metadata.", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "items": { "title": "Portfolios allocation account", "type": "object", "description": "An account associated with a portfolio allocation, identified by its account UUID.", "properties": { "id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" } }, "required": [ "id" ], "additionalProperties": false } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "example": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1, "sort": "id", "order": "ASC" }, "data": [ { "id": "81d6e710-37e6-4a5a-9877-ef5bb6d717e3" } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "405": { "description": "Method Not Allowed. The requested method is not allowed on the requested resource.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 405, "type": "method_not_allowed" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/accounts/{account_id}/valuations/current": { "parameters": [ { "name": "account_id", "in": "path", "required": true, "description": "The unique identifier of the account. Universally Unique Identifier (UUID).", "schema": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "get_account_valuation", "summary": "Get current valuation for an account", "description": "Get current valuation for an account", "tags": [ "Valuations" ], "security": [ { "oauth-client-credentials": [ "valuations:read" ] } ], "parameters": [ { "name": "price_quality", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "EOD", "HIGHEST_AVAILABLE" ], "description": "Defines the quality of the price used in the valuation." } } ], "responses": { "200": { "description": "Valuations", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Account Valuation", "type": "object", "properties": { "id": { "title": "Account valuation unique identifier", "description": "Account valuation unique identifier.", "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "total_security_value": { "title": "Total security value", "description": "Entity representing the monetary value by amount and currency.", "type": "object", "properties": { "amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] } }, "required": [ "amount", "currency" ], "additionalProperties": false }, "price_quality": { "type": "string", "description": "The requested price quality.\n* EOD - End of day prices\n* HIGHEST_AVAILABLE - The most recent available prices", "enum": [ "EOD", "HIGHEST_AVAILABLE" ] }, "security_positions": { "type": "array", "description": "Positions associated with this account valuation.", "items": { "title": "Account valuation security position", "type": "object", "properties": { "instrument": { "title": "Instrument", "description": "Entity representing the financial instrument.", "type": "object", "properties": { "uuid": { "description": "String representing the instrument internal identifier.", "type": "string", "format": "uuid" }, "isin": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" } }, "required": [ "uuid" ], "additionalProperties": false }, "quantity": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,10})?$" }, { "description": "Total quantity of the instrument (10 decimal places)." } ] }, "value": { "nullable": true, "allOf": [ { "title": "Security position value", "description": "Entity representing the monetary value by amount and currency, and the time of the price used.", "type": "object", "properties": { "amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "price_time": { "type": "string", "format": "date-time", "description": "The date and time of the price used for the calculation. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" } }, "required": [ "amount", "currency", "price_time" ], "additionalProperties": false }, { "nullable": true } ] }, "weight": { "description": "Total weight of the instrument (10 decimal places).", "oneOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,10})?$" }, { "type": "null" } ] }, "price_quality": { "type": "string", "description": "The price quality used for the calculation of the value of the position.\n* EOD - end of day price\n* REALTIME - realtime price\n* DELAYED - delayed price\n* NA - no available price", "enum": [ "EOD", "REALTIME", "DELAYED", "NA" ] } }, "required": [ "instrument", "quantity", "value", "weight" ], "additionalProperties": false } }, "valuation_time": { "type": "string", "format": "date-time", "description": "Date and time as of which the value was calculated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" } }, "required": [ "id", "account_id", "created_at", "updated_at", "valuation_time", "total_security_value", "price_quality", "security_positions" ], "additionalProperties": false }, "example": { "id": "404b170a-9042-11ed-9a51-2eabd0c03f8a", "created_at": "2023-01-10T14:15:22Z", "updated_at": "2023-01-10T14:15:22Z", "valuation_time": "2023-01-10T14:15:22Z", "account_id": "51cdc0cc-9042-11ed-b017-2eabd0c03f8a", "price_quality": "EOD", "total_security_value": { "amount": "142.29", "currency": "EUR" }, "security_positions": [ { "instrument": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "isin": "DE0007664005" }, "value": { "amount": "104.81", "currency": "EUR", "price_time": "2023-01-09T09:20:00Z" }, "quantity": "0.65", "weight": "0.736595", "price_quality": "EOD" }, { "instrument": { "uuid": "48b798b7-3a62-4f30-8307-ee94d35b21b7", "isin": "FR0010524777" }, "value": { "amount": "37.48", "currency": "EUR", "price_time": "2023-01-09T09:20:00Z" }, "quantity": "1.00", "weight": "0.263405", "price_quality": "EOD" }, { "instrument": { "uuid": "7499ccf8-6fa5-43ef-af9e-dd062e10ab59", "isin": "SE0019889775" }, "quantity": "5.00", "value": null, "weight": null, "price_quality": "NA" } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/accounts/{account_id}/valuations": { "parameters": [ { "name": "account_id", "in": "path", "required": true, "description": "The unique identifier of the account. Universally Unique Identifier (UUID).", "schema": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_account_valuation_history", "summary": "List valuation history for an account", "description": "List valuation history for an account", "tags": [ "Valuations" ], "security": [ { "oauth-client-credentials": [ "valuations:read" ] } ], "parameters": [ { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "title": "Date in YYYY-MM-DD format. RFC 3339, section 5.6", "description": "Returns account valuations starting from and including this date (UTC)" }, "example": "2023-01-03" }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "title": "Date in YYYY-MM-DD format. RFC 3339, section 5.6", "description": "Returns account valuations up until this date (UTC)" }, "example": "2023-01-11" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "valuation_time" ], "default": "valuation_time" }, "description": "Sort the result by `valuation_time`." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." } ], "responses": { "200": { "description": "Valuations", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Account Valuation - List - Response", "type": "object", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "items": { "title": "Account Valuation", "type": "object", "properties": { "id": { "title": "Account valuation unique identifier", "description": "Account valuation unique identifier.", "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "total_security_value": { "title": "Total security value", "description": "Entity representing the monetary value by amount and currency.", "type": "object", "properties": { "amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] } }, "required": [ "amount", "currency" ], "additionalProperties": false }, "price_quality": { "type": "string", "description": "The requested price quality.\n* EOD - End of day prices\n* HIGHEST_AVAILABLE - The most recent available prices", "enum": [ "EOD", "HIGHEST_AVAILABLE" ] }, "security_positions": { "type": "array", "description": "Positions associated with this account valuation.", "items": { "title": "Account valuation security position", "type": "object", "properties": { "instrument": { "title": "Instrument", "description": "Entity representing the financial instrument.", "type": "object", "properties": { "uuid": { "description": "String representing the instrument internal identifier.", "type": "string", "format": "uuid" }, "isin": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" } }, "required": [ "uuid" ], "additionalProperties": false }, "quantity": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,10})?$" }, { "description": "Total quantity of the instrument (10 decimal places)." } ] }, "value": { "nullable": true, "allOf": [ { "title": "Security position value", "description": "Entity representing the monetary value by amount and currency, and the time of the price used.", "type": "object", "properties": { "amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "price_time": { "type": "string", "format": "date-time", "description": "The date and time of the price used for the calculation. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" } }, "required": [ "amount", "currency", "price_time" ], "additionalProperties": false }, { "nullable": true } ] }, "weight": { "description": "Total weight of the instrument (10 decimal places).", "oneOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,10})?$" }, { "type": "null" } ] }, "price_quality": { "type": "string", "description": "The price quality used for the calculation of the value of the position.\n* EOD - end of day price\n* REALTIME - realtime price\n* DELAYED - delayed price\n* NA - no available price", "enum": [ "EOD", "REALTIME", "DELAYED", "NA" ] } }, "required": [ "instrument", "quantity", "value", "weight" ], "additionalProperties": false } }, "valuation_time": { "type": "string", "format": "date-time", "description": "Date and time as of which the value was calculated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" } }, "required": [ "id", "account_id", "created_at", "updated_at", "valuation_time", "total_security_value", "price_quality", "security_positions" ], "additionalProperties": false } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "example": { "meta": { "offset": 0, "limit": 100, "count": 3, "total_count": 3, "sort": "created_at", "order": "ASC" }, "data": [ { "id": "404b170a-9042-11ed-9a51-2eabd0c03f8a", "created_at": "2023-01-10T14:15:22Z", "updated_at": "2023-01-10T14:15:22Z", "valuation_time": "2023-01-10T14:15:22Z", "account_id": "51cdc0cc-9042-11ed-b017-2eabd0c03f8a", "price_quality": "EOD", "total_security_value": { "amount": "142.29", "currency": "EUR" }, "security_positions": [ { "instrument": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "isin": "DE0007664005" }, "value": { "amount": "104.81", "currency": "EUR", "price_time": "2023-01-09T09:20:00Z" }, "quantity": "0.65", "weight": "0.736595" }, { "instrument": { "uuid": "48b798b7-3a62-4f30-8307-ee94d35b21b7", "isin": "FR0010524777" }, "value": { "amount": "37.48", "currency": "EUR", "price_time": "2023-01-09T09:20:00Z" }, "quantity": "1.00", "weight": "0.263405" }, { "instrument": { "uuid": "7499ccf8-6fa5-43ef-af9e-dd062e10ab59", "isin": "SE0019889775" }, "quantity": "5.00", "value": null, "weight": null } ] }, { "id": "adfbf024-3d31-11ef-b99b-2eabd0c03f8a", "created_at": "2023-01-11T14:15:22Z", "updated_at": "2023-01-11T14:15:22Z", "valuation_time": "2023-01-11T14:15:22Z", "account_id": "51cdc0cc-9042-11ed-b017-2eabd0c03f8a", "price_quality": "EOD", "total_security_value": { "amount": "104.81", "currency": "EUR" }, "security_positions": [ { "instrument": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "isin": "DE0007664005" }, "value": { "amount": "104.81", "currency": "EUR", "price_time": "2023-01-10T09:20:00Z" }, "quantity": "0.65", "weight": "1" } ] }, { "id": "be38000e-3d31-11ef-ac4e-2eabd0c03f8a", "created_at": "2023-01-12T14:15:22Z", "updated_at": "2023-01-12T14:15:22Z", "valuation_time": "2023-01-12T14:15:22Z", "account_id": "51cdc0cc-9042-11ed-b017-2eabd0c03f8a", "price_quality": "EOD", "total_security_value": { "amount": "0", "currency": "EUR" }, "security_positions": [] } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "405": { "description": "Method Not Allowed. The requested method is not allowed on the requested resource.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 405, "type": "method_not_allowed" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/transactions/cash": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_cash_transactions", "summary": "List cash transactions", "description": "List cash transactions", "tags": [ "Transactions" ], "security": [ { "oauth-client-credentials": [ "transactions:read" ] } ], "parameters": [ { "name": "account_group_id", "in": "query", "required": false, "schema": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "description": "Filters the list to show only transactions associated with a certain account group ID.", "example": "413715f2-5401-4b97-8055-034a6b879f8c" }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "title": "Date in YYYY-MM-DD format. RFC 3339, section 5.6", "description": "Returns transactions starting from and including this date (UTC).", "example": "2023-01-03" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "title": "Date in YYYY-MM-DD format. RFC 3339, section 5.6", "description": "Returns transactions up until this date (UTC)", "example": "2023-01-11" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "booking_date" ], "default": "booking_date" }, "description": "Sort the result by `booking_date`." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." } ], "responses": { "200": { "description": "Cash Transactions", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Cash transaction - List - Response", "type": "object", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "items": { "title": "Cash Transaction", "type": "object", "properties": { "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "booking_date": { "title": " Transaction booking date", "type": "string", "description": " Transaction booking date and time. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "delta": { "title": "Cash transaction delta", "description": "Entity representing cash transaction delta.", "type": "object", "properties": { "amount": { "type": "string", "pattern": "^-?[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling\n* USD - The United States dollar", "enum": [ "EUR", "GBP", "USD" ] } }, "required": [ "amount", "currency" ], "additionalProperties": false }, "id": { "title": "Cash transaction unique identifier", "type": "string", "description": "Cash transaction unique identifier.", "format": "uuid" }, "instrument": { "title": "Instrument", "description": "Entity representing instrument.", "type": "object", "properties": { "uuid": { "description": "Internal instrument identifier.", "type": "string", "format": "uuid" }, "isin": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" } }, "required": [ "uuid" ], "additionalProperties": false }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "taxes": { "type": "array", "items": { "title": "Transaction tax", "description": "Entity representing the transaction tax.", "type": "object", "properties": { "amount": { "type": "string", "pattern": "^-?[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling\n* USD - The United States dollar", "enum": [ "EUR", "GBP", "USD" ] }, "type": { "type": "string", "description": "Type of the tax.\n* TOTAL - Total taxes", "enum": [ "TOTAL" ], "default": "TOTAL" } }, "required": [ "amount", "currency", "type" ], "additionalProperties": false } }, "taxes_details": { "title": "Transaction taxes details", "description": "Entity representing the transaction taxes details.", "type": "object", "properties": { "total_amount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^-?[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling\n* USD - The United States dollar", "enum": [ "EUR", "GBP", "USD" ] } }, "required": [ "amount", "currency" ] }, "tax_breakdown": { "type": "array", "items": { "title": "Transaction tax", "description": "Entity representing the transaction tax.", "type": "object", "properties": { "amount": { "type": "string", "pattern": "^-?[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling\n* USD - The United States dollar", "enum": [ "EUR", "GBP", "USD" ] }, "type": { "type": "string", "description": "Type of the tax.", "enum": [ "CAPITAL_GAINS", "CHURCH_TAX", "SOLIDARITY_SURCHARGE", "FINANCIAL_TRANSACTION_TAX", "STAMP_DUTY", "INTERNATIONAL_WITHHOLDING_TAX" ] }, "taxing_jurisdiction": { "description": "Country code. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "pattern": "^[A-Z]{2}$" } }, "required": [ "amount", "currency", "type", "taxing_jurisdiction" ], "additionalProperties": false } } }, "required": [ "total_amount", "tax_breakdown" ], "additionalProperties": false }, "fees": { "type": "array", "items": { "title": "Transaction fee", "description": "Entity representing the transaction fee.", "type": "object", "properties": { "amount": { "type": "string", "pattern": "^-?[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling\n* USD - The United States dollar", "enum": [ "EUR", "GBP", "USD" ] }, "type": { "type": "string", "description": "Type of the fee.\n* TOTAL - Total fees", "enum": [ "TOTAL" ], "default": "TOTAL" }, "charge_method": { "type": "string", "description": "Indicates whether the fee was charged by client or by other methods.\n* CHARGED_BY_CLIENT - Charged by client\n* COLLECTED_BY_UPVEST - Charged by client and collected by Upvest", "enum": [ "CHARGED_BY_CLIENT", "COLLECTED_BY_UPVEST" ] } }, "required": [ "amount", "currency", "type", "charge_method" ], "additionalProperties": false } }, "references": { "type": "array", "items": { "title": "Cash transaction reference", "description": "Entity representing cash transaction reference.", "type": "object", "properties": { "id": { "title": "Unique identifier for a resource of given type", "type": "string", "description": "Unique identifier for a resource of given type.", "format": "uuid" }, "type": { "type": "string", "description": "Type of the reference.\n* ACCOUNT_GROUP - Account group\n* CASH_BALANCE_TRANSFER - Cash balance transfer\n* CORPORATE_ACTION - Corporate action\n* CORPORATE_ACTION_TRANSACTION_ID - Corporate action transaction ID\n* CREDIT_FUNDING - Credit Funding\n* DIRECT_DEBIT - Direct debit funding request\n* FEE_COLLECTION - Fee collection\n* ISA_TRANSFER - ISA transfer\n* ORDER - Order\n* ORDER_EXECUTION - Order execution\n* TAX_TRANSACTION - Tax transaction\n* TOPUP - Cash top up\n* TRANSACTION_FEE_EXECUTION - Transaction fee execution\n* VIRTUAL_CASH_DECREASE - Virtual cash decreased\n* VIRTUAL_CASH_INCREASE - Virtual cash increased\n* WITHDRAWAL - Cash withdrawal", "enum": [ "ACCOUNT_GROUP", "CASH_BALANCE_TRANSFER", "CORPORATE_ACTION", "CORPORATE_ACTION_TRANSACTION_ID", "CREDIT_FUNDING", "DIRECT_DEBIT", "FEE_COLLECTION", "ISA_TRANSFER", "ORDER", "ORDER_EXECUTION", "TAX_TRANSACTION", "TOPUP", "TRANSACTION_FEE_EXECUTION", "VIRTUAL_CASH_DECREASE", "VIRTUAL_CASH_INCREASE", "WITHDRAWAL" ] } }, "required": [ "id", "type" ], "additionalProperties": false } }, "type": { "title": "Transaction type", "description": "Transaction type\n* ACCUMULATION - Accumulation\n* ACCUMULATION_CANCELLATION - Accumulation cancellation\n* ANNUAL_GENERAL_MEETING - Annual general meeting\n* ANNUAL_GENERAL_MEETING_CANCELLATION - Annual general meeting cancellation\n* ATTACHMENT - Attachment\n* ATTACHMENT_CANCELLATION - Attachment cancellation\n* BALANCE_CORRECTION - Balance correction\n* BALANCE_CORRECTION_CANCELLATION - Balance correction cancellation\n* BANKRUPTCY - Bankruptcy\n* BANKRUPTCY_CANCELLATION - Bankruptcy cancellation\n* BOND_DEFAULT - Bond default\n* BOND_DEFAULT_CANCELLATION - Bond default cancellation\n* BOND_HOLDER_MEETING - Bond holder meeting\n* BOND_HOLDER_MEETING_CANCELLATION - Bond holder meeting cancellation\n* BONUS_ISSUE - Bonus Issue/Capitalisation Issue\n* BONUS_ISSUE_CANCELLATION - Bonus Issue/Capitalisation Issue, Cancellation\n* CALL_ON_INTERMEDIATE_SECURITIES - Call on Intermediate Securities\n* CALL_ON_INTERMEDIATE_SECURITIES_CANCELLATION - Call on Intermediate Securities cancellation\n* CAPITAL_DISTRIBUTION - Capital distribution\n* CAPITAL_DISTRIBUTION_CANCELLATION - Capital distribution cancellation\n* CAPITAL_GAINS_DISTRIBUTION - Capital gains distribution\n* CAPITAL_GAINS_DISTRIBUTION_CANCELLATION - Capital gains distribution cancellation\n* CAPITALISATION - Capitalisation\n* CAPITALISATION_CANCELLATION - Capitalisation cancellation\n* CASH_DISTRIBUTION_FROM_NON_ELIGIBLE_SECURITIES_SALES - Cash distribution from non eligible securities sales\n* CASH_DISTRIBUTION_FROM_NON_ELIGIBLE_SECURITIES_SALES_CANCELLATION - Cash distribution from non eligible securities sales cancellation\n* CASH_DIVIDEND - Cash dividend\n* CASH_DIVIDEND_CANCELLATION - Cash dividend cancellation\n* CHANGE - Change\n* CHANGE_CANCELLATION - Change, Cancellation\n* CLASS_ACTION - Class action\n* CLASS_ACTION_CANCELLATION - Class action cancellation\n* COMPANY_OPTION - Company option\n* COMPANY_OPTION_CANCELLATION - Company option cancellation\n* CONSENT - Consent\n* CONSENT_CANCELLATION - Consent cancellation\n* CONVERSION - Conversion\n* CONVERSION_CANCELLATION - Conversion cancellation\n* COURT_MEETING - Court meeting\n* COURT_MEETING_CANCELLATION - Court meeting cancellation\n* CREDIT_EVENT - Credit event\n* CREDIT_EVENT_CANCELLATION - Credit event cancellation\n* CREDIT_FUNDING - Credit funding\n* CREDIT_FUNDING_CHARGE_BACK - Credit funding charge back\n* DD_REFUND_REJECT_FEE - Direct debit refund reject fee\n* DD_REFUND_REJECT_FEE_CANCELLATION - Direct debit refund reject fee cancellation\n* DECREASE_IN_VALUE - Decrease in Value\n* DECREASE_IN_VALUE_CANCELLATION - Decrease in Value, Cancellation\n* DETACHMENT - Detachment\n* DETACHMENT_CANCELLATION - Detachment cancellation\n* DISCLOSURE - Disclosure\n* DISCLOSURE_CANCELLATION - Disclosure cancellation\n* DIVIDEND_OPTION - Dividend Option\n* DIVIDEND_OPTION_CANCELLATION - Dividend Option, Cancellation\n* DIVIDEND_REINVESTMENT - Dividend Reinvestment\n* DIVIDEND_REINVESTMENT_CANCELLATION - Dividend Reinvestment, Cancellation\n* DRAWING - Drawing\n* DRAWING_CANCELLATION - Drawing cancellation\n* DUTCH_AUCTION - Dutch Auction\n* DUTCH_AUCTION_CANCELLATION - Dutch Auction, Cancellation\n* EXCHANGE - Exchange\n* EXCHANGE_CANCELLATION - Exchange cancellation\n* EXTRAORDINARY_OR_SPECIAL_GENERAL_MEETING - Extraordinary or special general meeting\n* EXTRAORDINARY_OR_SPECIAL_GENERAL_MEETING_CANCELLATION - Extraordinary or special general meeting cancellation\n* FEE_COLLECTION - Fee collection\n* FEE_COLLECTION_CANCELLATION - Fee collection cancellation\n* FINAL_MATURITY - Final maturity\n* FINAL_MATURITY_CANCELLATION - Final maturity cancellation\n* FULL_CALL - Full call\n* FULL_CALL_CANCELLATION - Full call cancellation\n* INCREASE_IN_VALUE - Increase in Value\n* INCREASE_IN_VALUE_CANCELLATION - Increase in Value, Cancellation\n* INFORMATION - Information\n* INFORMATION_CANCELLATION - Information cancellation\n* INSTALMENT_CALL - Instalment call\n* INSTALMENT_CALL_CANCELLATION - Instalment call cancellation\n* INTEREST_PAYMENT - Interest payment\n* INTEREST_PAYMENT_CANCELLATION - Interest payment cancellation\n* INTERMEDIATE_SECURITIES_DISTRIBUTION - Intermediate Securities Distribution\n* INTERMEDIATE_SECURITIES_DISTRIBUTION_CANCELLATION - Intermediate Securities Distribution, Cancellation\n* INTERNAL_CASH_TRANSFER - Internal cash transfer\n* INTERNAL_CASH_TRANSFER_CANCELLATION - Internal cash transfer, Cancellation\n* ISA_TRANSFER - ISA transfer\n* LIQUIDATION_PAYMENT - Liquidation Dividend/Liquidation Payment\n* LIQUIDATION_PAYMENT_CANCELLATION - Liquidation Dividend/Liquidation Payment, Cancellation\n* MATURITY_EXTENSION - Maturity extension\n* MATURITY_EXTENSION_CANCELLATION - Maturity extension cancellation\n* MERGER - Merger\n* MERGER_CANCELLATION - Merger, Cancellation\n* NON_OFFICIAL_OFFER - Non-Official Offer\n* NON_OFFICIAL_OFFER_CANCELLATION - Non-Official Offer, Cancellation\n* NON_US_TEFRA_D_CERTIFICATION - Non us tefra d certification\n* NON_US_TEFRA_D_CERTIFICATION_CANCELLATION - Non us tefra d certification cancellation\n* ODD_LOT_SALE - Odd Lot Sale/Purchase\n* ODD_LOT_SALE_CANCELLATION - Odd Lot Sale/Purchase, Cancellation\n* ORDER_EXECUTION - Order execution\n* ORDER_EXECUTION_CANCELLATION - Order execution cancellation\n* ORDINARY_GENERAL_MEETING - Ordinary general meeting\n* ORDINARY_GENERAL_MEETING_CANCELLATION - Ordinary general meeting cancellation\n* OTHER_EVENT - Other Event\n* OTHER_EVENT_CANCELLATION - Other Event, Cancellation\n* PARI_PASSU - Pari passu\n* PARI_PASSU_CANCELLATION - Pari passu cancellation\n* PARTIAL_DEFEASANCE - Partial defeasance\n* PARTIAL_DEFEASANCE_CANCELLATION - Partial defeasance cancellation\n* PARTIAL_REDEMPTION_WITH_POOL_FACTOR_REDUCTION - Partial redemption with pool factor reduction\n* PARTIAL_REDEMPTION_WITH_POOL_FACTOR_REDUCTION_CANCELLATION - Partial redemption with pool factor reduction cancellation\n* PARTIAL_REDEMPTION_WITHOUT_POOL_FACTOR_REDUCTION - Partial redemption without pool factor reduction\n* PARTIAL_REDEMPTION_WITHOUT_POOL_FACTOR_REDUCTION_CANCELLATION - Partial redemption without pool factor reduction cancellation\n* PAY_IN_KIND - Pay in kind\n* PAY_IN_KIND_CANCELLATION - Pay in kind cancellation\n* PEAK_FRACTION_COMPENSATION - Peak fraction compensation\n* PEAK_ORDER_ADJUSTMENT - Peak order adjustment\n* PLACE_OF_INCORPORATION - Place of incorporation\n* PLACE_OF_INCORPORATION_CANCELLATION - Place of incorporation cancellation\n* PRIORITY_ISSUE - Priority Issue\n* PRIORITY_ISSUE_CANCELLATION - Priority Issue, Cancellation\n* PUT_REDEMPTION - Put redemption\n* PUT_REDEMPTION_CANCELLATION - Put redemption cancellation\n* REDENOMINATION - Redenomination\n* REDENOMINATION_CANCELLATION - Redenomination cancellation\n* REMARKETING_AGREEMENT - Remarketing agreement\n* REMARKETING_AGREEMENT_CANCELLATION - Remarketing agreement cancellation\n* REPURCHASE_OFFER - Repurchase Offer/Issuer Bid/Reverse Rights\n* REPURCHASE_OFFER_CANCELLATION - Repurchase Offer/Issuer Bid/Reverse Rights, Cancellation\n* REVERSE_STOCK_SPLIT - Reverse Stock Split/Change in Nominal Value\n* REVERSE_STOCK_SPLIT_CANCELLATION - Reverse Stock Split/Change in Nominal Value, Cancellation\n* RIGHTS_ISSUE - Rights Issue/Subscription Rights/Rights Offer\n* RIGHTS_ISSUE_CANCELLATION - Rights Issue/Subscription Rights/Rights Offer, Cancellation\n* SCRIP_DIVIDEND - Scrip dividend\n* SCRIP_DIVIDEND_CANCELLATION - Scrip dividend cancellation\n* SEPA_DIRECT_DEBIT - Sepa direct debit\n* SEPA_DIRECT_DEBIT_CHARGE_BACK - Sepa direct debit charge back\n* SHARES_PREMIUM_DIVIDEND - Shares Premium Dividend\n* SHARES_PREMIUM_DIVIDEND_CANCELLATION - Shares Premium Dividend, Cancellation\n* SMALLEST_NEGOTIABLE_UNIT - Smallest negotiable unit\n* SMALLEST_NEGOTIABLE_UNIT_CANCELLATION - Smallest negotiable unit cancellation\n* SPIN_OFF - Spin-Off\n* SPIN_OFF_CANCELLATION - Spin-Off, Cancellation\n* STOCK_DIVIDEND - Stock Dividend\n* STOCK_DIVIDEND_CANCELLATION - Stock Dividend, Cancellation\n* STOCK_SPLIT - Stock Split/Change in Nominal Value/Subdivision\n* STOCK_SPLIT_CANCELLATION - Stock Split/Change in Nominal Value/Subdivision, Cancellation\n* TAX_ON_NON_DISTRIBUTED_PROCEEDS - Tax on non distributed proceeds\n* TAX_ON_NON_DISTRIBUTED_PROCEEDS_CANCELLATION - Tax on non distributed proceeds cancellation\n* TAX_PAYMENT - Tax payment\n* TAX_PREPAYMENT_DE - German tax prepayment (Vorabpauschale)\n* TAX_RECLAIM - Tax reclaim\n* TAX_RECLAIM_CANCELLATION - Tax reclaim cancellation\n* TAX_REFUND - Tax refund\n* TENDER - Tender/Acquisition/Takeover/Purchase Offer\n* TENDER_CANCELLATION - Tender/Acquisition/Takeover/Purchase Offer, Cancellation\n* TOPUP - Cash top up\n* TOPUP_CANCELLATION - Top up cancellation\n* TRADING_STATUS_ACTIVE - Trading status active\n* TRADING_STATUS_ACTIVE_CANCELLATION - Trading status active cancellation\n* TRADING_STATUS_DELISTED - Trading status delisted\n* TRADING_STATUS_DELISTED_CANCELLATION - Trading status delisted cancellation\n* TRADING_STATUS_SUSPENDED - Trading status suspended\n* TRADING_STATUS_SUSPENDED_CANCELLATION - Trading status suspended cancellation\n* TREASURY_PAYMENT - Treasury payment\n* VIRTUAL_CASH_CORRECTION - Virtual cash correction\n* VIRTUAL_CASH_CORRECTION_CANCELLATION - Virtual cash correction cancellation\n* VIRTUAL_CASH_DECREASE - Virtual cash decreased\n* VIRTUAL_CASH_INCREASE - Virtual cash increased\n* WARRANT_EXERCISE - Warrant exercise\n* WARRANT_EXERCISE_CANCELLATION - Warrant exercise cancellation\n* WITHDRAWAL - Withdrawal\n* WITHDRAWAL_CANCELLATION - Withdrawal cancellation\n* WORTHLESS - Worthless\n* WORTHLESS_CANCELLATION - Worthless, Cancellation\n* WITHHOLDING_TAX_RELIEF_CERTIFICATION - Withholding tax relief certification\n* WITHHOLDING_TAX_RELIEF_CERTIFICATION_CANCELLATION - Withholding tax relief certification cancellation", "type": "string", "enum": [ "ACCUMULATION", "ACCUMULATION_CANCELLATION", "ANNUAL_GENERAL_MEETING", "ANNUAL_GENERAL_MEETING_CANCELLATION", "ATTACHMENT", "ATTACHMENT_CANCELLATION", "BALANCE_CORRECTION", "BALANCE_CORRECTION_CANCELLATION", "BANKRUPTCY", "BANKRUPTCY_CANCELLATION", "BOND_DEFAULT", "BOND_DEFAULT_CANCELLATION", "BOND_HOLDER_MEETING", "BOND_HOLDER_MEETING_CANCELLATION", "BONUS_ISSUE", "BONUS_ISSUE_CANCELLATION", "CALL_ON_INTERMEDIATE_SECURITIES", "CALL_ON_INTERMEDIATE_SECURITIES_CANCELLATION", "CAPITAL_DISTRIBUTION", "CAPITAL_DISTRIBUTION_CANCELLATION", "CAPITAL_GAINS_DISTRIBUTION", "CAPITAL_GAINS_DISTRIBUTION_CANCELLATION", "CAPITALISATION", "CAPITALISATION_CANCELLATION", "CASH_DISTRIBUTION_FROM_NON_ELIGIBLE_SECURITIES_SALES", "CASH_DISTRIBUTION_FROM_NON_ELIGIBLE_SECURITIES_SALES_CANCELLATION", "CASH_DIVIDEND", "CASH_DIVIDEND_CANCELLATION", "CHANGE", "CHANGE_CANCELLATION", "CLASS_ACTION", "CLASS_ACTION_CANCELLATION", "COMPANY_OPTION", "COMPANY_OPTION_CANCELLATION", "CONSENT", "CONSENT_CANCELLATION", "CONVERSION", "CONVERSION_CANCELLATION", "COURT_MEETING", "COURT_MEETING_CANCELLATION", "CREDIT_EVENT", "CREDIT_EVENT_CANCELLATION", "CREDIT_FUNDING", "CREDIT_FUNDING_CHARGE_BACK", "DD_REFUND_REJECT_FEE", "DD_REFUND_REJECT_FEE_CANCELLATION", "DECREASE_IN_VALUE", "DECREASE_IN_VALUE_CANCELLATION", "DETACHMENT", "DETACHMENT_CANCELLATION", "DISCLOSURE", "DISCLOSURE_CANCELLATION", "DIVIDEND_OPTION", "DIVIDEND_OPTION_CANCELLATION", "DIVIDEND_REINVESTMENT", "DIVIDEND_REINVESTMENT_CANCELLATION", "DRAWING", "DRAWING_CANCELLATION", "DUTCH_AUCTION", "DUTCH_AUCTION_CANCELLATION", "EXCHANGE", "EXCHANGE_CANCELLATION", "EXTRAORDINARY_OR_SPECIAL_GENERAL_MEETING", "EXTRAORDINARY_OR_SPECIAL_GENERAL_MEETING_CANCELLATION", "FEE_COLLECTION", "FEE_COLLECTION_CANCELLATION", "FINAL_MATURITY", "FINAL_MATURITY_CANCELLATION", "FULL_CALL", "FULL_CALL_CANCELLATION", "INCREASE_IN_VALUE", "INCREASE_IN_VALUE_CANCELLATION", "INFORMATION", "INFORMATION_CANCELLATION", "INSTALMENT_CALL", "INSTALMENT_CALL_CANCELLATION", "INTEREST_PAYMENT", "INTEREST_PAYMENT_CANCELLATION", "INTERMEDIATE_SECURITIES_DISTRIBUTION", "INTERMEDIATE_SECURITIES_DISTRIBUTION_CANCELLATION", "INTERNAL_CASH_TRANSFER", "INTERNAL_CASH_TRANSFER_CANCELLATION", "ISA_TRANSFER", "LIQUIDATION_PAYMENT", "LIQUIDATION_PAYMENT_CANCELLATION", "MATURITY_EXTENSION", "MATURITY_EXTENSION_CANCELLATION", "MERGER", "MERGER_CANCELLATION", "NON_OFFICIAL_OFFER", "NON_OFFICIAL_OFFER_CANCELLATION", "NON_US_TEFRA_D_CERTIFICATION", "NON_US_TEFRA_D_CERTIFICATION_CANCELLATION", "ODD_LOT_SALE", "ODD_LOT_SALE_CANCELLATION", "ORDER_EXECUTION", "ORDER_EXECUTION_CANCELLATION", "ORDINARY_GENERAL_MEETING", "ORDINARY_GENERAL_MEETING_CANCELLATION", "OTHER_EVENT", "OTHER_EVENT_CANCELLATION", "PARI_PASSU", "PARI_PASSU_CANCELLATION", "PARTIAL_DEFEASANCE", "PARTIAL_DEFEASANCE_CANCELLATION", "PARTIAL_REDEMPTION_WITH_POOL_FACTOR_REDUCTION", "PARTIAL_REDEMPTION_WITH_POOL_FACTOR_REDUCTION_CANCELLATION", "PARTIAL_REDEMPTION_WITHOUT_POOL_FACTOR_REDUCTION", "PARTIAL_REDEMPTION_WITHOUT_POOL_FACTOR_REDUCTION_CANCELLATION", "PAY_IN_KIND", "PAY_IN_KIND_CANCELLATION", "PEAK_FRACTION_COMPENSATION", "PEAK_ORDER_ADJUSTMENT", "PLACE_OF_INCORPORATION", "PLACE_OF_INCORPORATION_CANCELLATION", "PRIORITY_ISSUE", "PRIORITY_ISSUE_CANCELLATION", "PUT_REDEMPTION", "PUT_REDEMPTION_CANCELLATION", "REDENOMINATION", "REDENOMINATION_CANCELLATION", "REMARKETING_AGREEMENT", "REMARKETING_AGREEMENT_CANCELLATION", "REPURCHASE_OFFER", "REPURCHASE_OFFER_CANCELLATION", "REVERSE_STOCK_SPLIT", "REVERSE_STOCK_SPLIT_CANCELLATION", "RIGHTS_ISSUE", "RIGHTS_ISSUE_CANCELLATION", "SCRIP_DIVIDEND", "SCRIP_DIVIDEND_CANCELLATION", "SEPA_DIRECT_DEBIT", "SEPA_DIRECT_DEBIT_CHARGE_BACK", "SHARES_PREMIUM_DIVIDEND", "SHARES_PREMIUM_DIVIDEND_CANCELLATION", "SMALLEST_NEGOTIABLE_UNIT", "SMALLEST_NEGOTIABLE_UNIT_CANCELLATION", "SPIN_OFF", "SPIN_OFF_CANCELLATION", "STOCK_DIVIDEND", "STOCK_DIVIDEND_CANCELLATION", "STOCK_SPLIT", "STOCK_SPLIT_CANCELLATION", "TAX_ON_NON_DISTRIBUTED_PROCEEDS", "TAX_ON_NON_DISTRIBUTED_PROCEEDS_CANCELLATION", "TAX_PAYMENT", "TAX_PREPAYMENT_DE", "TAX_RECLAIM", "TAX_RECLAIM_CANCELLATION", "TAX_REFUND", "TENDER", "TENDER_CANCELLATION", "TOPUP", "TOPUP_CANCELLATION", "TRADING_STATUS_ACTIVE", "TRADING_STATUS_ACTIVE_CANCELLATION", "TRADING_STATUS_DELISTED", "TRADING_STATUS_DELISTED_CANCELLATION", "TRADING_STATUS_SUSPENDED", "TRADING_STATUS_SUSPENDED_CANCELLATION", "TREASURY_PAYMENT", "VIRTUAL_CASH_CORRECTION", "VIRTUAL_CASH_CORRECTION_CANCELLATION", "VIRTUAL_CASH_DECREASE", "VIRTUAL_CASH_INCREASE", "WARRANT_EXERCISE", "WARRANT_EXERCISE_CANCELLATION", "WITHDRAWAL", "WITHDRAWAL_CANCELLATION", "WORTHLESS", "WORTHLESS_CANCELLATION", "WITHHOLDING_TAX_RELIEF_CERTIFICATION", "WITHHOLDING_TAX_RELIEF_CERTIFICATION_CANCELLATION" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "value_date": { "title": "Transaction value date", "type": "string", "description": "Transaction value date and time. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)", "format": "date-time" } }, "required": [ "id", "type", "account_group_id", "delta", "taxes", "taxes_details", "references", "booking_date", "value_date", "created_at", "updated_at" ], "additionalProperties": true } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "example": { "meta": { "offset": 0, "limit": 100, "count": 2, "total_count": 2, "sort": "booking_date", "order": "ASC" }, "data": [ { "id": "6dc9fbca-8835-11ed-a217-2eabd0c03f8a", "created_at": "2023-01-01T00:00:00.000Z", "updated_at": "2023-01-01T00:00:00.000Z", "type": "ORDER_EXECUTION", "account_group_id": "6409e3f2-8835-11ed-96a4-2eabd0c03f8a", "delta": { "amount": "-305.00", "currency": "EUR" }, "taxes": [ { "amount": "5.00", "currency": "EUR", "type": "TOTAL" } ], "taxes_details": { "total_amount": { "amount": "5.00", "currency": "EUR" }, "tax_breakdown": [ { "amount": "5.00", "currency": "EUR", "type": "FINANCIAL_TRANSACTION_TAX", "taxing_jurisdiction": "FR" } ] }, "references": [ { "id": "7579a672-8835-11ed-9455-2eabd0c03f8a", "type": "ORDER_EXECUTION" }, { "id": "1f5758d3-1ef7-4b4c-96ec-6b3da2bf1a8a", "type": "ORDER" } ], "booking_date": "2023-01-01T00:00:00.000Z", "value_date": "2023-01-01T00:00:00.000Z" }, { "id": "9e7a3188-eff8-11ed-a05b-0242ac120003", "created_at": "2023-01-01T00:00:00.000Z", "updated_at": "2023-01-01T00:00:00.000Z", "type": "SEPA_DIRECT_DEBIT", "account_group_id": "6409e3f2-8835-11ed-96a4-2eabd0c03f8a", "delta": { "amount": "100.00", "currency": "EUR" }, "taxes": [], "taxes_details": { "total_amount": { "amount": "0.00", "currency": "EUR" }, "tax_breakdown": [] }, "references": [ { "id": "98f01200-eff8-11ed-a05b-0242ac120003", "type": "DIRECT_DEBIT" } ], "booking_date": "2023-01-01T00:00:00.000Z", "value_date": "2023-01-01T00:00:00.000Z" } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "405": { "description": "Method Not Allowed. The requested method is not allowed on the requested resource.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 405, "type": "method_not_allowed" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/transactions/securities": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_securities_transactions", "summary": "List securities transactions", "description": "List securities transactions", "tags": [ "Transactions" ], "security": [ { "oauth-client-credentials": [ "transactions:read" ] } ], "parameters": [ { "name": "account_group_id", "in": "query", "required": false, "schema": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "description": "Filters the list to only show transactions associated with a certain account group ID.", "example": "413715f2-5401-4b97-8055-034a6b879f8c" }, { "name": "account_id", "in": "query", "required": false, "schema": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "description": "Filters the list to only show transactions associated with a certain account ID.", "example": "413715f2-5401-4b97-8055-034a6b879f8c" }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "title": "Date in YYYY-MM-DD format. RFC 3339, section 5.6", "description": "Returns transactions starting from and including this date (UTC)" }, "example": "2023-01-03" }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "title": "Date in YYYY-MM-DD format. RFC 3339, section 5.6", "description": "Returns transactions up until this date (UTC)", "example": "2023-01-11" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "booking_date" ], "default": "booking_date" }, "description": "Sort the result by `booking_date`." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." } ], "responses": { "200": { "description": "Securities Transactions", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Security transaction - List - Response", "type": "object", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "items": { "title": "Security Transaction", "type": "object", "properties": { "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "booking_date": { "title": " Transaction booking date", "type": "string", "description": " Transaction booking date and time. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "delta": { "title": "Security transaction delta", "description": "Entity representing the security transaction delta.", "type": "object", "properties": { "amount": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" } }, "required": [ "amount" ], "additionalProperties": true }, "id": { "title": "Security transaction unique identifier", "type": "string", "description": "Security transaction unique identifier.", "format": "uuid" }, "instrument": { "title": "Instrument", "description": "Entity representing instrument.", "type": "object", "properties": { "uuid": { "description": "Internal instrument identifier.", "type": "string", "format": "uuid" }, "isin": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" } }, "required": [ "uuid" ], "additionalProperties": false }, "type": { "title": "Transaction type", "description": "Transaction type\n* ACCUMULATION - Accumulation\n* ACCUMULATION_CANCELLATION - Accumulation cancellation\n* ANNUAL_GENERAL_MEETING - Annual general meeting\n* ANNUAL_GENERAL_MEETING_CANCELLATION - Annual general meeting cancellation\n* ATTACHMENT - Attachment\n* ATTACHMENT_CANCELLATION - Attachment cancellation\n* BALANCE_CORRECTION - Balance correction\n* BALANCE_CORRECTION_CANCELLATION - Balance correction cancellation\n* BANKRUPTCY - Bankruptcy\n* BANKRUPTCY_CANCELLATION - Bankruptcy cancellation\n* BOND_DEFAULT - Bond default\n* BOND_DEFAULT_CANCELLATION - Bond default cancellation\n* BOND_HOLDER_MEETING - Bond holder meeting\n* BOND_HOLDER_MEETING_CANCELLATION - Bond holder meeting cancellation\n* BONUS_ISSUE - Bonus Issue/Capitalisation Issue\n* BONUS_ISSUE_CANCELLATION - Bonus Issue/Capitalisation Issue, Cancellation\n* CALL_ON_INTERMEDIATE_SECURITIES - Call on Intermediate Securities\n* CALL_ON_INTERMEDIATE_SECURITIES_CANCELLATION - Call on Intermediate Securities, Cancellation\n* CAPITAL_DISTRIBUTION - Capital distribution\n* CAPITAL_DISTRIBUTION_CANCELLATION - Capital distribution cancellation\n* CAPITAL_GAINS_DISTRIBUTION - Capital gains distribution\n* CAPITAL_GAINS_DISTRIBUTION_CANCELLATION - Capital gains distribution cancellation\n* CAPITALISATION - Capitalisation\n* CAPITALISATION_CANCELLATION - Capitalisation cancellation\n* CASH_DISTRIBUTION_FROM_NON_ELIGIBLE_SECURITIES_SALES - Cash distribution from non eligible securities sales\n* CASH_DISTRIBUTION_FROM_NON_ELIGIBLE_SECURITIES_SALES_CANCELLATION - Cash distribution from non eligible securities sales cancellation\n* CASH_DIVIDEND - Cash dividend\n* CASH_DIVIDEND_CANCELLATION - Cash dividend cancellation\n* CHANGE - Change\n* CHANGE_CANCELLATION - Change, Cancellation\n* CLASS_ACTION - Class action\n* CLASS_ACTION_CANCELLATION - Class action cancellation\n* COMPANY_OPTION - Company option\n* COMPANY_OPTION_CANCELLATION - Company option cancellation\n* CONSENT - Consent\n* CONSENT_CANCELLATION - Consent cancellation\n* CONVERSION - Conversion\n* CONVERSION_CANCELLATION - Conversion cancellation\n* COURT_MEETING - Court meeting\n* COURT_MEETING_CANCELLATION - Court meeting cancellation\n* CREDIT_EVENT - Credit event\n* CREDIT_EVENT_CANCELLATION - Credit event cancellation\n* DECREASE_IN_VALUE - Decrease in value\n* DECREASE_IN_VALUE_CANCELLATION - Decrease in value cancellation\n* DETACHMENT - Detachment\n* DETACHMENT_CANCELLATION - Detachment cancellation\n* DISCLOSURE - Disclosure\n* DISCLOSURE_CANCELLATION - Disclosure cancellation\n* DIVIDEND_OPTION - Dividend Option\n* DIVIDEND_OPTION_CANCELLATION - Dividend Option, Cancellation\n* DIVIDEND_REINVESTMENT - Dividend Reinvestment\n* DIVIDEND_REINVESTMENT_CANCELLATION - Dividend Reinvestment, Cancellation\n* DRAWING - Drawing\n* DRAWING_CANCELLATION - Drawing cancellation\n* DUST_CLEANUP - Dust Cleanup\n* DUTCH_AUCTION - Dutch Auction\n* DUTCH_AUCTION_CANCELLATION - Dutch Auction, Cancellation\n* EXCHANGE - Exchange\n* EXCHANGE_CANCELLATION - Exchange cancellation\n* EXTRAORDINARY_OR_SPECIAL_GENERAL_MEETING - Extraordinary or special general meeting\n* EXTRAORDINARY_OR_SPECIAL_GENERAL_MEETING_CANCELLATION - Extraordinary or special general meeting cancellation\n* FINAL_MATURITY - Final maturity\n* FINAL_MATURITY_CANCELLATION - Final maturity cancellation\n* FULL_CALL - Full call\n* FULL_CALL_CANCELLATION - Full call cancellation\n* INCREASE_IN_VALUE - Increase in value\n* INCREASE_IN_VALUE_CANCELLATION - Increase in value cancellation\n* INFORMATION - Information\n* INFORMATION_CANCELLATION - Information cancellation\n* INSTALMENT_CALL - Instalment call\n* INSTALMENT_CALL_CANCELLATION - Instalment call cancellation\n* INTEREST_PAYMENT - Interest payment\n* INTEREST_PAYMENT_CANCELLATION - Interest payment cancellation\n* INTERMEDIATE_SECURITIES_DISTRIBUTION - Intermediate Securities Distribution\n* INTERMEDIATE_SECURITIES_DISTRIBUTION_CANCELLATION - Intermediate Securities Distribution, Cancellation\n* LIQUIDATION_PAYMENT - Liquidation Dividend/Liquidation Payment\n* LIQUIDATION_PAYMENT_CANCELLATION - Liquidation Dividend/Liquidation Payment, Cancellation\n* MATURITY_EXTENSION - Maturity extension\n* MATURITY_EXTENSION_CANCELLATION - Maturity extension cancellation\n* MERGER - Merger\n* MERGER_CANCELLATION - Merger, Cancellation\n* NON_OFFICIAL_OFFER - Non-Official Offer\n* NON_OFFICIAL_OFFER_CANCELLATION - Non-Official Offer, Cancellation\n* NON_US_TEFRA_D_CERTIFICATION - Non us tefra d certification\n* NON_US_TEFRA_D_CERTIFICATION_CANCELLATION - Non us tefra d certification cancellation\n* ODD_LOT_SALE - Odd Lot Sale/Purchase\n* ODD_LOT_SALE_CANCELLATION - Odd Lot Sale/Purchase, Cancellation\n* ORDER_EXECUTION - Order execution\n* ORDER_EXECUTION_CANCELLATION - Order execution cancellation\n* ORDINARY_GENERAL_MEETING - Ordinary general meeting\n* ORDINARY_GENERAL_MEETING_CANCELLATION - Ordinary general meeting cancellation\n* OTHER_EVENT - Other Event\n* OTHER_EVENT_CANCELLATION - Other Event cancellation\n* PARI_PASSU - Pari passu\n* PARI_PASSU_CANCELLATION - Pari passu cancellation\n* PARTIAL_DEFEASANCE - Partial defeasance\n* PARTIAL_DEFEASANCE_CANCELLATION - Partial defeasance cancellation\n* PARTIAL_REDEMPTION_WITH_POOL_FACTOR_REDUCTION - Partial redemption with pool factor reduction\n* PARTIAL_REDEMPTION_WITH_POOL_FACTOR_REDUCTION_CANCELLATION - Partial redemption with pool factor reduction cancellation\n* PARTIAL_REDEMPTION_WITHOUT_POOL_FACTOR_REDUCTION - Partial redemption without pool factor reduction\n* PARTIAL_REDEMPTION_WITHOUT_POOL_FACTOR_REDUCTION_CANCELLATION - Partial redemption without pool factor reduction cancellation\n* PAY_IN_KIND - Pay in kind\n* PAY_IN_KIND_CANCELLATION - Pay in kind cancellation\n* PEAK_FRACTION_COMPENSATION - Peak fraction compensation\n* PEAK_ORDER_ADJUSTMENT - Peak order adjustment\n* PLACE_OF_INCORPORATION - Place of incorporation\n* PLACE_OF_INCORPORATION_CANCELLATION - Place of incorporation cancellation\n* PRIORITY_ISSUE - Priority Issue\n* PRIORITY_ISSUE_CANCELLATION - Priority Issue, Cancellation\n* PUT_REDEMPTION - Put redemption\n* PUT_REDEMPTION_CANCELLATION - Put redemption cancellation\n* REDENOMINATION - Redenomination\n* REDENOMINATION_CANCELLATION - Redenomination cancellation\n* REMARKETING_AGREEMENT - Remarketing agreement\n* REMARKETING_AGREEMENT_CANCELLATION - Remarketing agreement cancellation\n* REPURCHASE_OFFER - Repurchase Offer/Issuer Bid/Reverse Rights\n* REPURCHASE_OFFER_CANCELLATION - Repurchase Offer/Issuer Bid/Reverse Rights, Cancellation\n* REVERSE_STOCK_SPLIT - Reverse Stock Split/Change in Nominal Value\n* REVERSE_STOCK_SPLIT_CANCELLATION - Reverse Stock Split/Change in Nominal Value, Cancellation\n* RIGHTS_ISSUE - Rights Issue/Subscription Rights/Rights Offer\n* RIGHTS_ISSUE_CANCELLATION - Rights Issue/Subscription Rights/Rights Offer, Cancellation\n* SCRIP_DIVIDEND - Scrip dividend\n* SCRIP_DIVIDEND_CANCELLATION - Scrip dividend cancellation\n* SECURITIES_TRANSFER - Securities transfer\n* SECURITIES_TRANSFER_CANCELLATION - Securities transfer cancellation\n* SHARES_PREMIUM_DIVIDEND - Shares premium dividend\n* SHARES_PREMIUM_DIVIDEND_CANCELLATION - Shares premium dividend cancellation\n* SMALLEST_NEGOTIABLE_UNIT - Smallest negotiable unit\n* SMALLEST_NEGOTIABLE_UNIT_CANCELLATION - Smallest negotiable unit cancellation\n* SPIN_OFF - Spin-Off\n* SPIN_OFF_CANCELLATION - Spin-Off, Cancellation\n* STOCK_DIVIDEND - Stock Dividend\n* STOCK_DIVIDEND_CANCELLATION - Stock Dividend, Cancellation\n* STOCK_SPLIT - Stock Split/Change in Nominal Value/Subdivision\n* STOCK_SPLIT_CANCELLATION - Stock Split/Change in Nominal Value/Subdivision, Cancellation\n* TAX_ON_NON_DISTRIBUTED_PROCEEDS - Tax on non distributed proceeds\n* TAX_ON_NON_DISTRIBUTED_PROCEEDS_CANCELLATION - Tax on non distributed proceeds cancellation\n* TAX_RECLAIM - Tax reclaim\n* TAX_RECLAIM_CANCELLATION - Tax reclaim cancellation\n* TENDER - Tender/Acquisition/Takeover/Purchase Offer\n* TENDER_CANCELLATION - Tender/Acquisition/Takeover/Purchase Offer, Cancellation\n* TRADING_STATUS_ACTIVE - Trading status active\n* TRADING_STATUS_ACTIVE_CANCELLATION - Trading status active cancellation\n* TRADING_STATUS_DELISTED - Trading status delisted\n* TRADING_STATUS_DELISTED_CANCELLATION - Trading status delisted cancellation\n* TRADING_STATUS_SUSPENDED - Trading status suspended\n* TRADING_STATUS_SUSPENDED_CANCELLATION - Trading status suspended cancellation\n* VIRTUAL_CASH_CORRECTION_CANCELLATION - Virtual cash correction cancellation\n* WARRANT_EXERCISE - Warrant exercise\n* WARRANT_EXERCISE_CANCELLATION - Warrant exercise cancellation\n* WITHHOLDING_TAX_RELIEF_CERTIFICATION - Withholding tax relief certification\n* WITHHOLDING_TAX_RELIEF_CERTIFICATION_CANCELLATION - Withholding tax relief certification cancellation\n* WORTHLESS - Worthless\n* WORTHLESS_CANCELLATION - Worthless, Cancellation\n* SECURITIES_LENDING - Securities lending", "type": "string", "enum": [ "ACCUMULATION", "ACCUMULATION_CANCELLATION", "ANNUAL_GENERAL_MEETING", "ANNUAL_GENERAL_MEETING_CANCELLATION", "ATTACHMENT", "ATTACHMENT_CANCELLATION", "BALANCE_CORRECTION", "BALANCE_CORRECTION_CANCELLATION", "BANKRUPTCY", "BANKRUPTCY_CANCELLATION", "BOND_DEFAULT", "BOND_DEFAULT_CANCELLATION", "BOND_HOLDER_MEETING", "BOND_HOLDER_MEETING_CANCELLATION", "BONUS_ISSUE", "BONUS_ISSUE_CANCELLATION", "CALL_ON_INTERMEDIATE_SECURITIES", "CALL_ON_INTERMEDIATE_SECURITIES_CANCELLATION", "CAPITAL_DISTRIBUTION", "CAPITAL_DISTRIBUTION_CANCELLATION", "CAPITAL_GAINS_DISTRIBUTION", "CAPITAL_GAINS_DISTRIBUTION_CANCELLATION", "CAPITALISATION", "CAPITALISATION_CANCELLATION", "CASH_DISTRIBUTION_FROM_NON_ELIGIBLE_SECURITIES_SALES", "CASH_DISTRIBUTION_FROM_NON_ELIGIBLE_SECURITIES_SALES_CANCELLATION", "CASH_DIVIDEND", "CASH_DIVIDEND_CANCELLATION", "CHANGE", "CHANGE_CANCELLATION", "CLASS_ACTION", "CLASS_ACTION_CANCELLATION", "COMPANY_OPTION", "COMPANY_OPTION_CANCELLATION", "CONSENT", "CONSENT_CANCELLATION", "CONVERSION", "CONVERSION_CANCELLATION", "COURT_MEETING", "COURT_MEETING_CANCELLATION", "CREDIT_EVENT", "CREDIT_EVENT_CANCELLATION", "DECREASE_IN_VALUE", "DECREASE_IN_VALUE_CANCELLATION", "DETACHMENT", "DETACHMENT_CANCELLATION", "DISCLOSURE", "DISCLOSURE_CANCELLATION", "DIVIDEND_OPTION", "DIVIDEND_OPTION_CANCELLATION", "DIVIDEND_REINVESTMENT", "DIVIDEND_REINVESTMENT_CANCELLATION", "DRAWING", "DRAWING_CANCELLATION", "DUST_CLEANUP", "DUTCH_AUCTION", "DUTCH_AUCTION_CANCELLATION", "EXCHANGE", "EXCHANGE_CANCELLATION", "EXTRAORDINARY_OR_SPECIAL_GENERAL_MEETING", "EXTRAORDINARY_OR_SPECIAL_GENERAL_MEETING_CANCELLATION", "FINAL_MATURITY", "FINAL_MATURITY_CANCELLATION", "FULL_CALL", "FULL_CALL_CANCELLATION", "INCREASE_IN_VALUE", "INCREASE_IN_VALUE_CANCELLATION", "INFORMATION", "INFORMATION_CANCELLATION", "INSTALMENT_CALL", "INSTALMENT_CALL_CANCELLATION", "INTEREST_PAYMENT", "INTEREST_PAYMENT_CANCELLATION", "INTERMEDIATE_SECURITIES_DISTRIBUTION", "INTERMEDIATE_SECURITIES_DISTRIBUTION_CANCELLATION", "LIQUIDATION_PAYMENT", "LIQUIDATION_PAYMENT_CANCELLATION", "MATURITY_EXTENSION", "MATURITY_EXTENSION_CANCELLATION", "MERGER", "MERGER_CANCELLATION", "NON_OFFICIAL_OFFER", "NON_OFFICIAL_OFFER_CANCELLATION", "NON_US_TEFRA_D_CERTIFICATION", "NON_US_TEFRA_D_CERTIFICATION_CANCELLATION", "ODD_LOT_SALE", "ODD_LOT_SALE_CANCELLATION", "ORDER_EXECUTION", "ORDER_EXECUTION_CANCELLATION", "ORDINARY_GENERAL_MEETING", "ORDINARY_GENERAL_MEETING_CANCELLATION", "OTHER_EVENT", "OTHER_EVENT_CANCELLATION", "PARI_PASSU", "PARI_PASSU_CANCELLATION", "PARTIAL_DEFEASANCE", "PARTIAL_DEFEASANCE_CANCELLATION", "PARTIAL_REDEMPTION_WITH_POOL_FACTOR_REDUCTION", "PARTIAL_REDEMPTION_WITH_POOL_FACTOR_REDUCTION_CANCELLATION", "PARTIAL_REDEMPTION_WITHOUT_POOL_FACTOR_REDUCTION", "PARTIAL_REDEMPTION_WITHOUT_POOL_FACTOR_REDUCTION_CANCELLATION", "PAY_IN_KIND", "PAY_IN_KIND_CANCELLATION", "PEAK_FRACTION_COMPENSATION", "PEAK_ORDER_ADJUSTMENT", "PLACE_OF_INCORPORATION", "PLACE_OF_INCORPORATION_CANCELLATION", "PRIORITY_ISSUE", "PRIORITY_ISSUE_CANCELLATION", "PUT_REDEMPTION", "PUT_REDEMPTION_CANCELLATION", "REDENOMINATION", "REDENOMINATION_CANCELLATION", "REMARKETING_AGREEMENT", "REMARKETING_AGREEMENT_CANCELLATION", "REPURCHASE_OFFER", "REPURCHASE_OFFER_CANCELLATION", "REVERSE_STOCK_SPLIT", "REVERSE_STOCK_SPLIT_CANCELLATION", "RIGHTS_ISSUE", "RIGHTS_ISSUE_CANCELLATION", "SCRIP_DIVIDEND", "SCRIP_DIVIDEND_CANCELLATION", "SECURITIES_TRANSFER", "SECURITIES_TRANSFER_CANCELLATION", "SHARES_PREMIUM_DIVIDEND", "SHARES_PREMIUM_DIVIDEND_CANCELLATION", "SMALLEST_NEGOTIABLE_UNIT", "SMALLEST_NEGOTIABLE_UNIT_CANCELLATION", "SPIN_OFF", "SPIN_OFF_CANCELLATION", "STOCK_DIVIDEND", "STOCK_DIVIDEND_CANCELLATION", "STOCK_SPLIT", "STOCK_SPLIT_CANCELLATION", "TAX_ON_NON_DISTRIBUTED_PROCEEDS", "TAX_ON_NON_DISTRIBUTED_PROCEEDS_CANCELLATION", "TAX_RECLAIM", "TAX_RECLAIM_CANCELLATION", "TENDER", "TENDER_CANCELLATION", "TRADING_STATUS_ACTIVE", "TRADING_STATUS_ACTIVE_CANCELLATION", "TRADING_STATUS_DELISTED", "TRADING_STATUS_DELISTED_CANCELLATION", "TRADING_STATUS_SUSPENDED", "TRADING_STATUS_SUSPENDED_CANCELLATION", "VIRTUAL_CASH_CORRECTION_CANCELLATION", "WARRANT_EXERCISE", "WARRANT_EXERCISE_CANCELLATION", "WITHHOLDING_TAX_RELIEF_CERTIFICATION", "WITHHOLDING_TAX_RELIEF_CERTIFICATION_CANCELLATION", "WORTHLESS", "WORTHLESS_CANCELLATION", "SECURITIES_LENDING" ] }, "references": { "type": "array", "items": { "title": "Security transaction reference", "description": "Entity representing security transaction reference.", "type": "object", "properties": { "id": { "title": "Unique identifier for a resource of given type", "type": "string", "description": "Unique identifier for a resource of given type.", "format": "uuid" }, "type": { "type": "string", "description": "Type of the reference.\n* ORDER - Order\n* ORDER_EXECUTION - Order execution\n* CORPORATE_ACTION - Corporate action\n* CORPORATE_ACTION_TRANSACTION_ID - Corporate action transaction ID", "enum": [ "ORDER", "ORDER_EXECUTION", "CORPORATE_ACTION", "CORPORATE_ACTION_TRANSACTION_ID" ] } }, "required": [ "id", "type" ], "additionalProperties": false } }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "value_date": { "title": "Transaction value date", "type": "string", "description": "Transaction value date and time. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)", "format": "date-time" } }, "required": [ "id", "type", "account_id", "account_group_id", "instrument", "delta", "references", "value_date", "booking_date", "created_at", "updated_at" ], "additionalProperties": true } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "example": { "meta": { "offset": 0, "limit": 100, "count": 2, "total_count": 2, "sort": "booking_date", "order": "ASC" }, "data": [ { "id": "6dc9fbca-8835-11ed-a217-2eabd0c03f8a", "created_at": "2023-01-01T00:00:00.000Z", "updated_at": "2023-01-01T00:00:00.000Z", "type": "ORDER_EXECUTION", "account_id": "db6290bb-1491-45bf-aafe-262dad59d497", "account_group_id": "6409e3f2-8835-11ed-96a4-2eabd0c03f8a", "instrument": { "uuid": "ccb86937-8a39-4160-8d33-85bf9e902321", "isin": "US0378331005" }, "delta": { "amount": "-2.5234543879" }, "references": [ { "id": "7579a672-8835-11ed-9455-2eabd0c03f8a", "type": "ORDER_EXECUTION" }, { "id": "1f5758d3-1ef7-4b4c-96ec-6b3da2bf1a8a", "type": "ORDER" } ], "booking_date": "2023-01-01T00:00:00.000Z", "value_date": "2023-01-01T00:00:00.000Z" }, { "id": "6dc9fbca-8835-11ed-a217-2eabd0c03f8a", "created_at": "2023-01-01T00:00:00.000Z", "updated_at": "2023-01-01T00:00:00.000Z", "type": "ORDER_EXECUTION_CANCELLATION", "account_id": "db6290bb-1491-45bf-aafe-262dad59d497", "account_group_id": "6409e3f2-8835-11ed-96a4-2eabd0c03f8a", "instrument": { "uuid": "ccb86937-8a39-4160-8d33-85bf9e902321", "isin": "US0378331005" }, "delta": { "amount": "2.5234543879" }, "references": [ { "id": "7579a672-8835-11ed-9455-2eabd0c03f8a", "type": "ORDER_EXECUTION" }, { "id": "1f5758d3-1ef7-4b4c-96ec-6b3da2bf1a8a", "type": "ORDER" } ], "booking_date": "2023-01-01T00:00:00.000Z", "value_date": "2023-01-01T00:00:00.000Z" } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "405": { "description": "Method Not Allowed. The requested method is not allowed on the requested resource.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 405, "type": "method_not_allowed" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/accounts/{account_id}/liquidations": { "parameters": [ { "name": "account_id", "in": "path", "required": true, "description": "The unique identifier of the account. Universally Unique Identifier (UUID).", "schema": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_accounts_liquidations", "summary": "List accounts liquidations", "description": "Returns a paginated list of account liquidation requests for the authenticated client.\n\nSee the Liquidations guide ([TOL](https://docs.upvest.co/products/tol/guides/liquidations) / [BYOL](https://docs.upvest.co/products/byol/guides/liquidations)) for implementation details.", "tags": [ "Liquidations" ], "security": [ { "oauth-client-credentials": [ "account_liquidations:read", "account_liquidations:admin" ] } ], "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "id" ], "default": "id" }, "description": "Sort the result by `id`." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. By default, only ASC for ascending sort." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "title": "Date in YYYY-MM-DD format. RFC 3339, section 5.6" }, "description": "Returns accounts liquidations created starting from and including this date (UTC)", "example": "2022-10-14T10:10:10Z" }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "title": "Date in YYYY-MM-DD format. RFC 3339, section 5.6" }, "description": "Returns accounts liquidations created up until this date (UTC)", "example": "2022-10-14T10:10:10Z" } ], "responses": { "200": { "description": "Accounts liquidations", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Portfolios orders - List - Response", "type": "object", "description": "Paginated list of account liquidations, including cursor-based pagination metadata.", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "items": { "title": "Account liquidation", "type": "object", "description": "Represents an account liquidation — a request to sell all investment positions in an account and convert the proceeds to cash. Contains references to each individual sell order.", "properties": { "id": { "title": "Account liquidation unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of an account liquidation.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "description": "ID of the user who owns the account. Exactly one of user_id or business_id will be set; the other will be null.", "oneOf": [ { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, { "type": "null" } ] }, "business_id": { "description": "ID of the business that owns the account. Exactly one of user_id or business_id will be set; the other will be null.", "oneOf": [ { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, { "type": "null" } ] }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "cash_amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound", "enum": [ "EUR", "GBP" ] }, "status": { "type": "string", "description": "Execution status of the Account liquidation.\n* NEW - \n* PROCESSING - \n* FILLED - \n* CANCELLED - \n* SETTLED - ", "enum": [ "NEW", "PROCESSING", "FILLED", "CANCELLED", "SETTLED" ] }, "orders": { "type": "array", "description": "Position liquidation orders associated with this account liquidation", "items": { "title": "Account liquidation", "type": "object", "description": "An individual sell order within an account liquidation, corresponding to the sale of a single position held in the account.", "properties": { "id": { "title": "Account liquidation order unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of an account liquidation order.", "format": "uuid" }, "side": { "type": "string", "description": "Side of the order.\n* SELL - ", "default": "SELL" }, "status": { "type": "string", "description": "Execution status of the Account liquidation order.\n* NEW - \n* PROCESSING - \n* FILLED - \n* CANCELLED - ", "enum": [ "NEW", "PROCESSING", "FILLED", "CANCELLED" ] } }, "required": [ "id", "side", "status" ], "additionalProperties": false } }, "fee_collection_id": { "description": "Identifier of the fee collection associated with this liquidation. Null when no fee applies. See the Fees API to retrieve fee details.", "oneOf": [ { "type": "null" }, { "title": "Fee collection unique identifier.", "type": "string", "description": "Fee collection unique identifier.", "format": "uuid" } ] } }, "required": [ "id", "created_at", "updated_at", "account_id", "cash_amount", "currency", "status", "orders", "fee_collection_id" ], "additionalProperties": false } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "example": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1, "sort": "id", "order": "ASC" }, "data": [ { "id": "c5869b0c-e107-4e68-a89a-57ad43253dd6", "created_at": "2021-07-21T14:10:00.000Z", "updated_at": "2021-07-21T14:10:00.000Z", "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3", "cash_amount": "1000", "currency": "EUR", "status": "PROCESSING", "orders": [ { "id": "b291d8a4-21f5-4c52-8590-4f90ce54d0b1", "side": "SELL", "status": "NEW" }, { "id": "81d02bd9-7b9d-443d-bbfa-31df4d543f7d", "side": "SELL", "status": "PROCESSING" }, { "id": "e97fb564-ebb4-4f37-930a-bda49c09a2e4", "side": "SELL", "status": "FILLED" } ], "fee_collection_id": null } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "405": { "description": "Method Not Allowed. The requested method is not allowed on the requested resource.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 405, "type": "method_not_allowed" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "post": { "operationId": "create_account_liquidation", "summary": "Create account liquidation request", "description": "Initiates a full liquidation of an investment account, placing sell orders for all held positions and converting the proceeds to cash.\n\nExactly one of `user_id` or `business_id` must be provided in the request body.\n\nSee the Liquidations guide ([TOL](https://docs.upvest.co/products/tol/guides/liquidations) / [BYOL](https://docs.upvest.co/products/byol/guides/liquidations)) for implementation details.", "tags": [ "Liquidations" ], "security": [ { "oauth-client-credentials": [ "account_liquidations:admin" ] } ], "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$", "example": "ccb07f42-4104-44ad-8e1f-c660bb7b269c" }, "description": "A UUID to be used as an idempotency key. This prevents a duplicate request from being replayed.\nhttps://docs.upvest.co/documentation/concepts/api_concepts/idempotency\n" } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Account liquidation - Request", "type": "object", "description": "Request body for initiating an account liquidation. Exactly one of `user_id` or `business_id` must be provided.", "properties": { "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "business_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" } }, "oneOf": [ { "type": "object", "required": [ "user_id" ] }, { "type": "object", "required": [ "business_id" ] } ], "additionalProperties": false }, "example": { "user_id": "084a00a8-4a37-4d2d-b276-71ec5e2be0e3" } } } }, "responses": { "202": { "description": "Account liquidation object", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Account liquidation", "type": "object", "description": "Represents an account liquidation — a request to sell all investment positions in an account and convert the proceeds to cash. Contains references to each individual sell order.", "properties": { "id": { "title": "Account liquidation unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of an account liquidation.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "description": "ID of the user who owns the account. Exactly one of user_id or business_id will be set; the other will be null.", "oneOf": [ { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, { "type": "null" } ] }, "business_id": { "description": "ID of the business that owns the account. Exactly one of user_id or business_id will be set; the other will be null.", "oneOf": [ { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, { "type": "null" } ] }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "cash_amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound", "enum": [ "EUR", "GBP" ] }, "status": { "type": "string", "description": "Execution status of the Account liquidation.\n* NEW - \n* PROCESSING - \n* FILLED - \n* CANCELLED - \n* SETTLED - ", "enum": [ "NEW", "PROCESSING", "FILLED", "CANCELLED", "SETTLED" ] }, "orders": { "type": "array", "description": "Position liquidation orders associated with this account liquidation", "items": { "title": "Account liquidation", "type": "object", "description": "An individual sell order within an account liquidation, corresponding to the sale of a single position held in the account.", "properties": { "id": { "title": "Account liquidation order unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of an account liquidation order.", "format": "uuid" }, "side": { "type": "string", "description": "Side of the order.\n* SELL - ", "default": "SELL" }, "status": { "type": "string", "description": "Execution status of the Account liquidation order.\n* NEW - \n* PROCESSING - \n* FILLED - \n* CANCELLED - ", "enum": [ "NEW", "PROCESSING", "FILLED", "CANCELLED" ] } }, "required": [ "id", "side", "status" ], "additionalProperties": false } }, "fee_collection_id": { "description": "Identifier of the fee collection associated with this liquidation. Null when no fee applies. See the Fees API to retrieve fee details.", "oneOf": [ { "type": "null" }, { "title": "Fee collection unique identifier.", "type": "string", "description": "Fee collection unique identifier.", "format": "uuid" } ] } }, "required": [ "id", "created_at", "updated_at", "account_id", "cash_amount", "currency", "status", "orders", "fee_collection_id" ], "additionalProperties": false }, "example": { "id": "b2f541dc-a27b-4d5a-b970-41812b0892b9", "created_at": "2021-07-21T14:10:00.000Z", "updated_at": "2021-07-21T14:10:00.000Z", "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3", "user_id": "81dfb00e-9be6-4617-8994-dfd0407f34df", "cash_amount": "1000", "currency": "EUR", "status": "NEW", "orders": [], "fee_collection_id": null } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/accounts/{account_id}/liquidations/{account_liquidation_id}": { "parameters": [ { "name": "account_id", "in": "path", "required": true, "description": "The unique identifier of the account. Universally Unique Identifier (UUID).", "schema": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" } }, { "name": "account_liquidation_id", "in": "path", "required": true, "description": "The unique identifier of the account liquidation. Universally Unique Identifier (UUID).", "schema": { "title": "Account liquidation unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of an account liquidation.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_account_liquidation", "summary": "Retrieve account liquidation", "description": "Retrieves an account liquidation by its ID, including the status of each individual sell order.\n\nSee the Liquidations guide ([TOL](https://docs.upvest.co/products/tol/guides/liquidations) / [BYOL](https://docs.upvest.co/products/byol/guides/liquidations)) for implementation details.", "tags": [ "Liquidations" ], "security": [ { "oauth-client-credentials": [ "account_liquidations:read", "account_liquidations:admin" ] } ], "responses": { "200": { "description": "Account liquidation object", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Account liquidation", "type": "object", "description": "Represents an account liquidation — a request to sell all investment positions in an account and convert the proceeds to cash. Contains references to each individual sell order.", "properties": { "id": { "title": "Account liquidation unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of an account liquidation.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "description": "ID of the user who owns the account. Exactly one of user_id or business_id will be set; the other will be null.", "oneOf": [ { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, { "type": "null" } ] }, "business_id": { "description": "ID of the business that owns the account. Exactly one of user_id or business_id will be set; the other will be null.", "oneOf": [ { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, { "type": "null" } ] }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "cash_amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound", "enum": [ "EUR", "GBP" ] }, "status": { "type": "string", "description": "Execution status of the Account liquidation.\n* NEW - \n* PROCESSING - \n* FILLED - \n* CANCELLED - \n* SETTLED - ", "enum": [ "NEW", "PROCESSING", "FILLED", "CANCELLED", "SETTLED" ] }, "orders": { "type": "array", "description": "Position liquidation orders associated with this account liquidation", "items": { "title": "Account liquidation", "type": "object", "description": "An individual sell order within an account liquidation, corresponding to the sale of a single position held in the account.", "properties": { "id": { "title": "Account liquidation order unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of an account liquidation order.", "format": "uuid" }, "side": { "type": "string", "description": "Side of the order.\n* SELL - ", "default": "SELL" }, "status": { "type": "string", "description": "Execution status of the Account liquidation order.\n* NEW - \n* PROCESSING - \n* FILLED - \n* CANCELLED - ", "enum": [ "NEW", "PROCESSING", "FILLED", "CANCELLED" ] } }, "required": [ "id", "side", "status" ], "additionalProperties": false } }, "fee_collection_id": { "description": "Identifier of the fee collection associated with this liquidation. Null when no fee applies. See the Fees API to retrieve fee details.", "oneOf": [ { "type": "null" }, { "title": "Fee collection unique identifier.", "type": "string", "description": "Fee collection unique identifier.", "format": "uuid" } ] } }, "required": [ "id", "created_at", "updated_at", "account_id", "cash_amount", "currency", "status", "orders", "fee_collection_id" ], "additionalProperties": false }, "example": { "id": "f386fdc4-dcd8-4dce-8acb-dae332f51483", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "user_id": "4b9732bd-7496-4e91-8a5f-6360479d7fed", "account_id": "f2f7d2c7-d79b-4de2-ae9b-d01646259f9e", "cash_amount": "100.00", "currency": "EUR", "status": "PROCESSING", "orders": [ { "id": "79f2c816-13ed-4588-85e6-f3398b0b5825", "side": "SELL", "status": "NEW" }, { "id": "44f50a4e-7ce8-4eae-a078-f4b3d8ab4708", "side": "SELL", "status": "NEW" } ], "fee_collection_id": "8a6a2b7c-3f4e-4d8a-9c1b-1234567890ab" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "delete": { "operationId": "cancel_account_liquidation", "summary": "Cancel account liquidation", "description": "Cancels a pending account liquidation. Only liquidations in the `NEW` status can be cancelled.\n\nSee the Liquidations guide ([TOL](https://docs.upvest.co/products/tol/guides/liquidations) / [BYOL](https://docs.upvest.co/products/byol/guides/liquidations)) for implementation details.", "tags": [ "Liquidations" ], "security": [ { "oauth-client-credentials": [ "account_liquidations:admin" ] } ], "responses": { "204": { "description": "Request has been processed successfully.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/accounts/{account_id}/returns": { "parameters": [ { "name": "account_id", "in": "path", "required": true, "description": "The unique identifier of the account. Universally Unique Identifier (UUID).", "schema": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_account_returns", "summary": "List account returns", "description": "List account returns", "tags": [ "Returns" ], "security": [ { "oauth-client-credentials": [ "account_returns:read" ] } ], "parameters": [ { "name": "start_date", "in": "query", "schema": { "type": "string", "title": "Date in YYYY-MM-DD format. RFC 3339, section 5.6" }, "description": "Returns account returns starting from and including this date (UTC)", "example": "2023-08-15" }, { "name": "end_date", "in": "query", "schema": { "type": "string", "title": "Date in YYYY-MM-DD format. RFC 3339, section 5.6" }, "description": "Returns account returns up until this date (UTC)", "example": "2023-08-15" }, { "name": "sort", "in": "query", "required": false, "description": "Sort the result by `date`.", "schema": { "type": "string", "enum": [ "date" ], "default": "date" } }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Account Return - List - Response", "type": "object", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "items": { "title": "Account Returns", "type": "object", "properties": { "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "date": { "type": "string", "format": "date-time", "description": "Date when returns were calculated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "twr": { "title": "", "type": "object", "properties": { "daily": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "cumulative": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "cumulative_start_date": { "type": "string", "format": "date-time", "description": "Date when the cumulative time-weighted returns calculation starts." } } } }, "required": [ "account_id", "date", "twr" ], "additionalProperties": false } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "example": { "meta": { "offset": 0, "limit": 100, "count": 2, "total_count": 2, "sort": "date", "order": "ASC" }, "data": [ { "account_id": "bbe9e784-e009-4cb6-a07c-24831897327b", "date": "2023-09-01", "twr": { "daily": "0.0132434142", "cumulative": "0.0324353234", "cumulative_start_date": "2023-08-01" } }, { "account_id": "bbe9e784-e009-4cb6-a07c-24831897327b", "date": "2023-09-02", "twr": { "daily": "-0.005116543491", "cumulative": "0.0271528232", "cumulative_start_date": "2023-08-01" } } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "405": { "description": "Method Not Allowed. The requested method is not allowed on the requested resource.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 405, "type": "method_not_allowed" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/account_transfers": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "post": { "operationId": "create_account_transfer", "summary": "Create account transfer", "description": "Create account transfer", "tags": [ "Account Transfers" ], "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$", "example": "ccb07f42-4104-44ad-8e1f-c660bb7b269c" }, "description": "A UUID to be used as an idempotency key. This prevents a duplicate request from being replayed.\nhttps://docs.upvest.co/documentation/concepts/api_concepts/idempotency\n" } ], "security": [ { "oauth-client-credentials": [ "account_transfers:admin" ] } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Transfers - Account Transfer - Create - Request", "type": "object", "properties": { "direction": { "type": "string", "description": "Direction of the securities transfer\n* `INCOMING` - Securities transfer is incoming to the user.\n* OUTGOING - Securities transfer is outgoing from the user.", "enum": [ "INCOMING", "OUTGOING" ] }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "transfer_type": { "type": "string", "description": "Type of the securities transfer\n* NO_OWNER_CHANGE - No change of ownership.", "enum": [ "NO_OWNER_CHANGE" ] }, "settlement_reference": { "type": "string", "pattern": "^[0-9A-Za-z+?/\\-:()\\.,' ]*$", "description": "Unique identifier of the account transfer set by API consumers. Useful for API consumers to build special logic on top of it.\n*NOTE: This reference will be set and be common to all securities transfers*" }, "instruments": { "type": "array", "items": { "title": "Instruments request", "type": "object", "properties": { "id": { "type": "string", "description": "`ISIN` or other identity (depends on instrument_id_type) of the security to be transferred." }, "id_type": { "type": "string", "description": "Type of the instrument_id\n* `ISIN` - International Securities Identification Number", "enum": [ "ISIN" ] }, "quantity": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$", "description": "The quantity of instrument to move in or out. The value supported is maximum 15 digits including decimal place.\n*Note: For `INCOMING` the end user ensures that they don't sell their instruments on the counter-broker to enable smooth transfer of their instruments on Upvest platform.*" } }, "required": [ "id", "id_type", "quantity" ] }, "description": "For `INCOMING` at least one instrument should be defined. For `OUTGOING` an empty list means full transfer of full units of the account." }, "counterparty": { "title": "Counterparty", "description": "Counterparty for account transfer. The `type` field determines which counterparty variant is present in the payload.", "oneOf": [ { "type": "object", "title": "Account transfer counterparty - BIC", "description": "Counterparty with BIC (Bank Identifier Code) based identification for account transfer.", "properties": { "type": { "default": "BIC", "type": "string", "description": "Type of the counterparty." }, "id": { "title": "Business Identifier Code", "type": "string", "description": "Business Identifier Code (also known as SWIFT-BIC, BIC, SWIFT ID or SWIFT code) [ISO 9362](https://en.wikipedia.org/wiki/ISO_9362).", "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$" }, "account_number": { "title": "Account Number", "description": "The account number is composed of valid Swift charset with a max length of 28 if provided. The account number helps other brokers identify the owner of the assets.", "type": "string", "pattern": "^[0-9A-Za-z+?/\\-:()\\.,' ]{0,28}$" }, "name": { "title": "Full name of the counterparty", "description": "The name is going to be split into 4 lines of 35 characters, the split is space based. This means that even if the name is exactly 140 of length, we may drop out the last parts if they don't fit into 4x35.", "type": "string", "pattern": "^[0-9A-Za-z+?/\\-:()\\.,' ]{0,140}$" } }, "required": [ "type", "id" ], "additionalProperties": false } ] }, "trade_date": { "type": "string", "format": "date", "description": "Optional forecast date when the trade takes place. If provided, usually T+1 is sufficient. Depending on the market this means valid working days. Date in YYYY-MM-DD format. \n*NOTE: Each individual transfer can differ based on market needs.*" }, "settlement_date": { "type": "string", "format": "date", "description": "Optional forecast date when the settlement takes place. If provided, usually T+2 is sufficient or trade_date + 1. Depending on the market this means valid working days. Date in YYYY-MM-DD format. \n*NOTE: Each individual transfer can differ based on market needs." }, "order_date": { "type": "string", "format": "date", "description": "Optional date when the transfer request was received from the end user. If omitted, Upvest defaults `order_date` to the transfer's `created_at` timestamp. The regulatory deadline runs from this date. Date in YYYY-MM-DD format." } }, "required": [ "direction", "user_id", "account_id", "transfer_type", "settlement_reference", "instruments", "counterparty" ], "additionalProperties": false }, "examples": { "incoming": { "summary": "INCOMING", "value": { "direction": "INCOMING", "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e", "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4", "transfer_type": "NO_OWNER_CHANGE", "settlement_reference": "b82dc5985558fdr2", "instruments": [ { "id": "US0378331005", "id_type": "ISIN", "quantity": "10" }, { "id": "US64110L1061", "id_type": "ISIN", "quantity": "5" } ], "counterparty": { "type": "BIC", "id": "ABCDDEFFXXX", "account_number": "1234567891", "name": "Max Mustermann" }, "order_date": "2025-01-21" } }, "outgoing": { "summary": "OUTGOING", "value": { "direction": "OUTGOING", "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e", "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4", "transfer_type": "NO_OWNER_CHANGE", "settlement_reference": "b82dc5985558fdr2", "instruments": [ { "id": "US0378331005", "id_type": "ISIN", "quantity": "10" }, { "id": "US64110L1061", "id_type": "ISIN", "quantity": "5" } ], "counterparty": { "type": "BIC", "id": "ABCDDEFFXXX", "account_number": "1234567891", "name": "Max Mustermann" }, "order_date": "2025-01-21" } } } } } }, "responses": { "200": { "description": "Account Transfer created", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "title": "Account transfer request unique identifier.", "type": "string", "description": "Account transfer request unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "direction": { "type": "string", "description": "Direction of the account transfer\n* INCOMING - account transfer is incoming to the user.\n* OUTGOING - account transfer is outgoing from the user.", "enum": [ "INCOMING", "OUTGOING" ] }, "status": { "type": "string", "description": "Status of the account transfer\n* NEW - account transfer is created but not started processing.\n* PROCESSING - account transfer is in processing.\n* SETTLED - account transfer was successfully settled.\n* PARTIALLY_SETTLED - account transfer was partially settled, while some instrument got cancelled.\n* CANCELLED - account transfer was cancelled.", "enum": [ "NEW", "PROCESSING", "SETTLED", "PARTIALLY_SETTLED", "CANCELLED" ] }, "transfer_type": { "type": "string", "description": "Type of the account transfer\n* NO_OWNER_CHANGE - No change of ownership.", "enum": [ "NO_OWNER_CHANGE" ] }, "instruments": { "title": "Instruments", "type": "array", "description": "List of instruments positions.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "`ISIN` or other identity (depends on instrument_id_type) of the security to be transferred." }, "id_type": { "type": "string", "description": "Type of the instrument_id\n* `ISIN` - International Securities Identification Number", "enum": [ "ISIN" ] }, "quantity": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$", "description": "The quantity of instrument to move in or out." }, "quantity_settled": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$", "description": "The quantity of instruments settled." }, "status": { "type": "string", "description": "Status of the securities transfer\n* `NEW` - Securities transfer is created but not started processing.\n* `PROCESSING` - Securities transfer is in processing.\n* `SETTLED` - Securities transfer was successfully settled.\n* `CANCELLED` - Securities transfer was cancelled.", "enum": [ "NEW", "PROCESSING", "SETTLED", "CANCELLED" ] }, "transfer_id": { "type": "string", "description": "Securities transfer request unique identifier.", "format": "uuid" } }, "required": [ "id", "id_type", "quantity", "status", "transfer_id" ] } }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "settlement_reference": { "type": "string", "pattern": "^[0-9A-Za-z+?/\\-:()\\.,' ]*$", "description": "Unique identifier of the account transfer set by API consumers. Useful for API consumers to build special logic on top of it.\n*NOTE: This reference will be set and be common to all securities transfers.*" }, "counterparty": { "title": "Counterparty", "description": "Counterparty for account transfer. The `type` field determines which counterparty variant is present in the payload.", "oneOf": [ { "type": "object", "title": "Account transfer counterparty - BIC", "description": "Counterparty with BIC (Bank Identifier Code) based identification for account transfer.", "properties": { "type": { "default": "BIC", "type": "string", "description": "Type of the counterparty." }, "id": { "title": "Business Identifier Code", "type": "string", "description": "Business Identifier Code (also known as SWIFT-BIC, BIC, SWIFT ID or SWIFT code) [ISO 9362](https://en.wikipedia.org/wiki/ISO_9362).", "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$" }, "account_number": { "title": "Account Number", "description": "The account number is composed of valid Swift charset with a max length of 28 if provided. The account number helps other brokers identify the owner of the assets.", "type": "string", "pattern": "^[0-9A-Za-z+?/\\-:()\\.,' ]{0,28}$" }, "name": { "title": "Full name of the counterparty", "description": "The name is going to be split into 4 lines of 35 characters, the split is space based. This means that even if the name is exactly 140 of length, we may drop out the last parts if they don't fit into 4x35.", "type": "string", "pattern": "^[0-9A-Za-z+?/\\-:()\\.,' ]{0,140}$" } }, "required": [ "type", "id" ], "additionalProperties": false } ] }, "trade_date": { "type": "string", "format": "date", "description": "The forecast date when the trade takes place. Date in YYYY-MM-DD format. \n*NOTE: This date mirrors the preliminary date if given in request as input, each single transfer can have their own date according to market needs.*" }, "settlement_date": { "type": "string", "format": "date", "description": "The forecast date when the settlement takes place. Date in YYYY-MM-DD format. \n*NOTE: This date mirrors the preliminary date if given in request as input, each single transfer can have their own date according to market needs.*" }, "order_date": { "type": "string", "format": "date", "description": "Date the transfer request was received from the end user. The regulatory deadline runs from this date. Date in YYYY-MM-DD format." }, "delay_reason": { "title": "Delay reason code", "description": "Categorised reason why a securities transfer is delayed past the regulatory deadline.\n* `COUNTERPARTY_NOT_INSTRUCTING` - The counterparty has not yet instructed the transfer.\n* `COUNTERPARTY_NOT_RESPONDING` - The counterparty is not responding.\n* `COUNTERPARTY_DOES_NOT_AGREE_TO_DELIVERY_DETAILS` - The counterparty does not agree to the delivery details.\n* `COUNTERPARTY_NOT_ACCEPTING` - The counterparty is not accepting the transfer.", "type": "string", "enum": [ "COUNTERPARTY_NOT_INSTRUCTING", "COUNTERPARTY_NOT_RESPONDING", "COUNTERPARTY_DOES_NOT_AGREE_TO_DELIVERY_DETAILS", "COUNTERPARTY_NOT_ACCEPTING" ] } }, "required": [ "id", "created_at", "updated_at", "direction", "status", "transfer_type", "instruments", "user_id", "account_id", "settlement_reference", "counterparty" ], "additionalProperties": false }, "examples": { "incoming": { "summary": "INCOMING", "value": { "id": "63da4452-2dd3-4414-a7ca-66c0e3e89645", "created_at": "2025-01-22T14:10:00.00Z", "updated_at": "2025-01-22T14:12:34.56Z", "direction": "INCOMING", "status": "NEW", "transfer_type": "NO_OWNER_CHANGE", "instruments": [ { "id": "US0378331005", "id_type": "ISIN", "quantity": "10", "status": "NEW", "transfer_id": "9637e68f-7065-4131-a072-6d57044ebd8c" }, { "id": "US64110L1061", "id_type": "ISIN", "quantity": "5", "status": "NEW", "transfer_id": "c2f84524-3f05-4849-909c-2998803327d3" } ], "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e", "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4", "settlement_reference": "b82dc5985558fdr2", "counterparty": { "type": "BIC", "id": "ABCDDEFFXXX", "account_number": "1234567891", "name": "Max Mustermann" }, "order_date": "2025-01-21" } }, "outgoing": { "summary": "OUTGOING", "value": { "id": "63da4452-2dd3-4414-a7ca-66c0e3e89645", "created_at": "2025-01-22T14:10:00.00Z", "updated_at": "2025-01-22T14:12:34.56Z", "direction": "OUTGOING", "status": "NEW", "transfer_type": "NO_OWNER_CHANGE", "instruments": [ { "id": "US0378331005", "id_type": "ISIN", "quantity": "10", "status": "NEW", "transfer_id": "9637e68f-7065-4131-a072-6d57044ebd8c" }, { "id": "US64110L1061", "id_type": "ISIN", "quantity": "5", "status": "NEW", "transfer_id": "c2f84524-3f05-4849-909c-2998803327d3" } ], "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e", "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4", "settlement_reference": "b82dc5985558fdr2", "counterparty": { "type": "BIC", "id": "ABCDDEFFXXX", "account_number": "1234567891", "name": "Max Mustermann" }, "order_date": "2025-01-21" } } } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/account_transfers/{account_transfer_id}": { "parameters": [ { "name": "account_transfer_id", "in": "path", "required": true, "description": "The unique identifier of the account transfer. Universally Unique Identifier (UUID).", "schema": { "title": "Account transfer request unique identifier.", "type": "string", "description": "Account transfer request unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_account_transfer", "summary": "Retrieve account transfer", "description": "Retrieve account transfer", "tags": [ "Account Transfers" ], "security": [ { "oauth-client-credentials": [ "account_transfers:admin", "account_transfers:read" ] } ], "responses": { "200": { "description": "Account Transfer object", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "title": "Account transfer request unique identifier.", "type": "string", "description": "Account transfer request unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "direction": { "type": "string", "description": "Direction of the account transfer\n* INCOMING - account transfer is incoming to the user.\n* OUTGOING - account transfer is outgoing from the user.", "enum": [ "INCOMING", "OUTGOING" ] }, "status": { "type": "string", "description": "Status of the account transfer\n* NEW - account transfer is created but not started processing.\n* PROCESSING - account transfer is in processing.\n* SETTLED - account transfer was successfully settled.\n* PARTIALLY_SETTLED - account transfer was partially settled, while some instrument got cancelled.\n* CANCELLED - account transfer was cancelled.", "enum": [ "NEW", "PROCESSING", "SETTLED", "PARTIALLY_SETTLED", "CANCELLED" ] }, "transfer_type": { "type": "string", "description": "Type of the account transfer\n* NO_OWNER_CHANGE - No change of ownership.", "enum": [ "NO_OWNER_CHANGE" ] }, "instruments": { "title": "Instruments", "type": "array", "description": "List of instruments positions.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "`ISIN` or other identity (depends on instrument_id_type) of the security to be transferred." }, "id_type": { "type": "string", "description": "Type of the instrument_id\n* `ISIN` - International Securities Identification Number", "enum": [ "ISIN" ] }, "quantity": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$", "description": "The quantity of instrument to move in or out." }, "quantity_settled": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$", "description": "The quantity of instruments settled." }, "status": { "type": "string", "description": "Status of the securities transfer\n* `NEW` - Securities transfer is created but not started processing.\n* `PROCESSING` - Securities transfer is in processing.\n* `SETTLED` - Securities transfer was successfully settled.\n* `CANCELLED` - Securities transfer was cancelled.", "enum": [ "NEW", "PROCESSING", "SETTLED", "CANCELLED" ] }, "transfer_id": { "type": "string", "description": "Securities transfer request unique identifier.", "format": "uuid" } }, "required": [ "id", "id_type", "quantity", "status", "transfer_id" ] } }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "settlement_reference": { "type": "string", "pattern": "^[0-9A-Za-z+?/\\-:()\\.,' ]*$", "description": "Unique identifier of the account transfer set by API consumers. Useful for API consumers to build special logic on top of it.\n*NOTE: This reference will be set and be common to all securities transfers.*" }, "counterparty": { "title": "Counterparty", "description": "Counterparty for account transfer. The `type` field determines which counterparty variant is present in the payload.", "oneOf": [ { "type": "object", "title": "Account transfer counterparty - BIC", "description": "Counterparty with BIC (Bank Identifier Code) based identification for account transfer.", "properties": { "type": { "default": "BIC", "type": "string", "description": "Type of the counterparty." }, "id": { "title": "Business Identifier Code", "type": "string", "description": "Business Identifier Code (also known as SWIFT-BIC, BIC, SWIFT ID or SWIFT code) [ISO 9362](https://en.wikipedia.org/wiki/ISO_9362).", "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$" }, "account_number": { "title": "Account Number", "description": "The account number is composed of valid Swift charset with a max length of 28 if provided. The account number helps other brokers identify the owner of the assets.", "type": "string", "pattern": "^[0-9A-Za-z+?/\\-:()\\.,' ]{0,28}$" }, "name": { "title": "Full name of the counterparty", "description": "The name is going to be split into 4 lines of 35 characters, the split is space based. This means that even if the name is exactly 140 of length, we may drop out the last parts if they don't fit into 4x35.", "type": "string", "pattern": "^[0-9A-Za-z+?/\\-:()\\.,' ]{0,140}$" } }, "required": [ "type", "id" ], "additionalProperties": false } ] }, "trade_date": { "type": "string", "format": "date", "description": "The forecast date when the trade takes place. Date in YYYY-MM-DD format. \n*NOTE: This date mirrors the preliminary date if given in request as input, each single transfer can have their own date according to market needs.*" }, "settlement_date": { "type": "string", "format": "date", "description": "The forecast date when the settlement takes place. Date in YYYY-MM-DD format. \n*NOTE: This date mirrors the preliminary date if given in request as input, each single transfer can have their own date according to market needs.*" }, "order_date": { "type": "string", "format": "date", "description": "Date the transfer request was received from the end user. The regulatory deadline runs from this date. Date in YYYY-MM-DD format." }, "delay_reason": { "title": "Delay reason code", "description": "Categorised reason why a securities transfer is delayed past the regulatory deadline.\n* `COUNTERPARTY_NOT_INSTRUCTING` - The counterparty has not yet instructed the transfer.\n* `COUNTERPARTY_NOT_RESPONDING` - The counterparty is not responding.\n* `COUNTERPARTY_DOES_NOT_AGREE_TO_DELIVERY_DETAILS` - The counterparty does not agree to the delivery details.\n* `COUNTERPARTY_NOT_ACCEPTING` - The counterparty is not accepting the transfer.", "type": "string", "enum": [ "COUNTERPARTY_NOT_INSTRUCTING", "COUNTERPARTY_NOT_RESPONDING", "COUNTERPARTY_DOES_NOT_AGREE_TO_DELIVERY_DETAILS", "COUNTERPARTY_NOT_ACCEPTING" ] } }, "required": [ "id", "created_at", "updated_at", "direction", "status", "transfer_type", "instruments", "user_id", "account_id", "settlement_reference", "counterparty" ], "additionalProperties": false }, "examples": { "incoming": { "summary": "INCOMING", "value": { "id": "63da4452-2dd3-4414-a7ca-66c0e3e89645", "created_at": "2025-01-22T14:10:00.00Z", "updated_at": "2025-01-22T14:12:34.56Z", "direction": "INCOMING", "status": "SETTLED", "transfer_type": "NO_OWNER_CHANGE", "instruments": [ { "id": "US0378331005", "id_type": "ISIN", "quantity": "10", "status": "SETTLED", "transfer_id": "9637e68f-7065-4131-a072-6d57044ebd8c" }, { "id": "US64110L1061", "id_type": "ISIN", "quantity": "5", "status": "SETTLED", "transfer_id": "c2f84524-3f05-4849-909c-2998803327d3" } ], "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e", "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4", "settlement_reference": "b82dc5985558fdr2", "counterparty": { "type": "BIC", "id": "ABCDDEFFXXX", "account_number": "1234567891", "name": "Max Mustermann" }, "order_date": "2025-01-21", "delay_reason": "COUNTERPARTY_NOT_RESPONDING" } }, "outgoing": { "summary": "OUTGOING", "value": { "id": "63da4452-2dd3-4414-a7ca-66c0e3e89645", "created_at": "2025-01-22T14:10:00.00Z", "updated_at": "2025-01-22T14:12:34.56Z", "direction": "OUTGOING", "status": "SETTLED", "transfer_type": "NO_OWNER_CHANGE", "instruments": [ { "id": "US0378331005", "id_type": "ISIN", "quantity": "10", "status": "SETTLED", "transfer_id": "9637e68f-7065-4131-a072-6d57044ebd8c" }, { "id": "US64110L1061", "id_type": "ISIN", "quantity": "5", "status": "SETTLED", "transfer_id": "c2f84524-3f05-4849-909c-2998803327d3" } ], "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e", "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4", "settlement_reference": "b82dc5985558fdr2", "counterparty": { "type": "BIC", "id": "ABCDDEFFXXX", "account_number": "1234567891", "name": "Max Mustermann" }, "order_date": "2025-01-21", "delay_reason": "COUNTERPARTY_NOT_RESPONDING" } } } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/securities_transfers": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_securities_transfers", "summary": "List securities transfers", "description": "List securities transfers", "tags": [ "Securities Transfers" ], "security": [ { "oauth-client-credentials": [ "securities_transfers:admin", "securities_transfers:read" ] } ], "parameters": [ { "name": "direction", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "INCOMING", "OUTGOING" ] }, "description": "Filter the list by transfer direction." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "updated_at" ], "default": "created_at" }, "description": "Sort the result by `created_at`, `updated_at`." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." }, { "name": "user_id", "in": "query", "required": false, "description": "Filters results by user ID. Universally Unique Identifier (UUID).", "schema": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" } }, { "name": "account_id", "in": "query", "required": false, "description": "Filters results by account ID. Universally Unique Identifier (UUID).", "schema": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" } }, { "name": "account_group_id", "in": "query", "required": false, "description": "Filters results by account group ID. Universally Unique Identifier (UUID).", "schema": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "NEW", "PROCESSING", "CANCELLED", "SETTLED" ] }, "description": "Status of the securities transfer \n* NEW - Securities transfer is created but not started processing. \n* PROCESSING - Securities transfer is in processing. \n* SETTLED - Securities transfer was successfully settled. \n* CANCELLED - Securities transfer was cancelled." } ], "responses": { "200": { "description": "Securities Transfers list", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Security Transfers - List - Response", "type": "object", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "title": "Securities transfer request unique identifier.", "type": "string", "description": "Securities transfer request unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "direction": { "type": "string", "description": "Direction of the securities transfer\n* `INCOMING` - Securities transfer is incoming to the user.\n* `OUTGOING` - Securities transfer is outgoing from the user.", "enum": [ "INCOMING", "OUTGOING" ] }, "status": { "type": "string", "description": "Status of the securities transfer\n* `NEW` - Securities transfer is created but not started processing.\n* `PROCESSING` - Securities transfer is in processing.\n* `SETTLED` - Securities transfer was successfully settled.\n* `CANCELLED` - Securities transfer was cancelled.", "enum": [ "NEW", "PROCESSING", "SETTLED", "CANCELLED" ] }, "transfer_type": { "type": "string", "description": "Type of the securities transfer\n* `NO_OWNER_CHANGE` - No change of ownership.", "enum": [ "NO_OWNER_CHANGE" ] }, "instrument_id": { "type": "string", "description": "`ISIN` or other identity (depends on instrument_id_type) of the security to be transferred." }, "instrument_id_type": { "type": "string", "description": "Type of the instrument_id\n* `ISIN` - International Securities Identification Number", "enum": [ "ISIN" ] }, "quantity": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$", "description": "The quantity of instrument to move in or out." }, "quantity_settled": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$", "description": "The quantity of instruments settled." }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "place_of_settlement": { "title": "Business Identifier Code", "type": "string", "description": "Business Identifier Code (also known as SWIFT-BIC, BIC, SWIFT ID or SWIFT code) [ISO 9362](https://en.wikipedia.org/wiki/ISO_9362).", "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$" }, "settlement_reference": { "type": "string", "pattern": "^[0-9A-Za-z+?/\\-:()\\.,' ]*$", "description": "Unique identifier of the securities transfer set by API consumers. Useful for API consumers to build special logic on top of it.\n*NOTE: For automatic incoming transfers where API users will subscribe to the corresponding webhook, the value is set by Upvest!*" }, "counterparty": { "title": "Counterparty", "description": "Counterparty for securities transfer. The `type` field determines which counterparty variant is present in the payload.", "oneOf": [ { "type": "object", "title": "Securities transfer counterparty - BIC", "description": "Counterparty with BIC (Bank Identifier Code) based identification for securities transfer.", "properties": { "type": { "default": "BIC", "type": "string", "description": "Type of the counterparty." }, "id": { "title": "Business Identifier Code", "type": "string", "description": "Business Identifier Code (also known as SWIFT-BIC, BIC, SWIFT ID or SWIFT code) [ISO 9362](https://en.wikipedia.org/wiki/ISO_9362).", "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$" }, "account_number": { "title": "Account Number", "description": "The account number is composed of valid Swift charset with a max length of 28 if provided. The account number helps other brokers identify the owner of the assets.", "type": "string", "pattern": "^[0-9A-Za-z+?/\\-:()\\.,' ]{0,28}$" }, "name": { "title": "Full name of the counterparty", "description": "The name is going to be split into 4 lines of 35 characters, the split is space based. This means that even if the name is exactly 140 of length, we may drop out the last parts if they don't fit into 4x35.", "type": "string", "pattern": "^[0-9A-Za-z+?/\\-:()\\.,' ]{0,140}$" } }, "required": [ "type", "id" ], "additionalProperties": false } ] }, "settlement_counterparties": { "title": "Settlement Counterparties", "description": "Settlement counterparties for the securities transfer.\nWhen `settlement_counterparties` is provided, `settlement_agent` is required. Other participants are optional but must respect the following dependency rules:\n* `settlement_custodian` presence requires `settlement_party` to be present.\n* `settlement_intermediary_1` presence requires `settlement_custodian` to be present.\n* `settlement_intermediary_2` presence requires `settlement_intermediary_1` to be present.\n\n Note: `settlement_custodian` can be provided without an explicit `settlement_party` since the default `counterparty` field at transfer level serves as the settlement party.", "type": "object", "properties": { "settlement_agent": { "title": "Settlement Counterparty", "description": "A participant in the settlement chain, identified by an identification and an optional account.", "type": "object", "properties": { "identification": { "title": "Settlement Counterparty Identification", "description": "Identification of a settlement counterparty.\n* `BIC` Party identified by BIC.\n* `PROPRIETARY` Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` Party identified by name and address.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of identification.\n* `BIC` - Party identified by BIC.\n* `PROPRIETARY` - Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` - Party identified by name and address.", "enum": [ "BIC", "PROPRIETARY", "NAME_AND_ADDRESS" ] }, "value": { "type": "string", "description": "Identification value. The format depends on the `type`:\n* For `BIC`: A valid BIC code.\n* For `PROPRIETARY`: A proprietary identifier under the given `scheme`.\n* For `NAME_AND_ADDRESS`: Name and address of the party." }, "scheme": { "type": "string", "pattern": "^[A-Z]{1,8}$", "description": "ISO Data Source Scheme code. **Required** when `type` is `PROPRIETARY`. Identifies the source of the proprietary identification (e.g. `CRST`, `DAKV`, `CEDE`)." } }, "required": [ "type", "value" ], "additionalProperties": false }, "account": { "title": "Settlement Counterparty Account", "description": "Account of a settlement counterparty.\n* `SAFE` - Safekeeping account.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of the account.\n* `SAFE` - Safekeeping account.", "enum": [ "SAFE" ] }, "value": { "type": "string", "description": "Account identifier value." } }, "required": [ "type", "value" ], "additionalProperties": false } }, "required": [ "identification" ], "additionalProperties": false }, "settlement_custodian": { "title": "Settlement Counterparty", "description": "A participant in the settlement chain, identified by an identification and an optional account.", "type": "object", "properties": { "identification": { "title": "Settlement Counterparty Identification", "description": "Identification of a settlement counterparty.\n* `BIC` Party identified by BIC.\n* `PROPRIETARY` Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` Party identified by name and address.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of identification.\n* `BIC` - Party identified by BIC.\n* `PROPRIETARY` - Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` - Party identified by name and address.", "enum": [ "BIC", "PROPRIETARY", "NAME_AND_ADDRESS" ] }, "value": { "type": "string", "description": "Identification value. The format depends on the `type`:\n* For `BIC`: A valid BIC code.\n* For `PROPRIETARY`: A proprietary identifier under the given `scheme`.\n* For `NAME_AND_ADDRESS`: Name and address of the party." }, "scheme": { "type": "string", "pattern": "^[A-Z]{1,8}$", "description": "ISO Data Source Scheme code. **Required** when `type` is `PROPRIETARY`. Identifies the source of the proprietary identification (e.g. `CRST`, `DAKV`, `CEDE`)." } }, "required": [ "type", "value" ], "additionalProperties": false }, "account": { "title": "Settlement Counterparty Account", "description": "Account of a settlement counterparty.\n* `SAFE` - Safekeeping account.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of the account.\n* `SAFE` - Safekeeping account.", "enum": [ "SAFE" ] }, "value": { "type": "string", "description": "Account identifier value." } }, "required": [ "type", "value" ], "additionalProperties": false } }, "required": [ "identification" ], "additionalProperties": false }, "settlement_intermediary_1": { "title": "Settlement Counterparty", "description": "A participant in the settlement chain, identified by an identification and an optional account.", "type": "object", "properties": { "identification": { "title": "Settlement Counterparty Identification", "description": "Identification of a settlement counterparty.\n* `BIC` Party identified by BIC.\n* `PROPRIETARY` Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` Party identified by name and address.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of identification.\n* `BIC` - Party identified by BIC.\n* `PROPRIETARY` - Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` - Party identified by name and address.", "enum": [ "BIC", "PROPRIETARY", "NAME_AND_ADDRESS" ] }, "value": { "type": "string", "description": "Identification value. The format depends on the `type`:\n* For `BIC`: A valid BIC code.\n* For `PROPRIETARY`: A proprietary identifier under the given `scheme`.\n* For `NAME_AND_ADDRESS`: Name and address of the party." }, "scheme": { "type": "string", "pattern": "^[A-Z]{1,8}$", "description": "ISO Data Source Scheme code. **Required** when `type` is `PROPRIETARY`. Identifies the source of the proprietary identification (e.g. `CRST`, `DAKV`, `CEDE`)." } }, "required": [ "type", "value" ], "additionalProperties": false }, "account": { "title": "Settlement Counterparty Account", "description": "Account of a settlement counterparty.\n* `SAFE` - Safekeeping account.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of the account.\n* `SAFE` - Safekeeping account.", "enum": [ "SAFE" ] }, "value": { "type": "string", "description": "Account identifier value." } }, "required": [ "type", "value" ], "additionalProperties": false } }, "required": [ "identification" ], "additionalProperties": false }, "settlement_intermediary_2": { "title": "Settlement Counterparty", "description": "A participant in the settlement chain, identified by an identification and an optional account.", "type": "object", "properties": { "identification": { "title": "Settlement Counterparty Identification", "description": "Identification of a settlement counterparty.\n* `BIC` Party identified by BIC.\n* `PROPRIETARY` Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` Party identified by name and address.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of identification.\n* `BIC` - Party identified by BIC.\n* `PROPRIETARY` - Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` - Party identified by name and address.", "enum": [ "BIC", "PROPRIETARY", "NAME_AND_ADDRESS" ] }, "value": { "type": "string", "description": "Identification value. The format depends on the `type`:\n* For `BIC`: A valid BIC code.\n* For `PROPRIETARY`: A proprietary identifier under the given `scheme`.\n* For `NAME_AND_ADDRESS`: Name and address of the party." }, "scheme": { "type": "string", "pattern": "^[A-Z]{1,8}$", "description": "ISO Data Source Scheme code. **Required** when `type` is `PROPRIETARY`. Identifies the source of the proprietary identification (e.g. `CRST`, `DAKV`, `CEDE`)." } }, "required": [ "type", "value" ], "additionalProperties": false }, "account": { "title": "Settlement Counterparty Account", "description": "Account of a settlement counterparty.\n* `SAFE` - Safekeeping account.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of the account.\n* `SAFE` - Safekeeping account.", "enum": [ "SAFE" ] }, "value": { "type": "string", "description": "Account identifier value." } }, "required": [ "type", "value" ], "additionalProperties": false } }, "required": [ "identification" ], "additionalProperties": false }, "settlement_party": { "title": "Settlement Counterparty", "description": "A participant in the settlement chain, identified by an identification and an optional account.", "type": "object", "properties": { "identification": { "title": "Settlement Counterparty Identification", "description": "Identification of a settlement counterparty.\n* `BIC` Party identified by BIC.\n* `PROPRIETARY` Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` Party identified by name and address.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of identification.\n* `BIC` - Party identified by BIC.\n* `PROPRIETARY` - Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` - Party identified by name and address.", "enum": [ "BIC", "PROPRIETARY", "NAME_AND_ADDRESS" ] }, "value": { "type": "string", "description": "Identification value. The format depends on the `type`:\n* For `BIC`: A valid BIC code.\n* For `PROPRIETARY`: A proprietary identifier under the given `scheme`.\n* For `NAME_AND_ADDRESS`: Name and address of the party." }, "scheme": { "type": "string", "pattern": "^[A-Z]{1,8}$", "description": "ISO Data Source Scheme code. **Required** when `type` is `PROPRIETARY`. Identifies the source of the proprietary identification (e.g. `CRST`, `DAKV`, `CEDE`)." } }, "required": [ "type", "value" ], "additionalProperties": false }, "account": { "title": "Settlement Counterparty Account", "description": "Account of a settlement counterparty.\n* `SAFE` - Safekeeping account.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of the account.\n* `SAFE` - Safekeeping account.", "enum": [ "SAFE" ] }, "value": { "type": "string", "description": "Account identifier value." } }, "required": [ "type", "value" ], "additionalProperties": false } }, "required": [ "identification" ], "additionalProperties": false } }, "required": [ "settlement_agent" ], "additionalProperties": false }, "trade_date": { "type": "string", "format": "date", "description": "The forecast date when the trade takes place. Date in YYYY-MM-DD format." }, "settlement_date": { "type": "string", "format": "date", "description": "The forecast date when the settlement takes place. Date in YYYY-MM-DD format." }, "actual_settlement_date": { "type": "string", "format": "date", "description": "The date when the transfer settled, only known in `SETTLED` status. Date in YYYY-MM-DD format." }, "order_date": { "type": "string", "format": "date", "description": "Optional. Date the transfer request was received from the end user. The regulatory deadline runs from this date. Date in YYYY-MM-DD format." }, "delay_reason": { "title": "Delay reason code", "description": "Categorised reason why a securities transfer is delayed past the regulatory deadline.\n* `COUNTERPARTY_NOT_INSTRUCTING` - The counterparty has not yet instructed the transfer.\n* `COUNTERPARTY_NOT_RESPONDING` - The counterparty is not responding.\n* `COUNTERPARTY_DOES_NOT_AGREE_TO_DELIVERY_DETAILS` - The counterparty does not agree to the delivery details.\n* `COUNTERPARTY_NOT_ACCEPTING` - The counterparty is not accepting the transfer.", "type": "string", "enum": [ "COUNTERPARTY_NOT_INSTRUCTING", "COUNTERPARTY_NOT_RESPONDING", "COUNTERPARTY_DOES_NOT_AGREE_TO_DELIVERY_DETAILS", "COUNTERPARTY_NOT_ACCEPTING" ] } }, "required": [ "id", "created_at", "updated_at", "user_id", "account_id", "direction", "status", "transfer_type", "instrument_id", "instrument_id_type", "quantity", "counterparty", "settlement_reference", "trade_date", "settlement_date" ], "additionalProperties": false } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "examples": { "incoming": { "summary": "INCOMING", "value": { "meta": { "offset": 0, "limit": 100, "count": 2, "total_count": 2, "sort": "created_at", "order": "ASC" }, "data": [ { "id": "9637e68f-7065-4131-a072-6d57044ebd8c", "created_at": "2024-01-22T14:10:00.00Z", "updated_at": "2024-01-22T14:12:34.56Z", "direction": "INCOMING", "status": "NEW", "transfer_type": "NO_OWNER_CHANGE", "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "quantity": "10", "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e", "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4", "settlement_reference": "b82dc5985558fdr2", "counterparty": { "type": "BIC", "id": "DUMBZZ33XXX", "account_number": "1234567891", "name": "Max Mustermann" }, "settlement_counterparties": { "settlement_agent": { "identification": { "type": "BIC", "value": "FAKEZZ55XXX" }, "account": { "type": "SAFE", "value": "DAKV1234" } }, "settlement_party": { "identification": { "type": "BIC", "value": "DUMBZZ33XXX" }, "account": { "type": "SAFE", "value": "1234567891" } } }, "place_of_settlement": "DAKVDEFFXXX", "trade_date": "2024-01-22", "settlement_date": "2024-01-23", "order_date": "2024-01-20" }, { "id": "64464124-18a2-4886-bc9f-c1b41fa8e4df", "created_at": "2025-01-22T14:10:00.00Z", "updated_at": "2025-01-22T14:12:34.56Z", "direction": "INCOMING", "status": "SETTLED", "transfer_type": "NO_OWNER_CHANGE", "instrument_id": "US88160R1014", "instrument_id_type": "ISIN", "quantity": "5", "quantity_settled": "5", "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e", "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4", "settlement_reference": "b82dc5985558fdr2", "counterparty": { "type": "BIC", "id": "DUMBZZ33XXX", "account_number": "1234567891", "name": "Max Mustermann" }, "settlement_counterparties": { "settlement_agent": { "identification": { "type": "BIC", "value": "FAKEZZ55XXX" }, "account": { "type": "SAFE", "value": "DAKV1234" } }, "settlement_party": { "identification": { "type": "BIC", "value": "DUMBZZ33XXX" }, "account": { "type": "SAFE", "value": "1234567891" } } }, "place_of_settlement": "CEDELULLXXX", "trade_date": "2024-01-22", "settlement_date": "2024-01-23", "actual_settlement_date": "2024-01-24", "order_date": "2023-12-20", "delay_reason": "COUNTERPARTY_NOT_RESPONDING" } ] } }, "outgoing": { "summary": "OUTGOING", "value": { "meta": { "offset": 0, "limit": 100, "count": 2, "total_count": 2, "sort": "created_at", "order": "ASC" }, "data": [ { "id": "9637e68f-7065-4131-a072-6d57044ebd8c", "created_at": "2024-01-22T14:10:00.00Z", "updated_at": "2024-01-22T14:12:34.56Z", "direction": "OUTGOING", "status": "NEW", "transfer_type": "NO_OWNER_CHANGE", "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "quantity": "10", "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e", "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4", "settlement_reference": "b82dc5985558fdr2", "counterparty": { "type": "BIC", "id": "DUMBZZ33XXX", "account_number": "1234567891", "name": "Max Mustermann" }, "settlement_counterparties": { "settlement_agent": { "identification": { "type": "BIC", "value": "FAKEZZ55XXX" }, "account": { "type": "SAFE", "value": "DAKV1234" } }, "settlement_party": { "identification": { "type": "BIC", "value": "DUMBZZ33XXX" }, "account": { "type": "SAFE", "value": "1234567891" } } }, "place_of_settlement": "DAKVDEFFXXX", "trade_date": "2024-01-22", "settlement_date": "2024-01-23", "order_date": "2024-01-20" }, { "id": "64464124-18a2-4886-bc9f-c1b41fa8e4df", "created_at": "2025-01-22T14:10:00.00Z", "updated_at": "2025-01-22T14:12:34.56Z", "direction": "OUTGOING", "status": "SETTLED", "transfer_type": "NO_OWNER_CHANGE", "instrument_id": "US88160R1014", "instrument_id_type": "ISIN", "quantity": "5", "quantity_settled": "5", "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e", "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4", "settlement_reference": "b82dc5985558fdr2", "counterparty": { "type": "BIC", "id": "DUMBZZ33XXX", "account_number": "1234567891", "name": "Max Mustermann" }, "settlement_counterparties": { "settlement_agent": { "identification": { "type": "BIC", "value": "FAKEZZ55XXX" }, "account": { "type": "SAFE", "value": "DAKV1234" } }, "settlement_party": { "identification": { "type": "BIC", "value": "DUMBZZ33XXX" }, "account": { "type": "SAFE", "value": "1234567891" } } }, "place_of_settlement": "CEDELULLXXX", "trade_date": "2024-01-22", "settlement_date": "2024-01-23", "actual_settlement_date": "2024-01-24", "order_date": "2023-12-20", "delay_reason": "COUNTERPARTY_NOT_RESPONDING" } ] } } } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "post": { "operationId": "create_securities_transfer", "summary": "Create securities transfer", "description": "Create securities transfer", "tags": [ "Securities Transfers" ], "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$", "example": "ccb07f42-4104-44ad-8e1f-c660bb7b269c" }, "description": "A UUID to be used as an idempotency key. This prevents a duplicate request from being replayed.\nhttps://docs.upvest.co/documentation/concepts/api_concepts/idempotency\n" } ], "security": [ { "oauth-client-credentials": [ "securities_transfers:admin" ] } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Transfers - Securities Transfer - Create - Request", "type": "object", "properties": { "direction": { "type": "string", "description": "Direction of the securities transfer\n* `INCOMING` - Securities transfer is incoming to the user.\n* `OUTGOING` - Securities transfer is outgoing from the user.", "enum": [ "INCOMING", "OUTGOING" ] }, "instrument_id": { "type": "string", "description": "`ISIN` or other identity (depends on instrument_id_type) of the security to be transferred." }, "instrument_id_type": { "type": "string", "description": "Type of the instrument_id\n* `ISIN` - International Securities Identification Number", "enum": [ "ISIN" ] }, "quantity": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$", "description": "The quantity of instrument to move in or out. The value supported is maximum 15 digits including decimal place.\n*Note: For `INCOMING` the end user ensures that they don't sell their instruments on the counter-broker to enable smooth transfer of their instruments on Upvest platform.*" }, "transfer_type": { "type": "string", "description": "Type of the securities transfer\n* NO_OWNER_CHANGE - No change of ownership.", "enum": [ "NO_OWNER_CHANGE" ] }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "place_of_settlement": { "title": "Business Identifier Code", "type": "string", "description": "Business Identifier Code (also known as SWIFT-BIC, BIC, SWIFT ID or SWIFT code) [ISO 9362](https://en.wikipedia.org/wiki/ISO_9362).", "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$" }, "settlement_reference": { "type": "string", "pattern": "^[0-9A-Za-z+?/\\-:()\\.,' ]*$", "description": "Unique identifier of the securities transfer set by API consumers. Useful for API consumers to build special logic on top of it.\n*NOTE: For automatic incoming transfers where API users will subscribe to the corresponding webhook, the value is set by Upvest!*\n*TIP: For non-live environment if you prefix the reference with `AUTO` your transfer gets through all lifecycle states.*" }, "counterparty": { "title": "Counterparty", "description": "Counterparty for securities transfer. The `type` field determines which counterparty variant is present in the payload.", "oneOf": [ { "type": "object", "title": "Securities transfer counterparty - BIC", "description": "Counterparty with BIC (Bank Identifier Code) based identification for securities transfer.", "properties": { "type": { "default": "BIC", "type": "string", "description": "Type of the counterparty." }, "id": { "title": "Business Identifier Code", "type": "string", "description": "Business Identifier Code (also known as SWIFT-BIC, BIC, SWIFT ID or SWIFT code) [ISO 9362](https://en.wikipedia.org/wiki/ISO_9362).", "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$" }, "account_number": { "title": "Account Number", "description": "The account number is composed of valid Swift charset with a max length of 28 if provided. The account number helps other brokers identify the owner of the assets.", "type": "string", "pattern": "^[0-9A-Za-z+?/\\-:()\\.,' ]{0,28}$" }, "name": { "title": "Full name of the counterparty", "description": "The name is going to be split into 4 lines of 35 characters, the split is space based. This means that even if the name is exactly 140 of length, we may drop out the last parts if they don't fit into 4x35.", "type": "string", "pattern": "^[0-9A-Za-z+?/\\-:()\\.,' ]{0,140}$" } }, "required": [ "type", "id" ], "additionalProperties": false } ] }, "settlement_counterparties": { "title": "Settlement Counterparties", "description": "Settlement counterparties for the securities transfer.\nWhen `settlement_counterparties` is provided, `settlement_agent` is required. Other participants are optional but must respect the following dependency rules:\n* `settlement_custodian` presence requires `settlement_party` to be present.\n* `settlement_intermediary_1` presence requires `settlement_custodian` to be present.\n* `settlement_intermediary_2` presence requires `settlement_intermediary_1` to be present.\n\n Note: `settlement_custodian` can be provided without an explicit `settlement_party` since the default `counterparty` field at transfer level serves as the settlement party.", "type": "object", "properties": { "settlement_agent": { "title": "Settlement Counterparty", "description": "A participant in the settlement chain, identified by an identification and an optional account.", "type": "object", "properties": { "identification": { "title": "Settlement Counterparty Identification", "description": "Identification of a settlement counterparty.\n* `BIC` Party identified by BIC.\n* `PROPRIETARY` Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` Party identified by name and address.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of identification.\n* `BIC` - Party identified by BIC.\n* `PROPRIETARY` - Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` - Party identified by name and address.", "enum": [ "BIC", "PROPRIETARY", "NAME_AND_ADDRESS" ] }, "value": { "type": "string", "description": "Identification value. The format depends on the `type`:\n* For `BIC`: A valid BIC code.\n* For `PROPRIETARY`: A proprietary identifier under the given `scheme`.\n* For `NAME_AND_ADDRESS`: Name and address of the party." }, "scheme": { "type": "string", "pattern": "^[A-Z]{1,8}$", "description": "ISO Data Source Scheme code. **Required** when `type` is `PROPRIETARY`. Identifies the source of the proprietary identification (e.g. `CRST`, `DAKV`, `CEDE`)." } }, "required": [ "type", "value" ], "additionalProperties": false }, "account": { "title": "Settlement Counterparty Account", "description": "Account of a settlement counterparty.\n* `SAFE` - Safekeeping account.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of the account.\n* `SAFE` - Safekeeping account.", "enum": [ "SAFE" ] }, "value": { "type": "string", "description": "Account identifier value." } }, "required": [ "type", "value" ], "additionalProperties": false } }, "required": [ "identification" ], "additionalProperties": false }, "settlement_custodian": { "title": "Settlement Counterparty", "description": "A participant in the settlement chain, identified by an identification and an optional account.", "type": "object", "properties": { "identification": { "title": "Settlement Counterparty Identification", "description": "Identification of a settlement counterparty.\n* `BIC` Party identified by BIC.\n* `PROPRIETARY` Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` Party identified by name and address.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of identification.\n* `BIC` - Party identified by BIC.\n* `PROPRIETARY` - Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` - Party identified by name and address.", "enum": [ "BIC", "PROPRIETARY", "NAME_AND_ADDRESS" ] }, "value": { "type": "string", "description": "Identification value. The format depends on the `type`:\n* For `BIC`: A valid BIC code.\n* For `PROPRIETARY`: A proprietary identifier under the given `scheme`.\n* For `NAME_AND_ADDRESS`: Name and address of the party." }, "scheme": { "type": "string", "pattern": "^[A-Z]{1,8}$", "description": "ISO Data Source Scheme code. **Required** when `type` is `PROPRIETARY`. Identifies the source of the proprietary identification (e.g. `CRST`, `DAKV`, `CEDE`)." } }, "required": [ "type", "value" ], "additionalProperties": false }, "account": { "title": "Settlement Counterparty Account", "description": "Account of a settlement counterparty.\n* `SAFE` - Safekeeping account.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of the account.\n* `SAFE` - Safekeeping account.", "enum": [ "SAFE" ] }, "value": { "type": "string", "description": "Account identifier value." } }, "required": [ "type", "value" ], "additionalProperties": false } }, "required": [ "identification" ], "additionalProperties": false }, "settlement_intermediary_1": { "title": "Settlement Counterparty", "description": "A participant in the settlement chain, identified by an identification and an optional account.", "type": "object", "properties": { "identification": { "title": "Settlement Counterparty Identification", "description": "Identification of a settlement counterparty.\n* `BIC` Party identified by BIC.\n* `PROPRIETARY` Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` Party identified by name and address.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of identification.\n* `BIC` - Party identified by BIC.\n* `PROPRIETARY` - Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` - Party identified by name and address.", "enum": [ "BIC", "PROPRIETARY", "NAME_AND_ADDRESS" ] }, "value": { "type": "string", "description": "Identification value. The format depends on the `type`:\n* For `BIC`: A valid BIC code.\n* For `PROPRIETARY`: A proprietary identifier under the given `scheme`.\n* For `NAME_AND_ADDRESS`: Name and address of the party." }, "scheme": { "type": "string", "pattern": "^[A-Z]{1,8}$", "description": "ISO Data Source Scheme code. **Required** when `type` is `PROPRIETARY`. Identifies the source of the proprietary identification (e.g. `CRST`, `DAKV`, `CEDE`)." } }, "required": [ "type", "value" ], "additionalProperties": false }, "account": { "title": "Settlement Counterparty Account", "description": "Account of a settlement counterparty.\n* `SAFE` - Safekeeping account.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of the account.\n* `SAFE` - Safekeeping account.", "enum": [ "SAFE" ] }, "value": { "type": "string", "description": "Account identifier value." } }, "required": [ "type", "value" ], "additionalProperties": false } }, "required": [ "identification" ], "additionalProperties": false }, "settlement_intermediary_2": { "title": "Settlement Counterparty", "description": "A participant in the settlement chain, identified by an identification and an optional account.", "type": "object", "properties": { "identification": { "title": "Settlement Counterparty Identification", "description": "Identification of a settlement counterparty.\n* `BIC` Party identified by BIC.\n* `PROPRIETARY` Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` Party identified by name and address.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of identification.\n* `BIC` - Party identified by BIC.\n* `PROPRIETARY` - Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` - Party identified by name and address.", "enum": [ "BIC", "PROPRIETARY", "NAME_AND_ADDRESS" ] }, "value": { "type": "string", "description": "Identification value. The format depends on the `type`:\n* For `BIC`: A valid BIC code.\n* For `PROPRIETARY`: A proprietary identifier under the given `scheme`.\n* For `NAME_AND_ADDRESS`: Name and address of the party." }, "scheme": { "type": "string", "pattern": "^[A-Z]{1,8}$", "description": "ISO Data Source Scheme code. **Required** when `type` is `PROPRIETARY`. Identifies the source of the proprietary identification (e.g. `CRST`, `DAKV`, `CEDE`)." } }, "required": [ "type", "value" ], "additionalProperties": false }, "account": { "title": "Settlement Counterparty Account", "description": "Account of a settlement counterparty.\n* `SAFE` - Safekeeping account.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of the account.\n* `SAFE` - Safekeeping account.", "enum": [ "SAFE" ] }, "value": { "type": "string", "description": "Account identifier value." } }, "required": [ "type", "value" ], "additionalProperties": false } }, "required": [ "identification" ], "additionalProperties": false }, "settlement_party": { "title": "Settlement Counterparty", "description": "A participant in the settlement chain, identified by an identification and an optional account.", "type": "object", "properties": { "identification": { "title": "Settlement Counterparty Identification", "description": "Identification of a settlement counterparty.\n* `BIC` Party identified by BIC.\n* `PROPRIETARY` Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` Party identified by name and address.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of identification.\n* `BIC` - Party identified by BIC.\n* `PROPRIETARY` - Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` - Party identified by name and address.", "enum": [ "BIC", "PROPRIETARY", "NAME_AND_ADDRESS" ] }, "value": { "type": "string", "description": "Identification value. The format depends on the `type`:\n* For `BIC`: A valid BIC code.\n* For `PROPRIETARY`: A proprietary identifier under the given `scheme`.\n* For `NAME_AND_ADDRESS`: Name and address of the party." }, "scheme": { "type": "string", "pattern": "^[A-Z]{1,8}$", "description": "ISO Data Source Scheme code. **Required** when `type` is `PROPRIETARY`. Identifies the source of the proprietary identification (e.g. `CRST`, `DAKV`, `CEDE`)." } }, "required": [ "type", "value" ], "additionalProperties": false }, "account": { "title": "Settlement Counterparty Account", "description": "Account of a settlement counterparty.\n* `SAFE` - Safekeeping account.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of the account.\n* `SAFE` - Safekeeping account.", "enum": [ "SAFE" ] }, "value": { "type": "string", "description": "Account identifier value." } }, "required": [ "type", "value" ], "additionalProperties": false } }, "required": [ "identification" ], "additionalProperties": false } }, "required": [ "settlement_agent" ], "additionalProperties": false }, "trade_date": { "type": "string", "format": "date", "description": "Optional forecast date when the trade takes place. If provided, usually T+1 is sufficient. Depending on the market this means valid working days. Date in YYYY-MM-DD format." }, "settlement_date": { "type": "string", "format": "date", "description": "Optional forecast date when the settlement takes place. If provided, usually T+2 is sufficient or trade_date + 1. Depending on the market this means valid working days. Date in YYYY-MM-DD format." }, "order_date": { "type": "string", "format": "date", "description": "Optional date when the transfer request was received from the end user. If omitted, Upvest defaults `order_date` to the transfer's `created_at` timestamp. The regulatory deadline runs from this date. Date in YYYY-MM-DD format." } }, "required": [ "direction", "user_id", "account_id", "instrument_id", "instrument_id_type", "quantity", "transfer_type", "settlement_reference", "counterparty" ], "additionalProperties": false }, "examples": { "incoming": { "summary": "INCOMING", "value": { "direction": "INCOMING", "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "quantity": "10", "transfer_type": "NO_OWNER_CHANGE", "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e", "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4", "settlement_reference": "b82dc5985558fdr2", "order_date": "2024-01-20", "counterparty": { "type": "BIC", "id": "DUMBZZ33XXX", "account_number": "1234567891", "name": "Max Mustermann" } } }, "incoming (BYOL Omnibus)": { "summary": "INCOMING (BYOL Omnibus)", "value": { "direction": "INCOMING", "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "quantity": "10", "transfer_type": "NO_OWNER_CHANGE", "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e", "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4", "settlement_reference": "b82dc5985558fdr2", "counterparty": { "type": "BIC", "id": "DUMBZZ33XXX", "account_number": "1234567891", "name": "Max Mustermann" }, "settlement_counterparties": { "settlement_agent": { "identification": { "type": "BIC", "value": "FAKEZZ55XXX" }, "account": { "type": "SAFE", "value": "DAKV1234" } }, "settlement_party": { "identification": { "type": "BIC", "value": "DUMBZZ33XXX" }, "account": { "type": "SAFE", "value": "1234567891" } } }, "place_of_settlement": "DAKVDEFFXXX", "trade_date": "2024-01-22", "settlement_date": "2024-01-23", "order_date": "2024-01-20" } }, "outgoing": { "summary": "OUTGOING", "value": { "direction": "OUTGOING", "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "quantity": "10", "transfer_type": "NO_OWNER_CHANGE", "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e", "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4", "settlement_reference": "b82dc5985558fdr2", "order_date": "2024-01-20", "counterparty": { "type": "BIC", "id": "DUMBZZ33XXX", "account_number": "1234567891", "name": "Max Mustermann" } } }, "outgoing (BYOL Omnibus)": { "summary": "OUTGOING (BYOL Omnibus)", "value": { "direction": "OUTGOING", "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "quantity": "10", "transfer_type": "NO_OWNER_CHANGE", "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e", "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4", "settlement_reference": "b82dc5985558fdr2", "counterparty": { "type": "BIC", "id": "DUMBZZ33XXX", "account_number": "1234567891", "name": "Max Mustermann" }, "settlement_counterparties": { "settlement_agent": { "identification": { "type": "BIC", "value": "FAKEZZ55XXX" }, "account": { "type": "SAFE", "value": "DAKV1234" } }, "settlement_party": { "identification": { "type": "BIC", "value": "DUMBZZ33XXX" }, "account": { "type": "SAFE", "value": "1234567891" } } }, "place_of_settlement": "DAKVDEFFXXX", "trade_date": "2024-01-22", "settlement_date": "2024-01-23", "order_date": "2024-01-20" } } } } } }, "responses": { "200": { "description": "Securities Transfer created", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "title": "Securities transfer request unique identifier.", "type": "string", "description": "Securities transfer request unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "direction": { "type": "string", "description": "Direction of the securities transfer\n* `INCOMING` - Securities transfer is incoming to the user.\n* `OUTGOING` - Securities transfer is outgoing from the user.", "enum": [ "INCOMING", "OUTGOING" ] }, "status": { "type": "string", "description": "Status of the securities transfer\n* `NEW` - Securities transfer is created but not started processing.\n* `PROCESSING` - Securities transfer is in processing.\n* `SETTLED` - Securities transfer was successfully settled.\n* `CANCELLED` - Securities transfer was cancelled.", "enum": [ "NEW", "PROCESSING", "SETTLED", "CANCELLED" ] }, "transfer_type": { "type": "string", "description": "Type of the securities transfer\n* `NO_OWNER_CHANGE` - No change of ownership.", "enum": [ "NO_OWNER_CHANGE" ] }, "instrument_id": { "type": "string", "description": "`ISIN` or other identity (depends on instrument_id_type) of the security to be transferred." }, "instrument_id_type": { "type": "string", "description": "Type of the instrument_id\n* `ISIN` - International Securities Identification Number", "enum": [ "ISIN" ] }, "quantity": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$", "description": "The quantity of instrument to move in or out." }, "quantity_settled": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$", "description": "The quantity of instruments settled." }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "place_of_settlement": { "title": "Business Identifier Code", "type": "string", "description": "Business Identifier Code (also known as SWIFT-BIC, BIC, SWIFT ID or SWIFT code) [ISO 9362](https://en.wikipedia.org/wiki/ISO_9362).", "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$" }, "settlement_reference": { "type": "string", "pattern": "^[0-9A-Za-z+?/\\-:()\\.,' ]*$", "description": "Unique identifier of the securities transfer set by API consumers. Useful for API consumers to build special logic on top of it.\n*NOTE: For automatic incoming transfers where API users will subscribe to the corresponding webhook, the value is set by Upvest!*" }, "counterparty": { "title": "Counterparty", "description": "Counterparty for securities transfer. The `type` field determines which counterparty variant is present in the payload.", "oneOf": [ { "type": "object", "title": "Securities transfer counterparty - BIC", "description": "Counterparty with BIC (Bank Identifier Code) based identification for securities transfer.", "properties": { "type": { "default": "BIC", "type": "string", "description": "Type of the counterparty." }, "id": { "title": "Business Identifier Code", "type": "string", "description": "Business Identifier Code (also known as SWIFT-BIC, BIC, SWIFT ID or SWIFT code) [ISO 9362](https://en.wikipedia.org/wiki/ISO_9362).", "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$" }, "account_number": { "title": "Account Number", "description": "The account number is composed of valid Swift charset with a max length of 28 if provided. The account number helps other brokers identify the owner of the assets.", "type": "string", "pattern": "^[0-9A-Za-z+?/\\-:()\\.,' ]{0,28}$" }, "name": { "title": "Full name of the counterparty", "description": "The name is going to be split into 4 lines of 35 characters, the split is space based. This means that even if the name is exactly 140 of length, we may drop out the last parts if they don't fit into 4x35.", "type": "string", "pattern": "^[0-9A-Za-z+?/\\-:()\\.,' ]{0,140}$" } }, "required": [ "type", "id" ], "additionalProperties": false } ] }, "settlement_counterparties": { "title": "Settlement Counterparties", "description": "Settlement counterparties for the securities transfer.\nWhen `settlement_counterparties` is provided, `settlement_agent` is required. Other participants are optional but must respect the following dependency rules:\n* `settlement_custodian` presence requires `settlement_party` to be present.\n* `settlement_intermediary_1` presence requires `settlement_custodian` to be present.\n* `settlement_intermediary_2` presence requires `settlement_intermediary_1` to be present.\n\n Note: `settlement_custodian` can be provided without an explicit `settlement_party` since the default `counterparty` field at transfer level serves as the settlement party.", "type": "object", "properties": { "settlement_agent": { "title": "Settlement Counterparty", "description": "A participant in the settlement chain, identified by an identification and an optional account.", "type": "object", "properties": { "identification": { "title": "Settlement Counterparty Identification", "description": "Identification of a settlement counterparty.\n* `BIC` Party identified by BIC.\n* `PROPRIETARY` Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` Party identified by name and address.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of identification.\n* `BIC` - Party identified by BIC.\n* `PROPRIETARY` - Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` - Party identified by name and address.", "enum": [ "BIC", "PROPRIETARY", "NAME_AND_ADDRESS" ] }, "value": { "type": "string", "description": "Identification value. The format depends on the `type`:\n* For `BIC`: A valid BIC code.\n* For `PROPRIETARY`: A proprietary identifier under the given `scheme`.\n* For `NAME_AND_ADDRESS`: Name and address of the party." }, "scheme": { "type": "string", "pattern": "^[A-Z]{1,8}$", "description": "ISO Data Source Scheme code. **Required** when `type` is `PROPRIETARY`. Identifies the source of the proprietary identification (e.g. `CRST`, `DAKV`, `CEDE`)." } }, "required": [ "type", "value" ], "additionalProperties": false }, "account": { "title": "Settlement Counterparty Account", "description": "Account of a settlement counterparty.\n* `SAFE` - Safekeeping account.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of the account.\n* `SAFE` - Safekeeping account.", "enum": [ "SAFE" ] }, "value": { "type": "string", "description": "Account identifier value." } }, "required": [ "type", "value" ], "additionalProperties": false } }, "required": [ "identification" ], "additionalProperties": false }, "settlement_custodian": { "title": "Settlement Counterparty", "description": "A participant in the settlement chain, identified by an identification and an optional account.", "type": "object", "properties": { "identification": { "title": "Settlement Counterparty Identification", "description": "Identification of a settlement counterparty.\n* `BIC` Party identified by BIC.\n* `PROPRIETARY` Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` Party identified by name and address.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of identification.\n* `BIC` - Party identified by BIC.\n* `PROPRIETARY` - Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` - Party identified by name and address.", "enum": [ "BIC", "PROPRIETARY", "NAME_AND_ADDRESS" ] }, "value": { "type": "string", "description": "Identification value. The format depends on the `type`:\n* For `BIC`: A valid BIC code.\n* For `PROPRIETARY`: A proprietary identifier under the given `scheme`.\n* For `NAME_AND_ADDRESS`: Name and address of the party." }, "scheme": { "type": "string", "pattern": "^[A-Z]{1,8}$", "description": "ISO Data Source Scheme code. **Required** when `type` is `PROPRIETARY`. Identifies the source of the proprietary identification (e.g. `CRST`, `DAKV`, `CEDE`)." } }, "required": [ "type", "value" ], "additionalProperties": false }, "account": { "title": "Settlement Counterparty Account", "description": "Account of a settlement counterparty.\n* `SAFE` - Safekeeping account.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of the account.\n* `SAFE` - Safekeeping account.", "enum": [ "SAFE" ] }, "value": { "type": "string", "description": "Account identifier value." } }, "required": [ "type", "value" ], "additionalProperties": false } }, "required": [ "identification" ], "additionalProperties": false }, "settlement_intermediary_1": { "title": "Settlement Counterparty", "description": "A participant in the settlement chain, identified by an identification and an optional account.", "type": "object", "properties": { "identification": { "title": "Settlement Counterparty Identification", "description": "Identification of a settlement counterparty.\n* `BIC` Party identified by BIC.\n* `PROPRIETARY` Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` Party identified by name and address.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of identification.\n* `BIC` - Party identified by BIC.\n* `PROPRIETARY` - Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` - Party identified by name and address.", "enum": [ "BIC", "PROPRIETARY", "NAME_AND_ADDRESS" ] }, "value": { "type": "string", "description": "Identification value. The format depends on the `type`:\n* For `BIC`: A valid BIC code.\n* For `PROPRIETARY`: A proprietary identifier under the given `scheme`.\n* For `NAME_AND_ADDRESS`: Name and address of the party." }, "scheme": { "type": "string", "pattern": "^[A-Z]{1,8}$", "description": "ISO Data Source Scheme code. **Required** when `type` is `PROPRIETARY`. Identifies the source of the proprietary identification (e.g. `CRST`, `DAKV`, `CEDE`)." } }, "required": [ "type", "value" ], "additionalProperties": false }, "account": { "title": "Settlement Counterparty Account", "description": "Account of a settlement counterparty.\n* `SAFE` - Safekeeping account.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of the account.\n* `SAFE` - Safekeeping account.", "enum": [ "SAFE" ] }, "value": { "type": "string", "description": "Account identifier value." } }, "required": [ "type", "value" ], "additionalProperties": false } }, "required": [ "identification" ], "additionalProperties": false }, "settlement_intermediary_2": { "title": "Settlement Counterparty", "description": "A participant in the settlement chain, identified by an identification and an optional account.", "type": "object", "properties": { "identification": { "title": "Settlement Counterparty Identification", "description": "Identification of a settlement counterparty.\n* `BIC` Party identified by BIC.\n* `PROPRIETARY` Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` Party identified by name and address.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of identification.\n* `BIC` - Party identified by BIC.\n* `PROPRIETARY` - Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` - Party identified by name and address.", "enum": [ "BIC", "PROPRIETARY", "NAME_AND_ADDRESS" ] }, "value": { "type": "string", "description": "Identification value. The format depends on the `type`:\n* For `BIC`: A valid BIC code.\n* For `PROPRIETARY`: A proprietary identifier under the given `scheme`.\n* For `NAME_AND_ADDRESS`: Name and address of the party." }, "scheme": { "type": "string", "pattern": "^[A-Z]{1,8}$", "description": "ISO Data Source Scheme code. **Required** when `type` is `PROPRIETARY`. Identifies the source of the proprietary identification (e.g. `CRST`, `DAKV`, `CEDE`)." } }, "required": [ "type", "value" ], "additionalProperties": false }, "account": { "title": "Settlement Counterparty Account", "description": "Account of a settlement counterparty.\n* `SAFE` - Safekeeping account.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of the account.\n* `SAFE` - Safekeeping account.", "enum": [ "SAFE" ] }, "value": { "type": "string", "description": "Account identifier value." } }, "required": [ "type", "value" ], "additionalProperties": false } }, "required": [ "identification" ], "additionalProperties": false }, "settlement_party": { "title": "Settlement Counterparty", "description": "A participant in the settlement chain, identified by an identification and an optional account.", "type": "object", "properties": { "identification": { "title": "Settlement Counterparty Identification", "description": "Identification of a settlement counterparty.\n* `BIC` Party identified by BIC.\n* `PROPRIETARY` Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` Party identified by name and address.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of identification.\n* `BIC` - Party identified by BIC.\n* `PROPRIETARY` - Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` - Party identified by name and address.", "enum": [ "BIC", "PROPRIETARY", "NAME_AND_ADDRESS" ] }, "value": { "type": "string", "description": "Identification value. The format depends on the `type`:\n* For `BIC`: A valid BIC code.\n* For `PROPRIETARY`: A proprietary identifier under the given `scheme`.\n* For `NAME_AND_ADDRESS`: Name and address of the party." }, "scheme": { "type": "string", "pattern": "^[A-Z]{1,8}$", "description": "ISO Data Source Scheme code. **Required** when `type` is `PROPRIETARY`. Identifies the source of the proprietary identification (e.g. `CRST`, `DAKV`, `CEDE`)." } }, "required": [ "type", "value" ], "additionalProperties": false }, "account": { "title": "Settlement Counterparty Account", "description": "Account of a settlement counterparty.\n* `SAFE` - Safekeeping account.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of the account.\n* `SAFE` - Safekeeping account.", "enum": [ "SAFE" ] }, "value": { "type": "string", "description": "Account identifier value." } }, "required": [ "type", "value" ], "additionalProperties": false } }, "required": [ "identification" ], "additionalProperties": false } }, "required": [ "settlement_agent" ], "additionalProperties": false }, "trade_date": { "type": "string", "format": "date", "description": "The forecast date when the trade takes place. Date in YYYY-MM-DD format." }, "settlement_date": { "type": "string", "format": "date", "description": "The forecast date when the settlement takes place. Date in YYYY-MM-DD format." }, "actual_settlement_date": { "type": "string", "format": "date", "description": "The date when the transfer settled, only known in `SETTLED` status. Date in YYYY-MM-DD format." }, "order_date": { "type": "string", "format": "date", "description": "Optional. Date the transfer request was received from the end user. The regulatory deadline runs from this date. Date in YYYY-MM-DD format." }, "delay_reason": { "title": "Delay reason code", "description": "Categorised reason why a securities transfer is delayed past the regulatory deadline.\n* `COUNTERPARTY_NOT_INSTRUCTING` - The counterparty has not yet instructed the transfer.\n* `COUNTERPARTY_NOT_RESPONDING` - The counterparty is not responding.\n* `COUNTERPARTY_DOES_NOT_AGREE_TO_DELIVERY_DETAILS` - The counterparty does not agree to the delivery details.\n* `COUNTERPARTY_NOT_ACCEPTING` - The counterparty is not accepting the transfer.", "type": "string", "enum": [ "COUNTERPARTY_NOT_INSTRUCTING", "COUNTERPARTY_NOT_RESPONDING", "COUNTERPARTY_DOES_NOT_AGREE_TO_DELIVERY_DETAILS", "COUNTERPARTY_NOT_ACCEPTING" ] } }, "required": [ "id", "created_at", "updated_at", "user_id", "account_id", "direction", "status", "transfer_type", "instrument_id", "instrument_id_type", "quantity", "counterparty", "settlement_reference", "trade_date", "settlement_date" ], "additionalProperties": false }, "examples": { "incoming": { "summary": "INCOMING", "value": { "id": "9637e68f-7065-4131-a072-6d57044ebd8c", "created_at": "2024-01-22T14:10:00.00Z", "updated_at": "2024-01-22T14:12:34.56Z", "direction": "INCOMING", "status": "NEW", "transfer_type": "NO_OWNER_CHANGE", "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "quantity": "10", "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e", "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4", "settlement_reference": "b82dc5985558fdr2", "counterparty": { "type": "BIC", "id": "DUMBZZ33XXX", "account_number": "1234567891", "name": "Max Mustermann" }, "settlement_counterparties": { "settlement_agent": { "identification": { "type": "BIC", "value": "FAKEZZ55XXX" }, "account": { "type": "SAFE", "value": "DAKV1234" } }, "settlement_party": { "identification": { "type": "BIC", "value": "DUMBZZ33XXX" }, "account": { "type": "SAFE", "value": "1234567891" } } }, "place_of_settlement": "DAKVDEFFXXX", "trade_date": "2024-01-22", "settlement_date": "2024-01-23", "order_date": "2024-01-20" } }, "outgoing": { "summary": "OUTGOING", "value": { "id": "9637e68f-7065-4131-a072-6d57044ebd8c", "created_at": "2024-01-22T14:10:00.00Z", "updated_at": "2024-01-22T14:12:34.56Z", "direction": "OUTGOING", "status": "NEW", "transfer_type": "NO_OWNER_CHANGE", "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "quantity": "10", "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e", "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4", "settlement_reference": "b82dc5985558fdr2", "counterparty": { "type": "BIC", "id": "DUMBZZ33XXX", "account_number": "1234567891", "name": "Max Mustermann" }, "settlement_counterparties": { "settlement_agent": { "identification": { "type": "BIC", "value": "FAKEZZ55XXX" }, "account": { "type": "SAFE", "value": "DAKV1234" } }, "settlement_party": { "identification": { "type": "BIC", "value": "DUMBZZ33XXX" }, "account": { "type": "SAFE", "value": "1234567891" } } }, "place_of_settlement": "DAKVDEFFXXX", "trade_date": "2024-01-22", "settlement_date": "2024-01-23", "order_date": "2024-01-20" } } } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/isa/transfers": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "post": { "operationId": "create_isa_transfer", "summary": "Create ISA transfer", "description": "Create ISA transfer", "tags": [ "ISA Transfers" ], "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$", "example": "ccb07f42-4104-44ad-8e1f-c660bb7b269c" }, "description": "A UUID to be used as an idempotency key. This prevents a duplicate request from being replayed.\nhttps://docs.upvest.co/documentation/concepts/api_concepts/idempotency\n" } ], "security": [ { "oauth-client-credentials": [ "isa_transfers:admin" ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "direction": { "type": "string", "description": "Direction of the ISA transfer\n* INCOMING - Transfer is incoming to the user.\n* OUTGOING - Transfer is outgoing from the user.", "enum": [ "INCOMING", "OUTGOING" ] }, "transfer_type": { "type": "string", "description": "Type of the securities transfer\n* ISA_INTERNAL - Transfer occurs within the same ISA manager.\n* ISA_EXTERNAL - Transfer occurs across different ISA managers, via Equisoft or others.", "enum": [ "ISA_INTERNAL", "ISA_EXTERNAL" ] }, "transfer_value": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* GBP - Great British Pound", "enum": [ "GBP" ], "default": "GBP" }, "transfer_method": { "type": "string", "description": "Method of the ISA transfer\n* CASH - Cash transfer.\n\nOther methods can be supported in the future, e.g. IN_SPECIE", "enum": [ "CASH" ] }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "reference": { "type": "string", "pattern": "^[0-9A-Za-z+?/\\-:()\\.,' ]*$", "description": "Random string reference on which API clients can build logic." }, "counterparty": { "type": "object", "properties": { "account_number": { "title": "Account Number", "description": "The account number is composed of valid Swift charset with a max length of 28 if provided. The account number helps other brokers identify the owner of the assets.", "type": "string", "pattern": "^[0-9A-Za-z+?/\\-:()\\.,' ]{0,28}$" } }, "required": [ "account_number" ], "additionalProperties": false }, "transfer_date": { "type": "string", "format": "date-time", "description": "The date when end user initiated the transfer. Relevant for tax year's end reporting. If not sent it will be the time we create the transfer internally on our side. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "details": { "type": "object", "properties": { "current_year_subscription": { "type": "object", "description": "Details related to the current year’s subscription being transferred.\n\nRequired if transfer_type is ISA_INTERNAL.", "properties": { "transfer_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "first_subscription_at": { "type": "string", "format": "date-time", "description": "The date of the first subscription made to the ISA in the current tax year. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)\n\n Required if transfer_type is ISA_INTERNAL." } }, "required": [ "transfer_amount" ], "additionalProperties": false } }, "required": [ "current_year_subscription" ], "additionalProperties": false } }, "required": [ "user_id", "account_group_id", "direction", "transfer_type", "currency", "transfer_method", "transfer_date" ], "additionalProperties": false }, "example": { "transfer_type": "ISA_EXTERNAL", "user_id": "2dedfeb0-58cd-55f2-ae08-0e41fe0413d9", "account_group_id": "48043cd0-e306-4b48-bbdd-6ca5d0967009", "direction": "INCOMING", "reference": "4XD8Z53CST3LGEZBYO", "counterparty": { "account_number": "5WJSZB3C8" }, "transfer_value": "10000.00", "currency": "GBP", "transfer_method": "CASH", "transfer_date": "2025-10-10T10:00:00Z", "details": { "current_year_subscription": { "transfer_amount": "2000.00", "first_subscription_at": "2025-09-09T12:50:00Z" } } } } } }, "responses": { "200": { "description": "ISA Transfer created", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "title": "ISA transfer request unique identifier.", "type": "string", "description": "ISA transfer request unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "direction": { "type": "string", "description": "Direction of the ISA transfer\n* INCOMING - Transfer is incoming to the user.\n* OUTGOING - Transfer is outgoing from the user.", "enum": [ "INCOMING", "OUTGOING" ] }, "status": { "type": "string", "description": "Status of the transfer\n* NEW - Transfer is created.\n* DISCOVERY - Discovery with the ceding provider where information about the transfer is being exchanged and reviewed. Only relevant if type ISA_EXTERNAL.\n* DISCOVERY_CONFIRMED - Discovery is completed and transfer request is accepted by the ceding provider. Only relevant if type ISA_EXTERNAL.\n* INSTRUCTED - Transfer is instructed to the ceding provider.\n* PROCESSING - Transfer instruction is confirmed by the ceding provider. Transfer is being processed. \n* SETTLED - Transfer is completed.", "enum": [ "NEW", "DISCOVERY", "DISCOVERY_CONFIRMED", "INSTRUCTED", "PROCESSING", "SETTLED" ] }, "transfer_type": { "type": "string", "description": "Type of the securities transfer\n* ISA_INTERNAL - Transfer occurs within the same ISA manager.\n* ISA_EXTERNAL - Transfer occurs across different ISA managers, via Equisoft or others.", "enum": [ "ISA_INTERNAL", "ISA_EXTERNAL" ] }, "transfer_value": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* GBP - Great British Pound", "enum": [ "GBP" ], "default": "GBP" }, "transfer_method": { "type": "string", "description": "Method of the ISA transfer\n* CASH - Cash transfer.\n\nOther methods can be supported in the future, e.g. IN_SPECIE", "enum": [ "CASH" ] }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "reference": { "type": "string", "pattern": "^[0-9A-Za-z+?/\\-:()\\.,' ]*$", "description": "Random string reference on which API clients can build logic." }, "counterparty": { "type": "object", "properties": { "account_number": { "title": "Account Number", "description": "The account number is composed of valid Swift charset with a max length of 28 if provided. The account number helps other brokers identify the owner of the assets.", "type": "string", "pattern": "^[0-9A-Za-z+?/\\-:()\\.,' ]{0,28}$" } }, "required": [ "account_number" ], "additionalProperties": false }, "transfer_date": { "type": "string", "format": "date-time", "description": "The date when end user initiated the transfer. Relevant for tax year's end reporting. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "details": { "type": "object", "properties": { "current_year_subscription": { "type": "object", "description": "Details related to the current year’s subscription being transferred.\n\nRequired if transfer_type is ISA_INTERNAL.", "properties": { "transfer_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "first_subscription_at": { "type": "string", "format": "date-time", "description": "The date of the first subscription made to the ISA in the current tax year. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)\n\n Required if transfer_type is ISA_INTERNAL." } }, "required": [ "transfer_amount" ], "additionalProperties": false } }, "required": [ "current_year_subscription" ], "additionalProperties": false } }, "required": [ "id", "created_at", "updated_at", "user_id", "account_group_id", "direction", "status", "transfer_type", "currency", "transfer_method", "reference", "transfer_date" ], "additionalProperties": false }, "example": { "id": "9637e68f-7065-4131-a072-6d57044ebd8c", "created_at": "2024-01-22T14:10:00.00Z", "updated_at": "2024-01-22T14:12:34.56Z", "direction": "INCOMING", "status": "NEW", "transfer_type": "ISA_INTERNAL", "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e", "account_group_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4", "reference": "b82dc5985558fdr2", "transfer_value": "10000.00", "currency": "GBP", "transfer_method": "CASH", "counterparty": { "account_number": "1234567891" }, "details": { "current_year_subscription": { "transfer_amount": "2000.00", "first_subscription_at": "2024-01-15T10:00:00.00Z" } }, "transfer_date": "2024-01-22T14:10:00.00Z" } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/virtual_cash_balances/increases": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "post": { "operationId": "create_virtual_cash_increase", "summary": "Trigger a virtual cash increase", "description": "Trigger a virtual cash increase", "tags": [ "Virtual Cash Balances" ], "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$", "example": "ccb07f42-4104-44ad-8e1f-c660bb7b269c" }, "description": "A UUID to be used as an idempotency key. This prevents a duplicate request from being replayed.\nhttps://docs.upvest.co/documentation/concepts/api_concepts/idempotency\n" } ], "security": [ { "oauth-client-credentials": [ "virtual_cash_balances:admin" ] } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Virtual Cash Balance - Virtual Cash Increase - Create - Request", "type": "object", "additionalProperties": false, "properties": { "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling\n* USD - The United States dollar", "enum": [ "EUR", "GBP", "USD" ] } }, "required": [ "account_group_id", "amount", "currency" ] }, "example": { "account_group_id": "2596db3b-0d03-4651-9eda-970910479dfb", "amount": "200.00", "currency": "EUR" } } } }, "responses": { "202": { "description": "Virtual Cash Balances Increase", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Virtual Cash Balance - Virtual Cash Increase", "type": "object", "additionalProperties": false, "properties": { "id": { "title": "Virtual cash unique identifier", "type": "string", "description": "Virtual cash unique identifier", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling\n* USD - The United States dollar", "enum": [ "EUR", "GBP", "USD" ] }, "status": { "type": "string", "description": "Status of the virtual cash\n* ISSUED - Virtual cash increase is created.\n* CONFIRMED - Virtual cash increase was successfully processed.\n* CANCELLED - Virtual cash increase was cancelled.", "enum": [ "ISSUED", "CONFIRMED", "CANCELLED" ] } }, "required": [ "id", "account_group_id", "amount", "currency", "status", "created_at", "updated_at" ] }, "example": { "id": "6ffa6b16-2380-4e7a-88b2-ae625c8eef99", "created_at": "2020-08-24T14:15:22Z", "updated_at": "2020-08-24T14:15:22Z", "account_group_id": "ac1c39e9-2101-46b8-a624-d10a9e351b6c", "amount": "200.00", "currency": "EUR", "status": "ISSUED" } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/virtual_cash_balances/decreases": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "post": { "operationId": "create_virtual_cash_decrease", "summary": "Trigger a virtual cash decrease", "description": "Trigger a virtual cash decrease", "tags": [ "Virtual Cash Balances" ], "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$", "example": "ccb07f42-4104-44ad-8e1f-c660bb7b269c" }, "description": "A UUID to be used as an idempotency key. This prevents a duplicate request from being replayed.\nhttps://docs.upvest.co/documentation/concepts/api_concepts/idempotency\n" } ], "security": [ { "oauth-client-credentials": [ "virtual_cash_balances:admin" ] } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Virtual Cash Balance - Virtual Cash Decrease - Create - Request", "type": "object", "additionalProperties": false, "properties": { "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling\n* USD - The United States dollar", "enum": [ "EUR", "GBP", "USD" ] } }, "required": [ "account_group_id", "amount", "currency" ] }, "example": { "account_group_id": "2596db3b-0d03-4651-9eda-970910479dfb", "amount": "200.00", "currency": "EUR" } } } }, "responses": { "202": { "description": "Virtual Cash Balances Decrease", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Virtual Cash Balance - Virtual Cash Decrease", "type": "object", "additionalProperties": false, "properties": { "id": { "title": "Virtual cash unique identifier", "type": "string", "description": "Virtual cash unique identifier", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling\n* USD - The United States dollar", "enum": [ "EUR", "GBP", "USD" ] }, "status": { "type": "string", "description": "Status of the virtual cash\n* ISSUED - Virtual cash decrease is created.\n* CONFIRMED - Virtual cash decrease was successfully processed.\n* QUEUED - Virtual cash decrease was queued.\n* CANCELLED - Virtual cash decrease was cancelled.", "enum": [ "ISSUED", "CONFIRMED", "QUEUED", "CANCELLED" ] } }, "required": [ "id", "account_group_id", "amount", "currency", "status", "created_at", "updated_at" ] }, "example": { "id": "6ffa6b16-2380-4e7a-88b2-ae625c8eef99", "created_at": "2020-08-24T14:15:22Z", "updated_at": "2020-08-24T14:15:22Z", "account_group_id": "ac1c39e9-2101-46b8-a624-d10a9e351b6c", "amount": "200.00", "currency": "EUR", "status": "ISSUED" } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/virtual_cash_balances/decreases/{virtual_cash_decrease_id}": { "parameters": [ { "name": "virtual_cash_decrease_id", "in": "path", "required": true, "description": "The unique identifier of the virtual cash decrease. Universally Unique Identifier (UUID).", "schema": { "title": "Virtual cash unique identifier", "type": "string", "description": "Virtual cash unique identifier", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "delete": { "operationId": "cancel_virtual_cash_decrease", "summary": "Cancel virtual cash decrease by ID", "description": "Cancels a virtual cash decrease specified by its ID. It is only possible to cancel a virtual cash decrease if it has the status `ISSUED` or `QUEUED`.", "tags": [ "Virtual Cash Balances" ], "security": [ { "oauth-client-credentials": [ "virtual_cash_balances:admin" ] } ], "responses": { "202": { "description": "The request has been successfully accepted and will be processed asynchronously.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "422": { "description": "Unprocessable Entity. The syntax of request is correct but server can't process it due a semantic error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 422, "type": "unprocessable_entity" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/savings_plans/{savings_plan_id}": { "parameters": [ { "name": "savings_plan_id", "in": "path", "required": true, "description": "The unique identifier of the savings plan. Universally Unique Identifier (UUID).", "schema": { "title": "Savings plan unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a savings plan.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_savings_plan", "summary": "Retrieve a savings plan", "description": "Retrieve a savings plan specified by its ID.", "tags": [ "Savings Plans" ], "security": [ { "oauth-client-credentials": [ "savings_plans:read", "savings_plans:admin" ] } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Savings plan (instrument)", "type": "object", "description": "Represents an `INSTRUMENT`-type savings plan — a recurring investment that automatically buys a fixed cash amount of a specified instrument on a defined schedule.", "properties": { "id": { "title": "Savings plan unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a savings plan.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "name": { "type": "string", "description": "Savings plan name" }, "type": { "type": "string", "description": "Type of the Savings plan.\n* PORTFOLIO - \n* INSTRUMENT - ", "enum": [ "PORTFOLIO", "INSTRUMENT" ] }, "instrument_id": { "title": "Instrument unique identifier", "description": "Instrument unique identifier.", "oneOf": [ { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, { "title": "German securities identification code", "type": "string", "description": "German securities identification code known as [Wertpapierkennnummer](https://en.wikipedia.org/wiki/Wertpapierkennnummer).", "pattern": "^[A-HJ-NP-Z0-9]{6}$" } ] }, "instrument_id_type": { "type": "string", "description": "The type of the ID used in the request.\n* ISIN - International Securities Identification Number\n* WKN - German securities identification code", "enum": [ "ISIN", "WKN" ], "default": "ISIN" }, "cash_amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "start_date": { "type": "string", "description": "First date of the savings plan execution in YYYY-MM-DD format.", "pattern": "^[12]\\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "period": { "type": "string", "description": "Unit of time. \n* WEEK - \n* MONTH - \n* YEAR - ", "enum": [ "WEEK", "MONTH", "YEAR" ] }, "interval": { "description": "Number of periods between executions", "type": "integer", "default": 1, "minimum": 1, "maximum": 1000 }, "status": { "type": "string", "description": "Status of a Savings Plan. \n* ACTIVE - \n* CANCELLED - ", "enum": [ "ACTIVE", "CANCELLED" ] }, "fee_configuration": { "title": "Savings plan fee configuration, only for instrument", "type": "array", "description": "Fee configuration for instrument-type savings plan executions. Specifies the transaction fee model to apply to each buy order placed on execution.", "items": { "type": "object", "properties": { "type": { "title": "Fee type", "description": "Fee type\n* TRANSACTION_FEE_BUY -", "type": "string", "enum": [ "TRANSACTION_FEE_BUY" ] }, "transaction_fee_model_id": { "title": "Fee model unique identifier.", "type": "string", "description": "Universally Unique Identifier (UUID) of the transaction fee model.", "format": "uuid" } }, "required": [ "type", "transaction_fee_model_id" ], "additionalProperties": false } }, "cancellation_reason": { "title": "Cancellation reason code for savings plan", "description": "Explains the reason why the savings plan was cancelled .\n* CANCELLED_BY_CLIENT: The savings plan was cancelled by the client.\n* CANCELLED_BY_UPVEST: The savings plan was cancelled by Upvest.", "type": "string", "enum": [ "CANCELLED_BY_CLIENT", "CANCELLED_BY_UPVEST" ] }, "cancellation_details": { "description": "Additional details about the cancellation", "type": "string" } }, "required": [ "id", "user_id", "account_id", "type", "cash_amount", "currency", "start_date", "period", "interval", "created_at", "updated_at" ], "additionalProperties": false }, "examples": { "instrument": { "summary": "instrument", "value": { "id": "fc34d28e-38f5-49d2-92f6-82acb79098f4", "created_at": "2023-07-21T14:10:00.00Z", "updated_at": "2023-07-21T15:10:00.00Z", "user_id": "4b9732bd-7496-4913-8a5f-6360479d7fed", "account_id": "00ef0be8-d564-43af-b3c7-11b7a2188030", "name": "Instrument savings plan", "type": "INSTRUMENT", "instrument_id": "DE0007664005", "instrument_id_type": "ISIN", "cash_amount": "100.00", "currency": "EUR", "start_date": "2023-07-24", "period": "WEEK", "interval": 1, "status": "ACTIVE", "fee_configuration": [ { "type": "TRANSACTION_FEE_BUY", "transaction_fee_model_id": "3ae9403c-1611-46eb-84ee-e06a02bcfd08" } ], "cancellation_reason": "CANCELLED_BY_CLIENT", "cancellation_details": "User requested cancellation" } }, "portfolio": { "summary": "portfolio", "value": { "id": "fc34d28e-38f5-49d2-92f6-82acb79098f4", "created_at": "2023-07-21T14:10:00.00Z", "updated_at": "2023-07-21T15:10:00.00Z", "user_id": "4b9732bd-7496-4913-8a5f-6360479d7fed", "account_id": "00ef0be8-d564-43af-b3c7-11b7a2188030", "name": "Portfolio savings plan", "type": "PORTFOLIO", "cash_amount": "100.00", "currency": "EUR", "start_date": "2023-07-24", "period": "WEEK", "interval": 1, "status": "ACTIVE", "cancellation_reason": "CANCELLED_BY_CLIENT", "cancellation_details": "User requested cancellation" } } } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "405": { "description": "Method Not Allowed. The requested method is not allowed on the requested resource.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 405, "type": "method_not_allowed" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "delete": { "operationId": "delete_savings_plan", "summary": "Delete a savings plan", "description": "Delete a savings plan specified by its ID.", "tags": [ "Savings Plans" ], "security": [ { "oauth-client-credentials": [ "savings_plans:admin" ] } ], "responses": { "202": { "description": "The request has been successfully accepted and will be processed asynchronously.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "409": { "description": "Conflict. An operation is not available for the current state of the resource.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 409, "type": "conflict" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/savings_plans": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_savings_plans", "summary": "List savings plans", "description": "Returns a paginated list of savings plans for the authenticated client.\n\nSavings plans can be of type `INSTRUMENT` (recurring buy of a single instrument) or `PORTFOLIO` (recurring investment distributed across the account's portfolio allocation).", "tags": [ "Savings Plans" ], "security": [ { "oauth-client-credentials": [ "savings_plans:read", "savings_plans:admin" ] } ], "parameters": [ { "name": "account_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filters savings plans by account ID", "example": "3ada8e9e-82c4-4c78-a43d-a691b1636509" }, { "name": "user_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filters savings plans by user ID", "example": "996e5e2c-bb76-4a38-8d5c-ff43d86904da" }, { "name": "instrument_id", "in": "query", "required": false, "schema": { "title": "Instrument unique identifier", "description": "Instrument unique identifier.", "oneOf": [ { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, { "title": "German securities identification code", "type": "string", "description": "German securities identification code known as [Wertpapierkennnummer](https://en.wikipedia.org/wiki/Wertpapierkennnummer).", "pattern": "^[A-HJ-NP-Z0-9]{6}$" } ] }, "description": "Filters savings plans by instrument ID (ISIN)", "example": "FR0010524777" }, { "name": "sort", "in": "query", "required": false, "description": "Sort the result by `id`.", "schema": { "type": "string", "enum": [ "id" ], "default": "id" } }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. By default, only ASC for ascending sort." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Savings plan - List - Response", "type": "object", "description": "Paginated list of savings plans, including cursor-based pagination metadata.", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "items": { "title": "Savings plan (instrument)", "type": "object", "description": "Represents an `INSTRUMENT`-type savings plan — a recurring investment that automatically buys a fixed cash amount of a specified instrument on a defined schedule.", "properties": { "id": { "title": "Savings plan unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a savings plan.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "name": { "type": "string", "description": "Savings plan name" }, "type": { "type": "string", "description": "Type of the Savings plan.\n* PORTFOLIO - \n* INSTRUMENT - ", "enum": [ "PORTFOLIO", "INSTRUMENT" ] }, "instrument_id": { "title": "Instrument unique identifier", "description": "Instrument unique identifier.", "oneOf": [ { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, { "title": "German securities identification code", "type": "string", "description": "German securities identification code known as [Wertpapierkennnummer](https://en.wikipedia.org/wiki/Wertpapierkennnummer).", "pattern": "^[A-HJ-NP-Z0-9]{6}$" } ] }, "instrument_id_type": { "type": "string", "description": "The type of the ID used in the request.\n* ISIN - International Securities Identification Number\n* WKN - German securities identification code", "enum": [ "ISIN", "WKN" ], "default": "ISIN" }, "cash_amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "start_date": { "type": "string", "description": "First date of the savings plan execution in YYYY-MM-DD format.", "pattern": "^[12]\\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "period": { "type": "string", "description": "Unit of time. \n* WEEK - \n* MONTH - \n* YEAR - ", "enum": [ "WEEK", "MONTH", "YEAR" ] }, "interval": { "description": "Number of periods between executions", "type": "integer", "default": 1, "minimum": 1, "maximum": 1000 }, "status": { "type": "string", "description": "Status of a Savings Plan. \n* ACTIVE - \n* CANCELLED - ", "enum": [ "ACTIVE", "CANCELLED" ] }, "fee_configuration": { "title": "Savings plan fee configuration, only for instrument", "type": "array", "description": "Fee configuration for instrument-type savings plan executions. Specifies the transaction fee model to apply to each buy order placed on execution.", "items": { "type": "object", "properties": { "type": { "title": "Fee type", "description": "Fee type\n* TRANSACTION_FEE_BUY -", "type": "string", "enum": [ "TRANSACTION_FEE_BUY" ] }, "transaction_fee_model_id": { "title": "Fee model unique identifier.", "type": "string", "description": "Universally Unique Identifier (UUID) of the transaction fee model.", "format": "uuid" } }, "required": [ "type", "transaction_fee_model_id" ], "additionalProperties": false } }, "cancellation_reason": { "title": "Cancellation reason code for savings plan", "description": "Explains the reason why the savings plan was cancelled .\n* CANCELLED_BY_CLIENT: The savings plan was cancelled by the client.\n* CANCELLED_BY_UPVEST: The savings plan was cancelled by Upvest.", "type": "string", "enum": [ "CANCELLED_BY_CLIENT", "CANCELLED_BY_UPVEST" ] }, "cancellation_details": { "description": "Additional details about the cancellation", "type": "string" } }, "required": [ "id", "user_id", "account_id", "type", "cash_amount", "currency", "start_date", "period", "interval", "created_at", "updated_at" ], "additionalProperties": false } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "examples": { "instrument": { "summary": "instrument", "value": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1, "sort": "id", "order": "ASC" }, "data": [ { "id": "fc34d28e-38f5-49d2-92f6-82acb79098f4", "created_at": "2023-07-21T14:10:00.00Z", "updated_at": "2023-07-21T15:10:00.00Z", "user_id": "4b9732bd-7496-4913-8a5f-6360479d7fed", "account_id": "00ef0be8-d564-43af-b3c7-11b7a2188030", "name": "Instrument savings plan", "type": "INSTRUMENT", "instrument_id": "DE0007664005", "instrument_id_type": "ISIN", "cash_amount": "100.00", "currency": "EUR", "start_date": "2023-07-24", "period": "WEEK", "interval": 1, "status": "ACTIVE", "fee_configuration": [ { "type": "TRANSACTION_FEE_BUY", "transaction_fee_model_id": "3ae9403c-1611-46eb-84ee-e06a02bcfd08" } ], "cancellation_reason": "CANCELLED_BY_CLIENT", "cancellation_details": "User requested cancellation" } ] } }, "portfolio": { "summary": "portfolio", "value": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1, "sort": "id", "order": "ASC" }, "data": [ { "id": "fc34d28e-38f5-49d2-92f6-82acb79098f4", "created_at": "2023-07-21T14:10:00.00Z", "updated_at": "2023-07-21T15:10:00.00Z", "user_id": "4b9732bd-7496-4913-8a5f-6360479d7fed", "account_id": "00ef0be8-d564-43af-b3c7-11b7a2188030", "name": "Portfolio savings plan", "type": "PORTFOLIO", "cash_amount": "100.00", "currency": "EUR", "start_date": "2023-07-24", "period": "WEEK", "interval": 1, "status": "ACTIVE", "cancellation_reason": "CANCELLED_BY_CLIENT", "cancellation_details": "User requested cancellation" } ] } } } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "405": { "description": "Method Not Allowed. The requested method is not allowed on the requested resource.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 405, "type": "method_not_allowed" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "post": { "operationId": "create_savings_plan", "summary": "Create savings plan", "description": "Creates a recurring savings plan that automatically invests a fixed cash amount at a defined frequency.\n\nSet `type` to `INSTRUMENT` to invest in a single instrument, or `PORTFOLIO` to distribute the investment across the account's portfolio allocation.", "tags": [ "Savings Plans" ], "security": [ { "oauth-client-credentials": [ "savings_plans:admin" ] } ], "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$", "example": "ccb07f42-4104-44ad-8e1f-c660bb7b269c" }, "description": "A UUID to be used as an idempotency key. This prevents a duplicate request from being replayed.\nhttps://docs.upvest.co/documentation/concepts/api_concepts/idempotency\n" } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Savings plan - Create - Request", "anyOf": [ { "title": "Savings plan (portfolio)", "type": "object", "description": "Request body for creating a `PORTFOLIO`-type savings plan. Specifies the account, cash amount, currency, and schedule. The account's portfolio configuration determines the allocation.", "properties": { "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "name": { "type": "string", "description": "Savings plan name" }, "type": { "type": "string", "default": "PORTFOLIO", "description": "The type of savings plan must be \"PORTFOLIO\"." }, "cash_amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "start_date": { "type": "string", "description": "First date of the savings plan execution in YYYY-MM-DD format.", "pattern": "^[12]\\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "period": { "type": "string", "description": "Unit of time. \n* WEEK - \n* MONTH - \n* YEAR - ", "enum": [ "WEEK", "MONTH", "YEAR" ] }, "interval": { "description": "Number of periods between executions", "type": "integer", "default": 1, "minimum": 1, "maximum": 1000 } }, "required": [ "user_id", "account_id", "type", "cash_amount", "currency", "start_date", "period", "interval" ], "additionalProperties": false }, { "title": "Savings plan (instrument)", "type": "object", "description": "Request body for creating an `INSTRUMENT`-type savings plan. Specifies the account, instrument, cash amount, currency, schedule, and optional fee configuration.", "properties": { "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "name": { "type": "string", "description": "Savings plan name" }, "type": { "type": "string", "default": "INSTRUMENT", "description": "The type of savings plan must be \"INSTRUMENT\"." }, "instrument_id": { "title": "Instrument unique identifier", "description": "Instrument unique identifier.", "oneOf": [ { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, { "title": "German securities identification code", "type": "string", "description": "German securities identification code known as [Wertpapierkennnummer](https://en.wikipedia.org/wiki/Wertpapierkennnummer).", "pattern": "^[A-HJ-NP-Z0-9]{6}$" } ] }, "instrument_id_type": { "type": "string", "description": "The type of the ID used in the request.\n* ISIN - International Securities Identification Number\n* WKN - German securities identification code", "enum": [ "ISIN", "WKN" ], "default": "ISIN" }, "cash_amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "start_date": { "type": "string", "description": "First date of the savings plan execution in YYYY-MM-DD format.", "pattern": "^[12]\\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "period": { "type": "string", "description": "Unit of time. \n* WEEK - \n* MONTH - \n* YEAR - ", "enum": [ "WEEK", "MONTH", "YEAR" ] }, "interval": { "description": "Number of periods between executions", "type": "integer", "default": 1, "minimum": 1, "maximum": 1000 }, "fee_configuration": { "title": "Savings plan fee configuration, only for instrument", "type": "array", "description": "Fee configuration for instrument-type savings plan executions. Specifies the transaction fee model to apply to each buy order placed on execution.", "items": { "type": "object", "properties": { "type": { "title": "Fee type", "description": "Fee type\n* TRANSACTION_FEE_BUY -", "type": "string", "enum": [ "TRANSACTION_FEE_BUY" ] }, "transaction_fee_model_id": { "title": "Fee model unique identifier.", "type": "string", "description": "Universally Unique Identifier (UUID) of the transaction fee model.", "format": "uuid" } }, "required": [ "type", "transaction_fee_model_id" ], "additionalProperties": false } } }, "required": [ "user_id", "account_id", "type", "cash_amount", "currency", "start_date", "period", "interval" ], "additionalProperties": false } ] }, "examples": { "instrument": { "summary": "instrument", "value": { "user_id": "fc34d28e-38f5-49d2-92f6-82acb79098f4", "account_id": "00ef0be8-d564-43af-b3c7-11b7a2188030", "name": "Instrument savings plan", "type": "INSTRUMENT", "instrument_id": "DE0007664005", "instrument_id_type": "ISIN", "cash_amount": "100.00", "currency": "EUR", "start_date": "2023-07-24", "period": "WEEK", "interval": 2, "fee_configuration": [ { "type": "TRANSACTION_FEE_BUY", "transaction_fee_model_id": "3ae9403c-1611-46eb-84ee-e06a02bcfd08" } ] } }, "portfolio": { "summary": "portfolio", "value": { "user_id": "fc34d28e-38f5-49d2-92f6-82acb79098f4", "account_id": "00ef0be8-d564-43af-b3c7-11b7a2188030", "name": "Portfolio savings plan", "type": "PORTFOLIO", "cash_amount": "100.00", "currency": "EUR", "start_date": "2023-07-24", "period": "WEEK", "interval": 1 } } } } } }, "responses": { "202": { "description": "Savings plan object", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Savings plan (instrument)", "type": "object", "description": "Represents an `INSTRUMENT`-type savings plan — a recurring investment that automatically buys a fixed cash amount of a specified instrument on a defined schedule.", "properties": { "id": { "title": "Savings plan unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a savings plan.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "name": { "type": "string", "description": "Savings plan name" }, "type": { "type": "string", "description": "Type of the Savings plan.\n* PORTFOLIO - \n* INSTRUMENT - ", "enum": [ "PORTFOLIO", "INSTRUMENT" ] }, "instrument_id": { "title": "Instrument unique identifier", "description": "Instrument unique identifier.", "oneOf": [ { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, { "title": "German securities identification code", "type": "string", "description": "German securities identification code known as [Wertpapierkennnummer](https://en.wikipedia.org/wiki/Wertpapierkennnummer).", "pattern": "^[A-HJ-NP-Z0-9]{6}$" } ] }, "instrument_id_type": { "type": "string", "description": "The type of the ID used in the request.\n* ISIN - International Securities Identification Number\n* WKN - German securities identification code", "enum": [ "ISIN", "WKN" ], "default": "ISIN" }, "cash_amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "start_date": { "type": "string", "description": "First date of the savings plan execution in YYYY-MM-DD format.", "pattern": "^[12]\\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "period": { "type": "string", "description": "Unit of time. \n* WEEK - \n* MONTH - \n* YEAR - ", "enum": [ "WEEK", "MONTH", "YEAR" ] }, "interval": { "description": "Number of periods between executions", "type": "integer", "default": 1, "minimum": 1, "maximum": 1000 }, "status": { "type": "string", "description": "Status of a Savings Plan. \n* ACTIVE - \n* CANCELLED - ", "enum": [ "ACTIVE", "CANCELLED" ] }, "fee_configuration": { "title": "Savings plan fee configuration, only for instrument", "type": "array", "description": "Fee configuration for instrument-type savings plan executions. Specifies the transaction fee model to apply to each buy order placed on execution.", "items": { "type": "object", "properties": { "type": { "title": "Fee type", "description": "Fee type\n* TRANSACTION_FEE_BUY -", "type": "string", "enum": [ "TRANSACTION_FEE_BUY" ] }, "transaction_fee_model_id": { "title": "Fee model unique identifier.", "type": "string", "description": "Universally Unique Identifier (UUID) of the transaction fee model.", "format": "uuid" } }, "required": [ "type", "transaction_fee_model_id" ], "additionalProperties": false } }, "cancellation_reason": { "title": "Cancellation reason code for savings plan", "description": "Explains the reason why the savings plan was cancelled .\n* CANCELLED_BY_CLIENT: The savings plan was cancelled by the client.\n* CANCELLED_BY_UPVEST: The savings plan was cancelled by Upvest.", "type": "string", "enum": [ "CANCELLED_BY_CLIENT", "CANCELLED_BY_UPVEST" ] }, "cancellation_details": { "description": "Additional details about the cancellation", "type": "string" } }, "required": [ "id", "user_id", "account_id", "type", "cash_amount", "currency", "start_date", "period", "interval", "created_at", "updated_at" ], "additionalProperties": false }, "examples": { "instrument": { "summary": "instrument", "value": { "id": "fc34d28e-38f5-49d2-92f6-82acb79098f4", "created_at": "2023-07-21T14:10:00.00Z", "updated_at": "2023-07-21T15:10:00.00Z", "user_id": "4b9732bd-7496-4913-8a5f-6360479d7fed", "account_id": "00ef0be8-d564-43af-b3c7-11b7a2188030", "name": "Instrument savings plan", "type": "INSTRUMENT", "instrument_id": "DE0007664005", "instrument_id_type": "ISIN", "cash_amount": "100.00", "currency": "EUR", "start_date": "2023-07-24", "period": "WEEK", "interval": 1, "status": "ACTIVE", "fee_configuration": [ { "type": "TRANSACTION_FEE_BUY", "transaction_fee_model_id": "3ae9403c-1611-46eb-84ee-e06a02bcfd08" } ], "cancellation_reason": "CANCELLED_BY_CLIENT", "cancellation_details": "User requested cancellation" } }, "portfolio": { "summary": "portfolio", "value": { "id": "fc34d28e-38f5-49d2-92f6-82acb79098f4", "created_at": "2023-07-21T14:10:00.00Z", "updated_at": "2023-07-21T15:10:00.00Z", "user_id": "4b9732bd-7496-4913-8a5f-6360479d7fed", "account_id": "00ef0be8-d564-43af-b3c7-11b7a2188030", "name": "Portfolio savings plan", "type": "PORTFOLIO", "cash_amount": "100.00", "currency": "EUR", "start_date": "2023-07-24", "period": "WEEK", "interval": 1, "status": "ACTIVE", "cancellation_reason": "CANCELLED_BY_CLIENT", "cancellation_details": "User requested cancellation" } } } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "405": { "description": "Method Not Allowed. The requested method is not allowed on the requested resource.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 405, "type": "method_not_allowed" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/savings_plans/{savings_plan_id}/executions/{savings_plan_execution_id}": { "parameters": [ { "name": "savings_plan_id", "in": "path", "required": true, "description": "The unique identifier of the savings plan. Universally Unique Identifier (UUID).", "schema": { "title": "Savings plan unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a savings plan.", "format": "uuid" } }, { "name": "savings_plan_execution_id", "in": "path", "required": true, "description": "The unique identifier of the savings plan execution. Universally Unique Identifier (UUID).", "schema": { "title": "Savings plan execution unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a savings plan execution.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_savings_plan_execution", "summary": "Retrieve savings plan execution", "description": "Retrieves a single execution of a savings plan by its ID, including the order placed and its current status.", "tags": [ "Savings Plans" ], "security": [ { "oauth-client-credentials": [ "savings_plans:read", "savings_plans:admin" ] } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Savings plan execution", "anyOf": [ { "title": "Savings plan execution (instrument)", "type": "object", "description": "Represents a single execution of an `INSTRUMENT`-type savings plan, recording the order placed, the execution date, and the resulting status.", "properties": { "id": { "title": "Savings plan execution unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a savings plan execution.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "savings_plan_id": { "title": "Savings plan unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a savings plan.", "format": "uuid" }, "order_id": { "title": "Order unique identifier (Portfolio order or Instrument order)", "description": "Order unique identifier (Portfolio order or Instrument order)", "oneOf": [ { "title": "Portfolios order unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio order.", "format": "uuid" }, { "title": "Order", "type": "object", "description": "Represents an investment order placed by an end user or on their behalf. An order transitions through states (`NEW` → `PROCESSING` → `FILLED` or `CANCELLED`) as it is routed and executed.", "properties": { "id": { "title": "Order unique identifier", "type": "string", "description": "Unique identifier for an order. Universally Unique Identifier (UUID).", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "type": "string", "format": "uuid", "description": "The ID of the user. Either user ID or business ID must be specified." }, "business_id": { "type": "string", "format": "uuid", "description": "The ID of the business. Either user ID or business ID must be specified." }, "account_id": { "type": "string", "format": "uuid", "description": "The ID of the account that owns the order" }, "cash_amount": { "allOf": [ { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, { "description": "Cash amount for a nominal order, not required if a share quantity is specified." } ] }, "currency": { "allOf": [ { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound\n* USD - US Dollar", "enum": [ "EUR", "GBP", "USD" ] }, { "description": "The currency for the order." } ] }, "side": { "type": "string", "description": "Side of the order.\n* BUY — purchases the specified instrument.\n* SELL — disposes of the specified instrument.", "enum": [ "BUY", "SELL" ] }, "instrument_id": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, "instrument_id_type": { "description": "The type of the ID used in the request.\n* ISIN - ", "enum": [ "ISIN" ], "default": "ISIN", "type": "string" }, "order_type": { "type": "string", "description": "Type of the order.\n* MARKET — executes immediately at the best available market price.\n* LIMIT — executes only at or better than the specified `limit_price`.\n* STOP — triggers when the market price reaches `stop_price`, then executes at the prevailing market price.", "enum": [ "MARKET", "LIMIT", "STOP" ] }, "quantity": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "Quantity of securities for the order. Only required if the cash amount is not specified." } ] }, "user_instrument_fit_acknowledgement": { "type": "boolean", "description": "Only applicable if the user has failed the instrument fit check for the instrument type being ordered. True if the user has acknowledged their willingness to trade." }, "limit_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The limit price for orders of the type 'limit'." } ] }, "stop_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The stop price for orders of the type 'stop'." } ] }, "expiry_date": { "allOf": [ { "title": "Expiry date", "type": "string", "description": "Order expiration date in YYYY-MM-DD format. Only applicable to `LIMIT` and `STOP` orders — the order will not execute after this date. Defaults to order creation date plus 359 days.", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, { "description": "The order expiration date (last day the order can trade) in the YYYY-MM-DD format. The expiry date can only be set for LIMIT and STOP orders. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339. The default value is order creation date + 359 days" } ] }, "status": { "type": "string", "description": "The execution status of the order.\n* NEW — the order has been received and validated, awaiting routing.\n* PROCESSING — the order is being routed for execution.\n* FILLED — the order has been fully executed.\n* CANCELLED — the order was cancelled before being fully executed.", "enum": [ "NEW", "PROCESSING", "FILLED", "CANCELLED" ] }, "fee": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "cancellation_reason": { "type": "string", "description": "Reason for order cancellation. Present only when `status` is `CANCELLED`.\n* CANCELLED_BY_CLIENT — cancelled at the end user's or client's request via the API.\n* CANCELLED_BY_UPVEST_OPERATIONS — cancelled by Upvest operations.\n* CANCELLED_BY_TRADING_PARTNER — cancelled by the executing partner.\n* CANCELLED_BY_UPVEST_PLATFORM — cancelled automatically by the Upvest platform.", "enum": [ "CANCELLED_BY_CLIENT", "CANCELLED_BY_UPVEST_OPERATIONS", "CANCELLED_BY_TRADING_PARTNER", "CANCELLED_BY_UPVEST_PLATFORM" ] }, "initiation_flow": { "type": "string", "description": "Identifies what triggered the order.\n* API — initiated directly via the client API.\n* PORTFOLIO — initiated by a portfolio rebalancing flow.\n* CASH_DIVIDEND_REINVESTMENT — initiated as part of dividend reinvestment.\n* PORTFOLIO_REBALANCING — initiated by an automated rebalancing.\n* SELL_TO_COVER_FEES — initiated automatically to cover outstanding fees.\n* SELL_TO_COVER_TAXES — initiated automatically to cover tax obligations.\n* ACCOUNT_LIQUIDATION — initiated as part of an account liquidation.\n* UPVEST_OPERATIONS — initiated by Upvest operations.\n* SAVINGS_PLAN — initiated by a savings plan execution.\n* CLIENT_OPERATIONS — initiated by client operations.", "enum": [ "API", "PORTFOLIO", "CASH_DIVIDEND_REINVESTMENT", "PORTFOLIO_REBALANCING", "SELL_TO_COVER_FEES", "SELL_TO_COVER_TAXES", "ACCOUNT_LIQUIDATION", "UPVEST_OPERATIONS", "SAVINGS_PLAN", "CLIENT_OPERATIONS" ] }, "execution_flow": { "type": "string", "description": "Execution flow for order processing. Defaults to `STRAIGHT_THROUGH` if not specified.\n* STRAIGHT_THROUGH — the order is routed and executed directly without manual intervention.\n* BLOCK — the order is bundled with other orders for block execution.", "enum": [ "STRAIGHT_THROUGH", "BLOCK" ] }, "executions": { "type": "array", "description": "Order executions associated with this order", "items": { "title": "Order execution", "type": "object", "description": "Represents a single execution (trade fill) within an order. An order may have multiple executions if it is partially filled across several trades.", "properties": { "id": { "title": "Order execution unique identifier", "type": "string", "format": "uuid" }, "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "share_quantity": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "price": { "type": "string", "description": "Price of an instrument for a trade execution provided as a decimal string.", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,4})?$" }, "transaction_time": { "type": "string", "format": "date-time", "description": "Timestamp of when the trade was executed at the market. [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) date-time format." }, "taxes": { "type": "array", "description": "Taxes deducted as part of this execution.", "items": { "title": "Tax", "type": "object", "description": "Tax deducted as part of an order execution. Contains the tax type and the deducted amount.", "properties": { "type": { "type": "string", "description": "Tax type\n* TOTAL - ", "default": "TOTAL", "enum": [ "TOTAL" ] }, "amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" } }, "required": [ "type", "amount" ] } }, "order_id": { "title": "Order unique identifier", "type": "string", "description": "Unique identifier for an order. Universally Unique Identifier (UUID).", "format": "uuid" }, "status": { "type": "string", "description": "Status of the execution.\n* FILLED — the execution has been filled.\n* SETTLED — the execution has settled and securities and cash have been exchanged.\n* CANCELLED — the execution was cancelled before settlement.", "enum": [ "FILLED", "SETTLED", "CANCELLED" ] }, "side": { "type": "string", "description": "Side of the execution.\n* BUY — a buy execution.\n* SELL — a sell execution.", "enum": [ "BUY", "SELL" ] }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound\n* USD - US Dollar", "enum": [ "EUR", "GBP", "USD" ] }, "settlement_date": { "allOf": [ { "title": "Settlement date", "type": "string", "description": "Trade settlement date in YYYY-MM-DD format. The date on which securities and cash are exchanged following execution.", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, { "description": "Order execution settlement date in the YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339" } ] }, "venue_id": { "type": "string", "format": "uuid", "description": "The ID of the venue" } }, "required": [ "id", "cash_amount", "share_quantity", "price", "transaction_time", "taxes", "order_id", "status", "side", "currency", "venue_id" ], "additionalProperties": false } }, "client_reference": { "type": "string", "description": "Immutable reference to the API flow that initiated the order. For client initiated API flows, this is a client provided ID. For internal initiations, it is set to the ID of the related object.", "maxLength": 100 }, "fee_configuration": { "type": "array", "description": "Fee configuration applied to this order. Determines how the order fee is calculated.", "items": { "title": "Fee", "description": "A fee applied to an order. Either a fixed absolute cash fee (`absolute_fee_configuration_item`) or a reference to a predefined transaction fee model.", "oneOf": [ { "title": "Absolute Fee", "type": "object", "description": "A fixed cash fee applied to an order, specified as an absolute amount in a given currency.", "properties": { "type": { "title": "Fee type", "description": "Fee type\n* TRANSACTION_FEE_BUY - \n* TRANSACTION_FEE_SELL - ", "type": "string", "enum": [ "TRANSACTION_FEE_BUY", "TRANSACTION_FEE_SELL" ] }, "value_type": { "type": "string", "default": "ABSOLUTE", "description": "The value type must be “ABSOLUTE”." }, "charge_method": { "title": "Fee charge method", "type": "string", "description": "Indicates whether the fee will be charged by client or by other methods.\n* CHARGED_BY_CLIENT - \n* COLLECTED_BY_UPVEST - ", "enum": [ "CHARGED_BY_CLIENT", "COLLECTED_BY_UPVEST" ] }, "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound\n* USD - US Dollar", "enum": [ "EUR", "GBP", "USD" ] } }, "required": [ "type", "value_type", "charge_method", "cash_amount", "currency" ], "additionalProperties": false }, { "title": "Transaction Fee Model", "type": "object", "description": "A fee configuration that references a predefined transaction fee model by its ID, rather than specifying a fee amount directly.", "properties": { "type": { "title": "Fee type", "description": "Fee type\n* TRANSACTION_FEE_BUY - \n* TRANSACTION_FEE_SELL - ", "type": "string", "enum": [ "TRANSACTION_FEE_BUY", "TRANSACTION_FEE_SELL" ] }, "transaction_fee_model_id": { "type": "string", "format": "uuid", "description": "The ID of the transaction fee model." } }, "required": [ "type", "transaction_fee_model_id" ], "additionalProperties": false } ] } }, "decision_maker_id": { "type": "string", "description": "ID of the user behind the decision to place an order. Required only if different from the user_id. (e.g. child account order placed by a guardian)" } }, "required": [ "id", "created_at", "updated_at", "account_id", "cash_amount", "currency", "side", "instrument_id", "instrument_id_type", "order_type", "quantity", "status", "fee", "initiation_flow", "executions" ], "additionalProperties": false }, { "type": "null" } ] }, "cash_amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "status": { "type": "string", "description": "Status of a Savings Plan Execution. \n* NEW - \n* PROCESSING - \n* FILLED - \n* SETTLED - \n* CANCELLED - ", "enum": [ "NEW", "PROCESSING", "FILLED", "SETTLED", "CANCELLED" ] }, "type": { "type": "string", "default": "INSTRUMENT", "description": "The type of savings plan must be \"INSTRUMENT\"." }, "execution_date": { "type": "string", "description": "Date of a savings plan execution in YYYY-MM-DD format.", "pattern": "^[12]\\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "instrument_id": { "title": "Instrument unique identifier", "description": "Instrument unique identifier.", "oneOf": [ { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, { "title": "German securities identification code", "type": "string", "description": "German securities identification code known as [Wertpapierkennnummer](https://en.wikipedia.org/wiki/Wertpapierkennnummer).", "pattern": "^[A-HJ-NP-Z0-9]{6}$" } ] }, "instrument_id_type": { "type": "string", "description": "The type of the ID used in the request.\n* ISIN - International Securities Identification Number\n* WKN - German securities identification code", "enum": [ "ISIN", "WKN" ], "default": "ISIN" }, "fee_configuration": { "title": "Savings plan fee configuration, only for instrument", "type": "array", "description": "Fee configuration for instrument-type savings plan executions. Specifies the transaction fee model to apply to each buy order placed on execution.", "items": { "type": "object", "properties": { "type": { "title": "Fee type", "description": "Fee type\n* TRANSACTION_FEE_BUY -", "type": "string", "enum": [ "TRANSACTION_FEE_BUY" ] }, "transaction_fee_model_id": { "title": "Fee model unique identifier.", "type": "string", "description": "Universally Unique Identifier (UUID) of the transaction fee model.", "format": "uuid" } }, "required": [ "type", "transaction_fee_model_id" ], "additionalProperties": false } }, "cancellation_reason": { "title": "Cancellation reason code for savings plan execution", "description": "Explains the reason why the savings plan execution was cancelled .\n* CANCELLED_BY_CLIENT: The savings plan execution was cancelled by the client.\n* CANCELLED_BY_UPVEST: The savings plan execution was cancelled by Upvest.", "type": "string", "enum": [ "CANCELLED_BY_CLIENT", "CANCELLED_BY_UPVEST" ] }, "cancellation_details": { "title": "Cancellation details for savings plan execution", "description": "Human-readable description providing additional context about why the savings plan execution was cancelled.", "type": "string" } }, "required": [ "id", "user_id", "account_id", "savings_plan_id", "order_id", "cash_amount", "currency", "status", "type", "execution_date", "created_at", "updated_at" ], "additionalProperties": false }, { "title": "Savings plan execution (portfolio)", "type": "object", "description": "Represents a single execution of a `PORTFOLIO`-type savings plan, recording the portfolio order placed, the execution date, and the resulting status.", "properties": { "id": { "title": "Savings plan execution unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a savings plan execution.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "savings_plan_id": { "title": "Savings plan unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a savings plan.", "format": "uuid" }, "order_id": { "title": "Order unique identifier (Portfolio order or Instrument order)", "description": "Order unique identifier (Portfolio order or Instrument order)", "oneOf": [ { "title": "Portfolios order unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio order.", "format": "uuid" }, { "title": "Order", "type": "object", "description": "Represents an investment order placed by an end user or on their behalf. An order transitions through states (`NEW` → `PROCESSING` → `FILLED` or `CANCELLED`) as it is routed and executed.", "properties": { "id": { "title": "Order unique identifier", "type": "string", "description": "Unique identifier for an order. Universally Unique Identifier (UUID).", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "type": "string", "format": "uuid", "description": "The ID of the user. Either user ID or business ID must be specified." }, "business_id": { "type": "string", "format": "uuid", "description": "The ID of the business. Either user ID or business ID must be specified." }, "account_id": { "type": "string", "format": "uuid", "description": "The ID of the account that owns the order" }, "cash_amount": { "allOf": [ { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, { "description": "Cash amount for a nominal order, not required if a share quantity is specified." } ] }, "currency": { "allOf": [ { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound\n* USD - US Dollar", "enum": [ "EUR", "GBP", "USD" ] }, { "description": "The currency for the order." } ] }, "side": { "type": "string", "description": "Side of the order.\n* BUY — purchases the specified instrument.\n* SELL — disposes of the specified instrument.", "enum": [ "BUY", "SELL" ] }, "instrument_id": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, "instrument_id_type": { "description": "The type of the ID used in the request.\n* ISIN - ", "enum": [ "ISIN" ], "default": "ISIN", "type": "string" }, "order_type": { "type": "string", "description": "Type of the order.\n* MARKET — executes immediately at the best available market price.\n* LIMIT — executes only at or better than the specified `limit_price`.\n* STOP — triggers when the market price reaches `stop_price`, then executes at the prevailing market price.", "enum": [ "MARKET", "LIMIT", "STOP" ] }, "quantity": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "Quantity of securities for the order. Only required if the cash amount is not specified." } ] }, "user_instrument_fit_acknowledgement": { "type": "boolean", "description": "Only applicable if the user has failed the instrument fit check for the instrument type being ordered. True if the user has acknowledged their willingness to trade." }, "limit_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The limit price for orders of the type 'limit'." } ] }, "stop_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The stop price for orders of the type 'stop'." } ] }, "expiry_date": { "allOf": [ { "title": "Expiry date", "type": "string", "description": "Order expiration date in YYYY-MM-DD format. Only applicable to `LIMIT` and `STOP` orders — the order will not execute after this date. Defaults to order creation date plus 359 days.", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, { "description": "The order expiration date (last day the order can trade) in the YYYY-MM-DD format. The expiry date can only be set for LIMIT and STOP orders. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339. The default value is order creation date + 359 days" } ] }, "status": { "type": "string", "description": "The execution status of the order.\n* NEW — the order has been received and validated, awaiting routing.\n* PROCESSING — the order is being routed for execution.\n* FILLED — the order has been fully executed.\n* CANCELLED — the order was cancelled before being fully executed.", "enum": [ "NEW", "PROCESSING", "FILLED", "CANCELLED" ] }, "fee": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "cancellation_reason": { "type": "string", "description": "Reason for order cancellation. Present only when `status` is `CANCELLED`.\n* CANCELLED_BY_CLIENT — cancelled at the end user's or client's request via the API.\n* CANCELLED_BY_UPVEST_OPERATIONS — cancelled by Upvest operations.\n* CANCELLED_BY_TRADING_PARTNER — cancelled by the executing partner.\n* CANCELLED_BY_UPVEST_PLATFORM — cancelled automatically by the Upvest platform.", "enum": [ "CANCELLED_BY_CLIENT", "CANCELLED_BY_UPVEST_OPERATIONS", "CANCELLED_BY_TRADING_PARTNER", "CANCELLED_BY_UPVEST_PLATFORM" ] }, "initiation_flow": { "type": "string", "description": "Identifies what triggered the order.\n* API — initiated directly via the client API.\n* PORTFOLIO — initiated by a portfolio rebalancing flow.\n* CASH_DIVIDEND_REINVESTMENT — initiated as part of dividend reinvestment.\n* PORTFOLIO_REBALANCING — initiated by an automated rebalancing.\n* SELL_TO_COVER_FEES — initiated automatically to cover outstanding fees.\n* SELL_TO_COVER_TAXES — initiated automatically to cover tax obligations.\n* ACCOUNT_LIQUIDATION — initiated as part of an account liquidation.\n* UPVEST_OPERATIONS — initiated by Upvest operations.\n* SAVINGS_PLAN — initiated by a savings plan execution.\n* CLIENT_OPERATIONS — initiated by client operations.", "enum": [ "API", "PORTFOLIO", "CASH_DIVIDEND_REINVESTMENT", "PORTFOLIO_REBALANCING", "SELL_TO_COVER_FEES", "SELL_TO_COVER_TAXES", "ACCOUNT_LIQUIDATION", "UPVEST_OPERATIONS", "SAVINGS_PLAN", "CLIENT_OPERATIONS" ] }, "execution_flow": { "type": "string", "description": "Execution flow for order processing. Defaults to `STRAIGHT_THROUGH` if not specified.\n* STRAIGHT_THROUGH — the order is routed and executed directly without manual intervention.\n* BLOCK — the order is bundled with other orders for block execution.", "enum": [ "STRAIGHT_THROUGH", "BLOCK" ] }, "executions": { "type": "array", "description": "Order executions associated with this order", "items": { "title": "Order execution", "type": "object", "description": "Represents a single execution (trade fill) within an order. An order may have multiple executions if it is partially filled across several trades.", "properties": { "id": { "title": "Order execution unique identifier", "type": "string", "format": "uuid" }, "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "share_quantity": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "price": { "type": "string", "description": "Price of an instrument for a trade execution provided as a decimal string.", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,4})?$" }, "transaction_time": { "type": "string", "format": "date-time", "description": "Timestamp of when the trade was executed at the market. [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) date-time format." }, "taxes": { "type": "array", "description": "Taxes deducted as part of this execution.", "items": { "title": "Tax", "type": "object", "description": "Tax deducted as part of an order execution. Contains the tax type and the deducted amount.", "properties": { "type": { "type": "string", "description": "Tax type\n* TOTAL - ", "default": "TOTAL", "enum": [ "TOTAL" ] }, "amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" } }, "required": [ "type", "amount" ] } }, "order_id": { "title": "Order unique identifier", "type": "string", "description": "Unique identifier for an order. Universally Unique Identifier (UUID).", "format": "uuid" }, "status": { "type": "string", "description": "Status of the execution.\n* FILLED — the execution has been filled.\n* SETTLED — the execution has settled and securities and cash have been exchanged.\n* CANCELLED — the execution was cancelled before settlement.", "enum": [ "FILLED", "SETTLED", "CANCELLED" ] }, "side": { "type": "string", "description": "Side of the execution.\n* BUY — a buy execution.\n* SELL — a sell execution.", "enum": [ "BUY", "SELL" ] }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound\n* USD - US Dollar", "enum": [ "EUR", "GBP", "USD" ] }, "settlement_date": { "allOf": [ { "title": "Settlement date", "type": "string", "description": "Trade settlement date in YYYY-MM-DD format. The date on which securities and cash are exchanged following execution.", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, { "description": "Order execution settlement date in the YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339" } ] }, "venue_id": { "type": "string", "format": "uuid", "description": "The ID of the venue" } }, "required": [ "id", "cash_amount", "share_quantity", "price", "transaction_time", "taxes", "order_id", "status", "side", "currency", "venue_id" ], "additionalProperties": false } }, "client_reference": { "type": "string", "description": "Immutable reference to the API flow that initiated the order. For client initiated API flows, this is a client provided ID. For internal initiations, it is set to the ID of the related object.", "maxLength": 100 }, "fee_configuration": { "type": "array", "description": "Fee configuration applied to this order. Determines how the order fee is calculated.", "items": { "title": "Fee", "description": "A fee applied to an order. Either a fixed absolute cash fee (`absolute_fee_configuration_item`) or a reference to a predefined transaction fee model.", "oneOf": [ { "title": "Absolute Fee", "type": "object", "description": "A fixed cash fee applied to an order, specified as an absolute amount in a given currency.", "properties": { "type": { "title": "Fee type", "description": "Fee type\n* TRANSACTION_FEE_BUY - \n* TRANSACTION_FEE_SELL - ", "type": "string", "enum": [ "TRANSACTION_FEE_BUY", "TRANSACTION_FEE_SELL" ] }, "value_type": { "type": "string", "default": "ABSOLUTE", "description": "The value type must be “ABSOLUTE”." }, "charge_method": { "title": "Fee charge method", "type": "string", "description": "Indicates whether the fee will be charged by client or by other methods.\n* CHARGED_BY_CLIENT - \n* COLLECTED_BY_UPVEST - ", "enum": [ "CHARGED_BY_CLIENT", "COLLECTED_BY_UPVEST" ] }, "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound\n* USD - US Dollar", "enum": [ "EUR", "GBP", "USD" ] } }, "required": [ "type", "value_type", "charge_method", "cash_amount", "currency" ], "additionalProperties": false }, { "title": "Transaction Fee Model", "type": "object", "description": "A fee configuration that references a predefined transaction fee model by its ID, rather than specifying a fee amount directly.", "properties": { "type": { "title": "Fee type", "description": "Fee type\n* TRANSACTION_FEE_BUY - \n* TRANSACTION_FEE_SELL - ", "type": "string", "enum": [ "TRANSACTION_FEE_BUY", "TRANSACTION_FEE_SELL" ] }, "transaction_fee_model_id": { "type": "string", "format": "uuid", "description": "The ID of the transaction fee model." } }, "required": [ "type", "transaction_fee_model_id" ], "additionalProperties": false } ] } }, "decision_maker_id": { "type": "string", "description": "ID of the user behind the decision to place an order. Required only if different from the user_id. (e.g. child account order placed by a guardian)" } }, "required": [ "id", "created_at", "updated_at", "account_id", "cash_amount", "currency", "side", "instrument_id", "instrument_id_type", "order_type", "quantity", "status", "fee", "initiation_flow", "executions" ], "additionalProperties": false }, { "type": "null" } ] }, "cash_amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "status": { "type": "string", "description": "Status of a Savings Plan Execution. \n* NEW - \n* PROCESSING - \n* FILLED - \n* SETTLED - \n* CANCELLED - ", "enum": [ "NEW", "PROCESSING", "FILLED", "SETTLED", "CANCELLED" ] }, "type": { "type": "string", "default": "PORTFOLIO", "description": "The type of savings plan must be \"PORTFOLIO\"." }, "execution_date": { "type": "string", "description": "Date of a savings plan execution in YYYY-MM-DD format.", "pattern": "^[12]\\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "instrument_id": { "title": "Instrument unique identifier", "description": "Instrument unique identifier.", "oneOf": [ { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, { "title": "German securities identification code", "type": "string", "description": "German securities identification code known as [Wertpapierkennnummer](https://en.wikipedia.org/wiki/Wertpapierkennnummer).", "pattern": "^[A-HJ-NP-Z0-9]{6}$" } ] }, "instrument_id_type": { "type": "string", "description": "The type of the ID used in the request.\n* ISIN - International Securities Identification Number\n* WKN - German securities identification code", "enum": [ "ISIN", "WKN" ], "default": "ISIN" }, "cancellation_reason": { "title": "Cancellation reason code for savings plan execution", "description": "Explains the reason why the savings plan execution was cancelled .\n* CANCELLED_BY_CLIENT: The savings plan execution was cancelled by the client.\n* CANCELLED_BY_UPVEST: The savings plan execution was cancelled by Upvest.", "type": "string", "enum": [ "CANCELLED_BY_CLIENT", "CANCELLED_BY_UPVEST" ] }, "cancellation_details": { "title": "Cancellation details for savings plan execution", "description": "Human-readable description providing additional context about why the savings plan execution was cancelled.", "type": "string" } }, "required": [ "id", "user_id", "account_id", "savings_plan_id", "order_id", "cash_amount", "currency", "status", "type", "execution_date", "created_at", "updated_at" ], "additionalProperties": false } ] }, "examples": { "instrument": { "summary": "instrument", "value": { "id": "fc34d28e-38f5-49d2-92f6-82acb79098f4", "created_at": "2023-07-21T14:10:00.00Z", "updated_at": "2023-07-21T15:10:00.00Z", "user_id": "4b9732bd-7496-4913-8a5f-6360479d7fed", "account_id": "00ef0be8-d564-43af-b3c7-11b7a2188030", "savings_plan_id": "c31083c1-1cd3-405f-95d1-f49a37f0e032", "order_id": "68068440-6b8e-4700-8cfc-95bf21b34b96", "cash_amount": "100", "currency": "EUR", "status": "FILLED", "type": "INSTRUMENT", "instrument_id": "IE00BYTRRD19", "instrument_id_type": "ISIN", "execution_date": "2023-07-24" } }, "portfolio": { "summary": "portfolio", "value": { "id": "fc34d28e-38f5-49d2-92f6-82acb79098f4", "created_at": "2023-07-21T14:10:00.00Z", "updated_at": "2023-07-21T15:10:00.00Z", "user_id": "4b9732bd-7496-4913-8a5f-6360479d7fed", "account_id": "00ef0be8-d564-43af-b3c7-11b7a2188030", "savings_plan_id": "c31083c1-1cd3-405f-95d1-f49a37f0e032", "order_id": "68068440-6b8e-4700-8cfc-95bf21b34b96", "cash_amount": "100", "currency": "EUR", "status": "FILLED", "type": "PORTFOLIO", "execution_date": "2023-07-24" } } } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "405": { "description": "Method Not Allowed. The requested method is not allowed on the requested resource.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 405, "type": "method_not_allowed" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "delete": { "operationId": "delete_savings_plan_execution", "summary": "Delete savings plan execution", "description": "Deletes a scheduled savings plan execution before it has been processed. Only executions in the `NEW` status can be deleted.", "tags": [ "Savings Plans" ], "security": [ { "oauth-client-credentials": [ "savings_plans:admin" ] } ], "responses": { "202": { "description": "The request has been successfully accepted and will be processed asynchronously.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "409": { "description": "Conflict. An operation is not available for the current state of the resource.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 409, "type": "conflict" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/savings_plans/{savings_plan_id}/executions": { "parameters": [ { "name": "savings_plan_id", "in": "path", "required": true, "description": "The unique identifier of the savings plan. Universally Unique Identifier (UUID).", "schema": { "title": "Savings plan unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a savings plan.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_savings_plan_executions", "summary": "List savings plan executions", "description": "List savings plan executions for a saving plan specified by its ID.", "tags": [ "Savings Plans" ], "security": [ { "oauth-client-credentials": [ "savings_plans:read", "savings_plans:admin" ] } ], "parameters": [ { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "title": "Date in YYYY-MM-DD format. RFC 3339, section 5.6", "description": "Returns savings plan executions starting from and including this date (UTC)" }, "example": "2022-10-14T10:10:10Z" }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "title": "Date in YYYY-MM-DD format. RFC 3339, section 5.6", "description": "Returns savings plan executions up to this date (UTC)" }, "example": "2022-10-14T10:10:10Z" }, { "name": "sort", "in": "query", "required": false, "description": "Sort the result by `execution_date`, `created_at`, or `updated_at`.", "schema": { "type": "string", "enum": [ "execution_date", "created_at", "updated_at" ], "default": "execution_date" } }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Savings plan execution - List - Response", "type": "object", "description": "Paginated list of savings plan executions for a savings plan, including cursor-based pagination metadata.", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "items": { "title": "Savings plan execution", "anyOf": [ { "title": "Savings plan execution (instrument)", "type": "object", "description": "Represents a single execution of an `INSTRUMENT`-type savings plan, recording the order placed, the execution date, and the resulting status.", "properties": { "id": { "title": "Savings plan execution unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a savings plan execution.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "savings_plan_id": { "title": "Savings plan unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a savings plan.", "format": "uuid" }, "order_id": { "title": "Order unique identifier (Portfolio order or Instrument order)", "description": "Order unique identifier (Portfolio order or Instrument order)", "oneOf": [ { "title": "Portfolios order unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio order.", "format": "uuid" }, { "title": "Order", "type": "object", "description": "Represents an investment order placed by an end user or on their behalf. An order transitions through states (`NEW` → `PROCESSING` → `FILLED` or `CANCELLED`) as it is routed and executed.", "properties": { "id": { "title": "Order unique identifier", "type": "string", "description": "Unique identifier for an order. Universally Unique Identifier (UUID).", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "type": "string", "format": "uuid", "description": "The ID of the user. Either user ID or business ID must be specified." }, "business_id": { "type": "string", "format": "uuid", "description": "The ID of the business. Either user ID or business ID must be specified." }, "account_id": { "type": "string", "format": "uuid", "description": "The ID of the account that owns the order" }, "cash_amount": { "allOf": [ { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, { "description": "Cash amount for a nominal order, not required if a share quantity is specified." } ] }, "currency": { "allOf": [ { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound\n* USD - US Dollar", "enum": [ "EUR", "GBP", "USD" ] }, { "description": "The currency for the order." } ] }, "side": { "type": "string", "description": "Side of the order.\n* BUY — purchases the specified instrument.\n* SELL — disposes of the specified instrument.", "enum": [ "BUY", "SELL" ] }, "instrument_id": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, "instrument_id_type": { "description": "The type of the ID used in the request.\n* ISIN - ", "enum": [ "ISIN" ], "default": "ISIN", "type": "string" }, "order_type": { "type": "string", "description": "Type of the order.\n* MARKET — executes immediately at the best available market price.\n* LIMIT — executes only at or better than the specified `limit_price`.\n* STOP — triggers when the market price reaches `stop_price`, then executes at the prevailing market price.", "enum": [ "MARKET", "LIMIT", "STOP" ] }, "quantity": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "Quantity of securities for the order. Only required if the cash amount is not specified." } ] }, "user_instrument_fit_acknowledgement": { "type": "boolean", "description": "Only applicable if the user has failed the instrument fit check for the instrument type being ordered. True if the user has acknowledged their willingness to trade." }, "limit_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The limit price for orders of the type 'limit'." } ] }, "stop_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The stop price for orders of the type 'stop'." } ] }, "expiry_date": { "allOf": [ { "title": "Expiry date", "type": "string", "description": "Order expiration date in YYYY-MM-DD format. Only applicable to `LIMIT` and `STOP` orders — the order will not execute after this date. Defaults to order creation date plus 359 days.", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, { "description": "The order expiration date (last day the order can trade) in the YYYY-MM-DD format. The expiry date can only be set for LIMIT and STOP orders. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339. The default value is order creation date + 359 days" } ] }, "status": { "type": "string", "description": "The execution status of the order.\n* NEW — the order has been received and validated, awaiting routing.\n* PROCESSING — the order is being routed for execution.\n* FILLED — the order has been fully executed.\n* CANCELLED — the order was cancelled before being fully executed.", "enum": [ "NEW", "PROCESSING", "FILLED", "CANCELLED" ] }, "fee": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "cancellation_reason": { "type": "string", "description": "Reason for order cancellation. Present only when `status` is `CANCELLED`.\n* CANCELLED_BY_CLIENT — cancelled at the end user's or client's request via the API.\n* CANCELLED_BY_UPVEST_OPERATIONS — cancelled by Upvest operations.\n* CANCELLED_BY_TRADING_PARTNER — cancelled by the executing partner.\n* CANCELLED_BY_UPVEST_PLATFORM — cancelled automatically by the Upvest platform.", "enum": [ "CANCELLED_BY_CLIENT", "CANCELLED_BY_UPVEST_OPERATIONS", "CANCELLED_BY_TRADING_PARTNER", "CANCELLED_BY_UPVEST_PLATFORM" ] }, "initiation_flow": { "type": "string", "description": "Identifies what triggered the order.\n* API — initiated directly via the client API.\n* PORTFOLIO — initiated by a portfolio rebalancing flow.\n* CASH_DIVIDEND_REINVESTMENT — initiated as part of dividend reinvestment.\n* PORTFOLIO_REBALANCING — initiated by an automated rebalancing.\n* SELL_TO_COVER_FEES — initiated automatically to cover outstanding fees.\n* SELL_TO_COVER_TAXES — initiated automatically to cover tax obligations.\n* ACCOUNT_LIQUIDATION — initiated as part of an account liquidation.\n* UPVEST_OPERATIONS — initiated by Upvest operations.\n* SAVINGS_PLAN — initiated by a savings plan execution.\n* CLIENT_OPERATIONS — initiated by client operations.", "enum": [ "API", "PORTFOLIO", "CASH_DIVIDEND_REINVESTMENT", "PORTFOLIO_REBALANCING", "SELL_TO_COVER_FEES", "SELL_TO_COVER_TAXES", "ACCOUNT_LIQUIDATION", "UPVEST_OPERATIONS", "SAVINGS_PLAN", "CLIENT_OPERATIONS" ] }, "execution_flow": { "type": "string", "description": "Execution flow for order processing. Defaults to `STRAIGHT_THROUGH` if not specified.\n* STRAIGHT_THROUGH — the order is routed and executed directly without manual intervention.\n* BLOCK — the order is bundled with other orders for block execution.", "enum": [ "STRAIGHT_THROUGH", "BLOCK" ] }, "executions": { "type": "array", "description": "Order executions associated with this order", "items": { "title": "Order execution", "type": "object", "description": "Represents a single execution (trade fill) within an order. An order may have multiple executions if it is partially filled across several trades.", "properties": { "id": { "title": "Order execution unique identifier", "type": "string", "format": "uuid" }, "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "share_quantity": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "price": { "type": "string", "description": "Price of an instrument for a trade execution provided as a decimal string.", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,4})?$" }, "transaction_time": { "type": "string", "format": "date-time", "description": "Timestamp of when the trade was executed at the market. [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) date-time format." }, "taxes": { "type": "array", "description": "Taxes deducted as part of this execution.", "items": { "title": "Tax", "type": "object", "description": "Tax deducted as part of an order execution. Contains the tax type and the deducted amount.", "properties": { "type": { "type": "string", "description": "Tax type\n* TOTAL - ", "default": "TOTAL", "enum": [ "TOTAL" ] }, "amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" } }, "required": [ "type", "amount" ] } }, "order_id": { "title": "Order unique identifier", "type": "string", "description": "Unique identifier for an order. Universally Unique Identifier (UUID).", "format": "uuid" }, "status": { "type": "string", "description": "Status of the execution.\n* FILLED — the execution has been filled.\n* SETTLED — the execution has settled and securities and cash have been exchanged.\n* CANCELLED — the execution was cancelled before settlement.", "enum": [ "FILLED", "SETTLED", "CANCELLED" ] }, "side": { "type": "string", "description": "Side of the execution.\n* BUY — a buy execution.\n* SELL — a sell execution.", "enum": [ "BUY", "SELL" ] }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound\n* USD - US Dollar", "enum": [ "EUR", "GBP", "USD" ] }, "settlement_date": { "allOf": [ { "title": "Settlement date", "type": "string", "description": "Trade settlement date in YYYY-MM-DD format. The date on which securities and cash are exchanged following execution.", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, { "description": "Order execution settlement date in the YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339" } ] }, "venue_id": { "type": "string", "format": "uuid", "description": "The ID of the venue" } }, "required": [ "id", "cash_amount", "share_quantity", "price", "transaction_time", "taxes", "order_id", "status", "side", "currency", "venue_id" ], "additionalProperties": false } }, "client_reference": { "type": "string", "description": "Immutable reference to the API flow that initiated the order. For client initiated API flows, this is a client provided ID. For internal initiations, it is set to the ID of the related object.", "maxLength": 100 }, "fee_configuration": { "type": "array", "description": "Fee configuration applied to this order. Determines how the order fee is calculated.", "items": { "title": "Fee", "description": "A fee applied to an order. Either a fixed absolute cash fee (`absolute_fee_configuration_item`) or a reference to a predefined transaction fee model.", "oneOf": [ { "title": "Absolute Fee", "type": "object", "description": "A fixed cash fee applied to an order, specified as an absolute amount in a given currency.", "properties": { "type": { "title": "Fee type", "description": "Fee type\n* TRANSACTION_FEE_BUY - \n* TRANSACTION_FEE_SELL - ", "type": "string", "enum": [ "TRANSACTION_FEE_BUY", "TRANSACTION_FEE_SELL" ] }, "value_type": { "type": "string", "default": "ABSOLUTE", "description": "The value type must be “ABSOLUTE”." }, "charge_method": { "title": "Fee charge method", "type": "string", "description": "Indicates whether the fee will be charged by client or by other methods.\n* CHARGED_BY_CLIENT - \n* COLLECTED_BY_UPVEST - ", "enum": [ "CHARGED_BY_CLIENT", "COLLECTED_BY_UPVEST" ] }, "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound\n* USD - US Dollar", "enum": [ "EUR", "GBP", "USD" ] } }, "required": [ "type", "value_type", "charge_method", "cash_amount", "currency" ], "additionalProperties": false }, { "title": "Transaction Fee Model", "type": "object", "description": "A fee configuration that references a predefined transaction fee model by its ID, rather than specifying a fee amount directly.", "properties": { "type": { "title": "Fee type", "description": "Fee type\n* TRANSACTION_FEE_BUY - \n* TRANSACTION_FEE_SELL - ", "type": "string", "enum": [ "TRANSACTION_FEE_BUY", "TRANSACTION_FEE_SELL" ] }, "transaction_fee_model_id": { "type": "string", "format": "uuid", "description": "The ID of the transaction fee model." } }, "required": [ "type", "transaction_fee_model_id" ], "additionalProperties": false } ] } }, "decision_maker_id": { "type": "string", "description": "ID of the user behind the decision to place an order. Required only if different from the user_id. (e.g. child account order placed by a guardian)" } }, "required": [ "id", "created_at", "updated_at", "account_id", "cash_amount", "currency", "side", "instrument_id", "instrument_id_type", "order_type", "quantity", "status", "fee", "initiation_flow", "executions" ], "additionalProperties": false }, { "type": "null" } ] }, "cash_amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "status": { "type": "string", "description": "Status of a Savings Plan Execution. \n* NEW - \n* PROCESSING - \n* FILLED - \n* SETTLED - \n* CANCELLED - ", "enum": [ "NEW", "PROCESSING", "FILLED", "SETTLED", "CANCELLED" ] }, "type": { "type": "string", "default": "INSTRUMENT", "description": "The type of savings plan must be \"INSTRUMENT\"." }, "execution_date": { "type": "string", "description": "Date of a savings plan execution in YYYY-MM-DD format.", "pattern": "^[12]\\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "instrument_id": { "title": "Instrument unique identifier", "description": "Instrument unique identifier.", "oneOf": [ { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, { "title": "German securities identification code", "type": "string", "description": "German securities identification code known as [Wertpapierkennnummer](https://en.wikipedia.org/wiki/Wertpapierkennnummer).", "pattern": "^[A-HJ-NP-Z0-9]{6}$" } ] }, "instrument_id_type": { "type": "string", "description": "The type of the ID used in the request.\n* ISIN - International Securities Identification Number\n* WKN - German securities identification code", "enum": [ "ISIN", "WKN" ], "default": "ISIN" }, "fee_configuration": { "title": "Savings plan fee configuration, only for instrument", "type": "array", "description": "Fee configuration for instrument-type savings plan executions. Specifies the transaction fee model to apply to each buy order placed on execution.", "items": { "type": "object", "properties": { "type": { "title": "Fee type", "description": "Fee type\n* TRANSACTION_FEE_BUY -", "type": "string", "enum": [ "TRANSACTION_FEE_BUY" ] }, "transaction_fee_model_id": { "title": "Fee model unique identifier.", "type": "string", "description": "Universally Unique Identifier (UUID) of the transaction fee model.", "format": "uuid" } }, "required": [ "type", "transaction_fee_model_id" ], "additionalProperties": false } }, "cancellation_reason": { "title": "Cancellation reason code for savings plan execution", "description": "Explains the reason why the savings plan execution was cancelled .\n* CANCELLED_BY_CLIENT: The savings plan execution was cancelled by the client.\n* CANCELLED_BY_UPVEST: The savings plan execution was cancelled by Upvest.", "type": "string", "enum": [ "CANCELLED_BY_CLIENT", "CANCELLED_BY_UPVEST" ] }, "cancellation_details": { "title": "Cancellation details for savings plan execution", "description": "Human-readable description providing additional context about why the savings plan execution was cancelled.", "type": "string" } }, "required": [ "id", "user_id", "account_id", "savings_plan_id", "order_id", "cash_amount", "currency", "status", "type", "execution_date", "created_at", "updated_at" ], "additionalProperties": false }, { "title": "Savings plan execution (portfolio)", "type": "object", "description": "Represents a single execution of a `PORTFOLIO`-type savings plan, recording the portfolio order placed, the execution date, and the resulting status.", "properties": { "id": { "title": "Savings plan execution unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a savings plan execution.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "savings_plan_id": { "title": "Savings plan unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a savings plan.", "format": "uuid" }, "order_id": { "title": "Order unique identifier (Portfolio order or Instrument order)", "description": "Order unique identifier (Portfolio order or Instrument order)", "oneOf": [ { "title": "Portfolios order unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio order.", "format": "uuid" }, { "title": "Order", "type": "object", "description": "Represents an investment order placed by an end user or on their behalf. An order transitions through states (`NEW` → `PROCESSING` → `FILLED` or `CANCELLED`) as it is routed and executed.", "properties": { "id": { "title": "Order unique identifier", "type": "string", "description": "Unique identifier for an order. Universally Unique Identifier (UUID).", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "type": "string", "format": "uuid", "description": "The ID of the user. Either user ID or business ID must be specified." }, "business_id": { "type": "string", "format": "uuid", "description": "The ID of the business. Either user ID or business ID must be specified." }, "account_id": { "type": "string", "format": "uuid", "description": "The ID of the account that owns the order" }, "cash_amount": { "allOf": [ { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, { "description": "Cash amount for a nominal order, not required if a share quantity is specified." } ] }, "currency": { "allOf": [ { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound\n* USD - US Dollar", "enum": [ "EUR", "GBP", "USD" ] }, { "description": "The currency for the order." } ] }, "side": { "type": "string", "description": "Side of the order.\n* BUY — purchases the specified instrument.\n* SELL — disposes of the specified instrument.", "enum": [ "BUY", "SELL" ] }, "instrument_id": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, "instrument_id_type": { "description": "The type of the ID used in the request.\n* ISIN - ", "enum": [ "ISIN" ], "default": "ISIN", "type": "string" }, "order_type": { "type": "string", "description": "Type of the order.\n* MARKET — executes immediately at the best available market price.\n* LIMIT — executes only at or better than the specified `limit_price`.\n* STOP — triggers when the market price reaches `stop_price`, then executes at the prevailing market price.", "enum": [ "MARKET", "LIMIT", "STOP" ] }, "quantity": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "Quantity of securities for the order. Only required if the cash amount is not specified." } ] }, "user_instrument_fit_acknowledgement": { "type": "boolean", "description": "Only applicable if the user has failed the instrument fit check for the instrument type being ordered. True if the user has acknowledged their willingness to trade." }, "limit_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The limit price for orders of the type 'limit'." } ] }, "stop_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The stop price for orders of the type 'stop'." } ] }, "expiry_date": { "allOf": [ { "title": "Expiry date", "type": "string", "description": "Order expiration date in YYYY-MM-DD format. Only applicable to `LIMIT` and `STOP` orders — the order will not execute after this date. Defaults to order creation date plus 359 days.", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, { "description": "The order expiration date (last day the order can trade) in the YYYY-MM-DD format. The expiry date can only be set for LIMIT and STOP orders. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339. The default value is order creation date + 359 days" } ] }, "status": { "type": "string", "description": "The execution status of the order.\n* NEW — the order has been received and validated, awaiting routing.\n* PROCESSING — the order is being routed for execution.\n* FILLED — the order has been fully executed.\n* CANCELLED — the order was cancelled before being fully executed.", "enum": [ "NEW", "PROCESSING", "FILLED", "CANCELLED" ] }, "fee": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "cancellation_reason": { "type": "string", "description": "Reason for order cancellation. Present only when `status` is `CANCELLED`.\n* CANCELLED_BY_CLIENT — cancelled at the end user's or client's request via the API.\n* CANCELLED_BY_UPVEST_OPERATIONS — cancelled by Upvest operations.\n* CANCELLED_BY_TRADING_PARTNER — cancelled by the executing partner.\n* CANCELLED_BY_UPVEST_PLATFORM — cancelled automatically by the Upvest platform.", "enum": [ "CANCELLED_BY_CLIENT", "CANCELLED_BY_UPVEST_OPERATIONS", "CANCELLED_BY_TRADING_PARTNER", "CANCELLED_BY_UPVEST_PLATFORM" ] }, "initiation_flow": { "type": "string", "description": "Identifies what triggered the order.\n* API — initiated directly via the client API.\n* PORTFOLIO — initiated by a portfolio rebalancing flow.\n* CASH_DIVIDEND_REINVESTMENT — initiated as part of dividend reinvestment.\n* PORTFOLIO_REBALANCING — initiated by an automated rebalancing.\n* SELL_TO_COVER_FEES — initiated automatically to cover outstanding fees.\n* SELL_TO_COVER_TAXES — initiated automatically to cover tax obligations.\n* ACCOUNT_LIQUIDATION — initiated as part of an account liquidation.\n* UPVEST_OPERATIONS — initiated by Upvest operations.\n* SAVINGS_PLAN — initiated by a savings plan execution.\n* CLIENT_OPERATIONS — initiated by client operations.", "enum": [ "API", "PORTFOLIO", "CASH_DIVIDEND_REINVESTMENT", "PORTFOLIO_REBALANCING", "SELL_TO_COVER_FEES", "SELL_TO_COVER_TAXES", "ACCOUNT_LIQUIDATION", "UPVEST_OPERATIONS", "SAVINGS_PLAN", "CLIENT_OPERATIONS" ] }, "execution_flow": { "type": "string", "description": "Execution flow for order processing. Defaults to `STRAIGHT_THROUGH` if not specified.\n* STRAIGHT_THROUGH — the order is routed and executed directly without manual intervention.\n* BLOCK — the order is bundled with other orders for block execution.", "enum": [ "STRAIGHT_THROUGH", "BLOCK" ] }, "executions": { "type": "array", "description": "Order executions associated with this order", "items": { "title": "Order execution", "type": "object", "description": "Represents a single execution (trade fill) within an order. An order may have multiple executions if it is partially filled across several trades.", "properties": { "id": { "title": "Order execution unique identifier", "type": "string", "format": "uuid" }, "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "share_quantity": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "price": { "type": "string", "description": "Price of an instrument for a trade execution provided as a decimal string.", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,4})?$" }, "transaction_time": { "type": "string", "format": "date-time", "description": "Timestamp of when the trade was executed at the market. [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) date-time format." }, "taxes": { "type": "array", "description": "Taxes deducted as part of this execution.", "items": { "title": "Tax", "type": "object", "description": "Tax deducted as part of an order execution. Contains the tax type and the deducted amount.", "properties": { "type": { "type": "string", "description": "Tax type\n* TOTAL - ", "default": "TOTAL", "enum": [ "TOTAL" ] }, "amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" } }, "required": [ "type", "amount" ] } }, "order_id": { "title": "Order unique identifier", "type": "string", "description": "Unique identifier for an order. Universally Unique Identifier (UUID).", "format": "uuid" }, "status": { "type": "string", "description": "Status of the execution.\n* FILLED — the execution has been filled.\n* SETTLED — the execution has settled and securities and cash have been exchanged.\n* CANCELLED — the execution was cancelled before settlement.", "enum": [ "FILLED", "SETTLED", "CANCELLED" ] }, "side": { "type": "string", "description": "Side of the execution.\n* BUY — a buy execution.\n* SELL — a sell execution.", "enum": [ "BUY", "SELL" ] }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound\n* USD - US Dollar", "enum": [ "EUR", "GBP", "USD" ] }, "settlement_date": { "allOf": [ { "title": "Settlement date", "type": "string", "description": "Trade settlement date in YYYY-MM-DD format. The date on which securities and cash are exchanged following execution.", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, { "description": "Order execution settlement date in the YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339" } ] }, "venue_id": { "type": "string", "format": "uuid", "description": "The ID of the venue" } }, "required": [ "id", "cash_amount", "share_quantity", "price", "transaction_time", "taxes", "order_id", "status", "side", "currency", "venue_id" ], "additionalProperties": false } }, "client_reference": { "type": "string", "description": "Immutable reference to the API flow that initiated the order. For client initiated API flows, this is a client provided ID. For internal initiations, it is set to the ID of the related object.", "maxLength": 100 }, "fee_configuration": { "type": "array", "description": "Fee configuration applied to this order. Determines how the order fee is calculated.", "items": { "title": "Fee", "description": "A fee applied to an order. Either a fixed absolute cash fee (`absolute_fee_configuration_item`) or a reference to a predefined transaction fee model.", "oneOf": [ { "title": "Absolute Fee", "type": "object", "description": "A fixed cash fee applied to an order, specified as an absolute amount in a given currency.", "properties": { "type": { "title": "Fee type", "description": "Fee type\n* TRANSACTION_FEE_BUY - \n* TRANSACTION_FEE_SELL - ", "type": "string", "enum": [ "TRANSACTION_FEE_BUY", "TRANSACTION_FEE_SELL" ] }, "value_type": { "type": "string", "default": "ABSOLUTE", "description": "The value type must be “ABSOLUTE”." }, "charge_method": { "title": "Fee charge method", "type": "string", "description": "Indicates whether the fee will be charged by client or by other methods.\n* CHARGED_BY_CLIENT - \n* COLLECTED_BY_UPVEST - ", "enum": [ "CHARGED_BY_CLIENT", "COLLECTED_BY_UPVEST" ] }, "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound\n* USD - US Dollar", "enum": [ "EUR", "GBP", "USD" ] } }, "required": [ "type", "value_type", "charge_method", "cash_amount", "currency" ], "additionalProperties": false }, { "title": "Transaction Fee Model", "type": "object", "description": "A fee configuration that references a predefined transaction fee model by its ID, rather than specifying a fee amount directly.", "properties": { "type": { "title": "Fee type", "description": "Fee type\n* TRANSACTION_FEE_BUY - \n* TRANSACTION_FEE_SELL - ", "type": "string", "enum": [ "TRANSACTION_FEE_BUY", "TRANSACTION_FEE_SELL" ] }, "transaction_fee_model_id": { "type": "string", "format": "uuid", "description": "The ID of the transaction fee model." } }, "required": [ "type", "transaction_fee_model_id" ], "additionalProperties": false } ] } }, "decision_maker_id": { "type": "string", "description": "ID of the user behind the decision to place an order. Required only if different from the user_id. (e.g. child account order placed by a guardian)" } }, "required": [ "id", "created_at", "updated_at", "account_id", "cash_amount", "currency", "side", "instrument_id", "instrument_id_type", "order_type", "quantity", "status", "fee", "initiation_flow", "executions" ], "additionalProperties": false }, { "type": "null" } ] }, "cash_amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "status": { "type": "string", "description": "Status of a Savings Plan Execution. \n* NEW - \n* PROCESSING - \n* FILLED - \n* SETTLED - \n* CANCELLED - ", "enum": [ "NEW", "PROCESSING", "FILLED", "SETTLED", "CANCELLED" ] }, "type": { "type": "string", "default": "PORTFOLIO", "description": "The type of savings plan must be \"PORTFOLIO\"." }, "execution_date": { "type": "string", "description": "Date of a savings plan execution in YYYY-MM-DD format.", "pattern": "^[12]\\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "instrument_id": { "title": "Instrument unique identifier", "description": "Instrument unique identifier.", "oneOf": [ { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, { "title": "German securities identification code", "type": "string", "description": "German securities identification code known as [Wertpapierkennnummer](https://en.wikipedia.org/wiki/Wertpapierkennnummer).", "pattern": "^[A-HJ-NP-Z0-9]{6}$" } ] }, "instrument_id_type": { "type": "string", "description": "The type of the ID used in the request.\n* ISIN - International Securities Identification Number\n* WKN - German securities identification code", "enum": [ "ISIN", "WKN" ], "default": "ISIN" }, "cancellation_reason": { "title": "Cancellation reason code for savings plan execution", "description": "Explains the reason why the savings plan execution was cancelled .\n* CANCELLED_BY_CLIENT: The savings plan execution was cancelled by the client.\n* CANCELLED_BY_UPVEST: The savings plan execution was cancelled by Upvest.", "type": "string", "enum": [ "CANCELLED_BY_CLIENT", "CANCELLED_BY_UPVEST" ] }, "cancellation_details": { "title": "Cancellation details for savings plan execution", "description": "Human-readable description providing additional context about why the savings plan execution was cancelled.", "type": "string" } }, "required": [ "id", "user_id", "account_id", "savings_plan_id", "order_id", "cash_amount", "currency", "status", "type", "execution_date", "created_at", "updated_at" ], "additionalProperties": false } ] } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "examples": { "instrument": { "summary": "instrument", "value": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1, "sort": "execution_date", "order": "ASC" }, "data": [ { "id": "fc34d28e-38f5-49d2-92f6-82acb79098f4", "created_at": "2023-07-21T14:10:00.00Z", "updated_at": "2023-07-21T15:10:00.00Z", "user_id": "4b9732bd-7496-4913-8a5f-6360479d7fed", "account_id": "00ef0be8-d564-43af-b3c7-11b7a2188030", "savings_plan_id": "c31083c1-1cd3-405f-95d1-f49a37f0e032", "order_id": "68068440-6b8e-4700-8cfc-95bf21b34b96", "cash_amount": "100", "currency": "EUR", "status": "FILLED", "type": "INSTRUMENT", "instrument_id": "DE0007664005", "instrument_id_type": "ISIN", "execution_date": "2023-10-05", "fee_configuration": [ { "type": "TRANSACTION_FEE_BUY", "transaction_fee_model_id": "3ae9403c-1611-46eb-84ee-e06a02bcfd08" } ] } ] } }, "portfolio": { "summary": "portfolio", "value": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1, "sort": "execution_date", "order": "ASC" }, "data": [ { "id": "fc34d28e-38f5-49d2-92f6-82acb79098f4", "created_at": "2023-07-21T14:10:00.00Z", "updated_at": "2023-07-21T15:10:00.00Z", "user_id": "4b9732bd-7496-4913-8a5f-6360479d7fed", "account_id": "00ef0be8-d564-43af-b3c7-11b7a2188030", "savings_plan_id": "c31083c1-1cd3-405f-95d1-f49a37f0e032", "order_id": "68068440-6b8e-4700-8cfc-95bf21b34b96", "cash_amount": "100", "currency": "EUR", "status": "FILLED", "type": "PORTFOLIO", "execution_date": "2023-10-05" } ] } } } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "405": { "description": "Method Not Allowed. The requested method is not allowed on the requested resource.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 405, "type": "method_not_allowed" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/businesses": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_businesses", "summary": "Get all businesses", "description": "Returns a paginated list of all businesses.\n\nUse `offset` and `limit` to paginate through results, and `sort`/`order` to control the ordering by `created_at` or `updated_at`.\n\nSee the Business accounts guide ([TOL](https://docs.upvest.co/products/tol/guides/accounts/businesses_overview) / [BYOL](https://docs.upvest.co/products/byol/guides/accounts/businesses_overview)) for business account types.", "tags": [ "Businesses" ], "security": [ { "oauth-client-credentials": [ "businesses:read", "businesses:admin" ] } ], "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "updated_at" ], "default": "created_at" }, "description": "Sort the result by `created_at`, `updated_at`." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Businesses - List - Response", "type": "object", "description": "Response for listing businesses.", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "description": "List of businesses", "items": { "title": "Business", "description": "A business entity onboarded with Upvest, either a company or a sole trader.", "oneOf": [ { "type": "object", "description": "Schema for business company information.", "properties": { "id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "contact_email": { "type": "string", "format": "email", "description": "Contact email address of the business." }, "registered_address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, "registration_number": { "type": "string", "description": "Registration number of the business." }, "tax_information": { "type": "object", "properties": { "tax_country_code": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "tax_identification_type": { "type": "string", "enum": [ "STEUERNUMMER", "WIRTSCHAFTSIDENTIFIKATIONSNUMMER" ], "description": "Type of tax identification used by the business." }, "tax_identification_number": { "type": "string", "description": "Tax identification number of the business.\n\nWhen `tax_identification_type` is `STEUERNUMMER`, the value is 10 or 11 digits, provided either as bare digits or in a state-specific slash-grouped layout. Slashes are all-or-nothing and must appear at the grouping positions:\n\n| Format | Grouping | Example |\n| --- | --- | --- |\n| Bare digits | 10 or 11 digits | `1234567890`, `12345678901` |\n| North Rhine-Westphalia | 3/4/4 | `133/8150/8159` |\n| Bavaria | 3/3/5 | `181/815/08155` |\n| Standard 10-digit | 2/3/5 | `24/815/08151` |\n| Alternative 10-digit (Berlin, Bremen, Lower Saxony) | 3/3/4 | `181/815/0815` |\n\nWhen `tax_identification_type` is `WIRTSCHAFTSIDENTIFIKATIONSNUMMER`, the value is `DE` followed by 9 digits, with an optional 5-digit distinguishing feature (for example `DE123456789` or `DE123456789-00001`)." }, "is_resident_in_multiple_tax_jurisdictions": { "type": "boolean", "description": "Indicates if the business is resident in multiple tax jurisdictions." }, "is_subject_to_fatca": { "type": "boolean", "description": "Indicates if the business is subject to FATCA regulations." } }, "required": [ "tax_country_code", "tax_identification_type", "tax_identification_number", "is_resident_in_multiple_tax_jurisdictions", "is_subject_to_fatca" ], "description": "Tax information of the business." }, "business_type": { "default": "LIMITED_LIABILITY_COMPANY", "description": "Type of the business." }, "identification": { "type": "object", "properties": { "company_name": { "type": "string", "description": "Name of the company." }, "incorporation_date": { "type": "string", "description": "Incorporation date of the business in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" }, "district_court": { "type": "string", "minLength": 1, "maxLength": 40, "description": "District court where the company is registered." }, "legal_designation": { "type": "string", "enum": [ "GESELLSCHAFT_MIT_BESCHRAENKTER_HAFTUNG", "UNTERNEHMERGESELLSCHAFT", "AKTIENGESELLSCHAFT" ], "description": "Country specific legal designation of the company.\nNote: `AKTIENGESELLSCHAFT` businesses cannot be created via the API; please contact Upvest support before onboarding such a business." }, "legal_entity_identifier": { "type": "string", "pattern": "^[A-Z0-9]{18}[0-9]{2}$", "description": "Legal Entity Identifier (LEI) of the company. A 20-character alphanumeric code as defined by [ISO 17442](https://en.wikipedia.org/wiki/Legal_Entity_Identifier)." }, "common_reporting_standards": { "type": "object", "properties": { "is_passive_non_financial_entity": { "type": "boolean", "description": "Indicates if the company is a passive non-financial entity." }, "is_financial_institution": { "type": "boolean", "description": "Indicates if the company is a financial institution." } }, "required": [ "is_passive_non_financial_entity", "is_financial_institution" ], "description": "Common reporting standards information." } }, "required": [ "company_name", "incorporation_date", "district_court", "legal_designation", "common_reporting_standards" ], "description": "Identification information of the business." }, "terms_and_conditions": { "type": "object", "properties": { "consent_document_id": { "type": "string", "format": "uuid", "description": "UUID of the consent document." }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the terms and conditions were confirmed." } }, "required": [ "consent_document_id", "confirmed_at" ], "description": "Terms and conditions agreement." }, "data_privacy_and_sharing_agreement": { "type": "object", "properties": { "consent_document_id": { "type": "string", "format": "uuid", "description": "UUID of the data privacy and sharing agreement document." }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the data privacy and sharing agreement was confirmed." } }, "required": [ "consent_document_id", "confirmed_at" ], "description": "Data privacy and sharing agreement." }, "status": { "enum": [ "ACTIVE", "INACTIVE", "OFFBOARDING", "OFFBOARDED" ], "description": "Status of the business.\n* ACTIVE - \n* INACTIVE - \n* OFFBOARDING - \n* OFFBOARDED - " } }, "required": [ "id", "contact_email", "registered_address", "registration_number", "tax_information", "business_type", "identification", "terms_and_conditions", "data_privacy_and_sharing_agreement", "status", "created_at", "updated_at" ], "additionalProperties": false }, { "type": "object", "description": "Schema for business company information.", "properties": { "id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "contact_email": { "type": "string", "format": "email", "description": "Contact email address of the business." }, "registered_address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, "registration_number": { "type": "string", "description": "Registration number of the business." }, "tax_information": { "type": "object", "properties": { "tax_country_code": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "tax_identification_type": { "type": "string", "enum": [ "STEUERNUMMER", "WIRTSCHAFTSIDENTIFIKATIONSNUMMER" ], "description": "Type of tax identification used by the business." }, "tax_identification_number": { "type": "string", "description": "Tax identification number of the business.\n\nWhen `tax_identification_type` is `STEUERNUMMER`, the value is 10 or 11 digits, provided either as bare digits or in a state-specific slash-grouped layout. Slashes are all-or-nothing and must appear at the grouping positions:\n\n| Format | Grouping | Example |\n| --- | --- | --- |\n| Bare digits | 10 or 11 digits | `1234567890`, `12345678901` |\n| North Rhine-Westphalia | 3/4/4 | `133/8150/8159` |\n| Bavaria | 3/3/5 | `181/815/08155` |\n| Standard 10-digit | 2/3/5 | `24/815/08151` |\n| Alternative 10-digit (Berlin, Bremen, Lower Saxony) | 3/3/4 | `181/815/0815` |\n\nWhen `tax_identification_type` is `WIRTSCHAFTSIDENTIFIKATIONSNUMMER`, the value is `DE` followed by 9 digits, with an optional 5-digit distinguishing feature (for example `DE123456789` or `DE123456789-00001`)." }, "is_resident_in_multiple_tax_jurisdictions": { "type": "boolean", "description": "Indicates if the business is resident in multiple tax jurisdictions." }, "is_subject_to_fatca": { "type": "boolean", "description": "Indicates if the business is subject to FATCA regulations." } }, "required": [ "tax_country_code", "tax_identification_type", "tax_identification_number", "is_resident_in_multiple_tax_jurisdictions", "is_subject_to_fatca" ], "description": "Tax information of the business." }, "business_type": { "type": "string", "default": "SOLE_TRADER", "description": "Type of the business. Always `SOLE_TRADER` for sole trader businesses." }, "identification": { "type": "object", "properties": { "company_name": { "type": "string", "description": "Name of the sole trader business." }, "incorporation_date": { "type": "string", "description": "Incorporation date of the business in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" }, "legal_designation": { "type": "string", "enum": [ "EINZELUNTERNEHMER", "FREIBERUFLER", "EINGETRAGENER_KAUFMANN", "EINGETRAGENE_KAUFFRAU" ], "description": "Country specific legal designation of the sole trader business." } }, "required": [ "company_name", "legal_designation" ], "description": "Identification information of the sole trader business." }, "terms_and_conditions": { "type": "object", "properties": { "consent_document_id": { "type": "string", "format": "uuid", "description": "UUID of the consent document." }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the terms and conditions were confirmed." } }, "required": [ "consent_document_id", "confirmed_at" ], "description": "Terms and conditions agreement." }, "data_privacy_and_sharing_agreement": { "type": "object", "properties": { "consent_document_id": { "type": "string", "format": "uuid", "description": "UUID of the data privacy and sharing agreement document." }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the data privacy and sharing agreement was confirmed." } }, "required": [ "consent_document_id", "confirmed_at" ], "description": "Data privacy and sharing agreement." }, "status": { "enum": [ "ACTIVE", "INACTIVE", "OFFBOARDING", "OFFBOARDED" ], "description": "Status of the business.\n* ACTIVE - \n* INACTIVE - \n* OFFBOARDING - \n* OFFBOARDED - " } }, "required": [ "id", "created_at", "updated_at", "contact_email", "registered_address", "tax_information", "business_type", "identification", "terms_and_conditions", "data_privacy_and_sharing_agreement", "status" ], "additionalProperties": false } ] } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "examples": { "List Businesses": { "summary": "List of businesses", "value": { "meta": { "offset": 0, "limit": 100, "count": 0, "total_count": 0, "sort": "created_at", "order": "ASC" }, "data": [ { "id": "a9a72268-4f3c-4de2-abb9-a553a3bb7608", "created_at": "2023-09-24T11:15:10Z", "updated_at": "2023-09-24T11:15:10Z", "contact_email": "acme.corporation@example.com", "registered_address": { "address_line1": "110", "address_line2": "Schonhauser Allee", "postcode": "101110", "city": "Berlin", "state": "BE", "country": "DE" }, "registration_number": "111221111", "tax_information": { "tax_country_code": "DE", "tax_identification_type": "STEUERNUMMER", "tax_identification_number": "12345678901", "is_resident_in_multiple_tax_jurisdictions": false, "is_subject_to_fatca": false }, "business_type": "LIMITED_LIABILITY_COMPANY", "identification": { "company_name": "Acme Corporation", "incorporation_date": "2000-01-01", "district_court": "Berlin Charlottenburg", "legal_designation": "GESELLSCHAFT_MIT_BESCHRAENKTER_HAFTUNG", "legal_entity_identifier": "213800K98H63P249S632", "common_reporting_standards": { "is_passive_non_financial_entity": false, "is_financial_institution": false } }, "terms_and_conditions": { "consent_document_id": "6a163d14-5b3d-48be-ac90-43314e96be71", "confirmed_at": "2023-10-24T14:14:22Z" }, "data_privacy_and_sharing_agreement": { "consent_document_id": "fa2227c3-2b29-47e1-84da-996d09517edc", "confirmed_at": "2023-10-24T14:16:22Z" }, "status": "ACTIVE" } ] } }, "Empty List": { "summary": "Empty businesses list", "value": { "meta": { "offset": 0, "limit": 100, "count": 0, "total_count": 0, "sort": "created_at", "order": "ASC" }, "data": [] } } } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "post": { "operationId": "create_business", "summary": "Create a business", "description": "Creates a business.\n\nSupports both corporate and sole trader business types, each with a different set of required fields.\n\nSee the Business accounts guide ([TOL](https://docs.upvest.co/products/tol/guides/accounts/businesses_overview) / [BYOL](https://docs.upvest.co/products/byol/guides/accounts/businesses_overview)) for implementation details.", "tags": [ "Businesses" ], "security": [ { "oauth-client-credentials": [ "businesses:admin" ] } ], "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$", "example": "ccb07f42-4104-44ad-8e1f-c660bb7b269c" }, "description": "A UUID to be used as an idempotency key. This prevents a duplicate request from being replayed.\nhttps://docs.upvest.co/documentation/concepts/api_concepts/idempotency\n" } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Business - Create - Request", "description": "Request payload for creating a business, either a company or a sole trader.", "oneOf": [ { "type": "object", "title": "Business (Company) - Create - Request", "description": "Schema for business company information.", "properties": { "contact_email": { "type": "string", "format": "email", "description": "Contact email address of the business." }, "registered_address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, "registration_number": { "type": "string", "description": "Registration number of the business." }, "tax_information": { "type": "object", "properties": { "tax_country_code": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "tax_identification_type": { "type": "string", "enum": [ "STEUERNUMMER", "WIRTSCHAFTSIDENTIFIKATIONSNUMMER" ], "description": "Type of tax identification used by the business." }, "tax_identification_number": { "type": "string", "description": "Tax identification number of the business.\n\nWhen `tax_identification_type` is `STEUERNUMMER`, the value is 10 or 11 digits, provided either as bare digits or in a state-specific slash-grouped layout. Slashes are all-or-nothing and must appear at the grouping positions:\n\n| Format | Grouping | Example |\n| --- | --- | --- |\n| Bare digits | 10 or 11 digits | `1234567890`, `12345678901` |\n| North Rhine-Westphalia | 3/4/4 | `133/8150/8159` |\n| Bavaria | 3/3/5 | `181/815/08155` |\n| Standard 10-digit | 2/3/5 | `24/815/08151` |\n| Alternative 10-digit (Berlin, Bremen, Lower Saxony) | 3/3/4 | `181/815/0815` |\n\nWhen `tax_identification_type` is `WIRTSCHAFTSIDENTIFIKATIONSNUMMER`, the value is `DE` followed by 9 digits, with an optional 5-digit distinguishing feature (for example `DE123456789` or `DE123456789-00001`)." }, "is_resident_in_multiple_tax_jurisdictions": { "type": "boolean", "description": "Indicates if the business is resident in multiple tax jurisdictions." }, "is_subject_to_fatca": { "type": "boolean", "description": "Indicates if the business is subject to FATCA regulations." } }, "required": [ "tax_country_code", "tax_identification_type", "tax_identification_number", "is_resident_in_multiple_tax_jurisdictions", "is_subject_to_fatca" ], "description": "Tax information of the business." }, "business_type": { "default": "LIMITED_LIABILITY_COMPANY", "description": "Type of the business." }, "identification": { "type": "object", "properties": { "company_name": { "type": "string", "description": "Name of the company." }, "incorporation_date": { "type": "string", "description": "Incorporation date of the business in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" }, "district_court": { "type": "string", "minLength": 1, "maxLength": 40, "description": "District court where the company is registered." }, "legal_designation": { "type": "string", "enum": [ "GESELLSCHAFT_MIT_BESCHRAENKTER_HAFTUNG", "UNTERNEHMERGESELLSCHAFT", "AKTIENGESELLSCHAFT" ], "description": "Country specific legal designation of the company.\nNote: `AKTIENGESELLSCHAFT` businesses cannot be created via the API; please contact Upvest support before onboarding such a business." }, "legal_entity_identifier": { "type": "string", "pattern": "^[A-Z0-9]{18}[0-9]{2}$", "description": "Legal Entity Identifier (LEI) of the company. A 20-character alphanumeric code as defined by [ISO 17442](https://en.wikipedia.org/wiki/Legal_Entity_Identifier)." }, "common_reporting_standards": { "type": "object", "properties": { "is_passive_non_financial_entity": { "type": "boolean", "description": "Indicates if the company is a passive non-financial entity." }, "is_financial_institution": { "type": "boolean", "description": "Indicates if the company is a financial institution." } }, "required": [ "is_passive_non_financial_entity", "is_financial_institution" ], "description": "Common reporting standards information." } }, "required": [ "company_name", "incorporation_date", "district_court", "legal_designation", "common_reporting_standards" ], "description": "Identification information of the business." }, "terms_and_conditions": { "type": "object", "properties": { "consent_document_id": { "type": "string", "format": "uuid", "description": "UUID of the consent document." }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the terms and conditions were confirmed." } }, "required": [ "consent_document_id", "confirmed_at" ], "description": "Terms and conditions agreement." }, "data_privacy_and_sharing_agreement": { "type": "object", "properties": { "consent_document_id": { "type": "string", "format": "uuid", "description": "UUID of the data privacy and sharing agreement document." }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the data privacy and sharing agreement was confirmed." } }, "required": [ "consent_document_id", "confirmed_at" ], "description": "Data privacy and sharing agreement." } }, "required": [ "contact_email", "registered_address", "registration_number", "business_type", "tax_information", "identification", "terms_and_conditions", "data_privacy_and_sharing_agreement" ] }, { "type": "object", "title": "Business (Sole Trader) - Create - Request", "description": "Schema for business company information.", "properties": { "contact_email": { "type": "string", "format": "email", "description": "Contact email address of the business." }, "registered_address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, "registration_number": { "type": "string", "description": "Registration number of the business." }, "tax_information": { "type": "object", "properties": { "tax_country_code": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "tax_identification_type": { "type": "string", "enum": [ "STEUERNUMMER", "WIRTSCHAFTSIDENTIFIKATIONSNUMMER" ], "description": "Type of tax identification used by the business." }, "tax_identification_number": { "type": "string", "description": "Tax identification number of the business.\n\nWhen `tax_identification_type` is `STEUERNUMMER`, the value is 10 or 11 digits, provided either as bare digits or in a state-specific slash-grouped layout. Slashes are all-or-nothing and must appear at the grouping positions:\n\n| Format | Grouping | Example |\n| --- | --- | --- |\n| Bare digits | 10 or 11 digits | `1234567890`, `12345678901` |\n| North Rhine-Westphalia | 3/4/4 | `133/8150/8159` |\n| Bavaria | 3/3/5 | `181/815/08155` |\n| Standard 10-digit | 2/3/5 | `24/815/08151` |\n| Alternative 10-digit (Berlin, Bremen, Lower Saxony) | 3/3/4 | `181/815/0815` |\n\nWhen `tax_identification_type` is `WIRTSCHAFTSIDENTIFIKATIONSNUMMER`, the value is `DE` followed by 9 digits, with an optional 5-digit distinguishing feature (for example `DE123456789` or `DE123456789-00001`)." }, "is_resident_in_multiple_tax_jurisdictions": { "type": "boolean", "description": "Indicates if the business is resident in multiple tax jurisdictions." }, "is_subject_to_fatca": { "type": "boolean", "description": "Indicates if the business is subject to FATCA regulations." } }, "required": [ "tax_country_code", "tax_identification_type", "tax_identification_number", "is_resident_in_multiple_tax_jurisdictions", "is_subject_to_fatca" ], "description": "Tax information of the business." }, "business_type": { "type": "string", "default": "SOLE_TRADER", "description": "Type of the business. Always `SOLE_TRADER` for sole trader businesses." }, "identification": { "type": "object", "properties": { "company_name": { "type": "string", "description": "Name of the sole trader business." }, "incorporation_date": { "type": "string", "description": "Incorporation date of the business in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" }, "legal_designation": { "type": "string", "enum": [ "EINZELUNTERNEHMER", "FREIBERUFLER", "EINGETRAGENER_KAUFMANN", "EINGETRAGENE_KAUFFRAU" ], "description": "Country specific legal designation of the sole trader business." } }, "required": [ "company_name", "legal_designation" ], "description": "Identification information of the sole trader business." }, "terms_and_conditions": { "type": "object", "properties": { "consent_document_id": { "type": "string", "format": "uuid", "description": "UUID of the consent document." }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the terms and conditions were confirmed." } }, "required": [ "consent_document_id", "confirmed_at" ], "description": "Terms and conditions agreement." }, "data_privacy_and_sharing_agreement": { "type": "object", "properties": { "consent_document_id": { "type": "string", "format": "uuid", "description": "UUID of the data privacy and sharing agreement document." }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the data privacy and sharing agreement was confirmed." } }, "required": [ "consent_document_id", "confirmed_at" ], "description": "Data privacy and sharing agreement." } }, "required": [ "contact_email", "registered_address", "business_type", "identification", "tax_information", "terms_and_conditions", "data_privacy_and_sharing_agreement" ] } ] }, "examples": { "Company": { "summary": "Company business", "value": { "contact_email": "acme.corporation@example.com", "registered_address": { "address_line1": "110", "address_line2": "Schonhauser Allee", "postcode": "101110", "city": "Berlin", "state": "BE", "country": "DE" }, "registration_number": "111221111", "tax_information": { "tax_country_code": "DE", "tax_identification_type": "STEUERNUMMER", "tax_identification_number": "12345678901", "is_resident_in_multiple_tax_jurisdictions": false, "is_subject_to_fatca": false }, "business_type": "LIMITED_LIABILITY_COMPANY", "identification": { "company_name": "Acme Corporation", "incorporation_date": "2000-10-10", "district_court": "Berlin Charlottenburg", "legal_designation": "GESELLSCHAFT_MIT_BESCHRAENKTER_HAFTUNG", "legal_entity_identifier": "213800K98H63P249S632", "common_reporting_standards": { "is_passive_non_financial_entity": false, "is_financial_institution": false } }, "terms_and_conditions": { "consent_document_id": "6a163d14-5b3d-48be-ac90-43314e96be71", "confirmed_at": "2024-10-24T14:14:22Z" }, "data_privacy_and_sharing_agreement": { "consent_document_id": "fa2227c3-2b29-47e1-84da-996d09517edc", "confirmed_at": "2024-10-24T14:16:22Z" } } }, "Sole Trader": { "summary": "Sole Trader business", "value": { "contact_email": "acme.corporation@example.com", "registered_address": { "address_line1": "110", "address_line2": "Schonhauser Allee", "postcode": "101110", "city": "Berlin", "state": "BE", "country": "DE" }, "registration_number": "111221111", "tax_information": { "tax_country_code": "DE", "tax_identification_type": "STEUERNUMMER", "tax_identification_number": "12345678901", "is_resident_in_multiple_tax_jurisdictions": false, "is_subject_to_fatca": false }, "business_type": "SOLE_TRADER", "identification": { "company_name": "Max Mustermann - Web Design", "incorporation_date": "2000-10-10", "legal_designation": "EINZELUNTERNEHMER" }, "terms_and_conditions": { "consent_document_id": "6a163d14-5b3d-48be-ac90-43314e96be71", "confirmed_at": "2024-10-24T14:14:22Z" }, "data_privacy_and_sharing_agreement": { "consent_document_id": "fa2227c3-2b29-47e1-84da-996d09517edc", "confirmed_at": "2024-10-24T14:16:22Z" } } } } } } }, "responses": { "200": { "description": "Business created.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Business - Create - Request", "description": "The business created, either a company or a sole trader.", "oneOf": [ { "type": "object", "title": "Business (Company) - Create - Response", "description": "Response schema for the create business endpoint.", "properties": { "id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "contact_email": { "type": "string", "format": "email", "description": "Contact email address of the business." }, "registered_address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, "registration_number": { "type": "string", "description": "Registration number of the business." }, "tax_information": { "type": "object", "properties": { "tax_country_code": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "tax_identification_type": { "type": "string", "enum": [ "STEUERNUMMER", "WIRTSCHAFTSIDENTIFIKATIONSNUMMER" ], "description": "Type of tax identification used by the business." }, "tax_identification_number": { "type": "string", "description": "Tax identification number of the business.\n\nWhen `tax_identification_type` is `STEUERNUMMER`, the value is 10 or 11 digits, provided either as bare digits or in a state-specific slash-grouped layout. Slashes are all-or-nothing and must appear at the grouping positions:\n\n| Format | Grouping | Example |\n| --- | --- | --- |\n| Bare digits | 10 or 11 digits | `1234567890`, `12345678901` |\n| North Rhine-Westphalia | 3/4/4 | `133/8150/8159` |\n| Bavaria | 3/3/5 | `181/815/08155` |\n| Standard 10-digit | 2/3/5 | `24/815/08151` |\n| Alternative 10-digit (Berlin, Bremen, Lower Saxony) | 3/3/4 | `181/815/0815` |\n\nWhen `tax_identification_type` is `WIRTSCHAFTSIDENTIFIKATIONSNUMMER`, the value is `DE` followed by 9 digits, with an optional 5-digit distinguishing feature (for example `DE123456789` or `DE123456789-00001`)." }, "is_resident_in_multiple_tax_jurisdictions": { "type": "boolean", "description": "Indicates if the business is resident in multiple tax jurisdictions." }, "is_subject_to_fatca": { "type": "boolean", "description": "Indicates if the business is subject to FATCA regulations." } }, "required": [ "tax_country_code", "tax_identification_type", "tax_identification_number", "is_resident_in_multiple_tax_jurisdictions", "is_subject_to_fatca" ], "description": "Tax information of the business." }, "business_type": { "default": "LIMITED_LIABILITY_COMPANY", "description": "Type of the business." }, "identification": { "type": "object", "properties": { "company_name": { "type": "string", "description": "Name of the company." }, "incorporation_date": { "type": "string", "description": "Incorporation date of the business in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" }, "district_court": { "type": "string", "minLength": 1, "maxLength": 40, "description": "District court where the company is registered." }, "legal_designation": { "type": "string", "enum": [ "GESELLSCHAFT_MIT_BESCHRAENKTER_HAFTUNG", "UNTERNEHMERGESELLSCHAFT", "AKTIENGESELLSCHAFT" ], "description": "Country specific legal designation of the company.\nNote: `AKTIENGESELLSCHAFT` businesses cannot be created via the API; please contact Upvest support before onboarding such a business." }, "legal_entity_identifier": { "type": "string", "pattern": "^[A-Z0-9]{18}[0-9]{2}$", "description": "Legal Entity Identifier (LEI) of the company. A 20-character alphanumeric code as defined by [ISO 17442](https://en.wikipedia.org/wiki/Legal_Entity_Identifier)." }, "common_reporting_standards": { "type": "object", "properties": { "is_passive_non_financial_entity": { "type": "boolean", "description": "Indicates if the company is a passive non-financial entity." }, "is_financial_institution": { "type": "boolean", "description": "Indicates if the company is a financial institution." } }, "required": [ "is_passive_non_financial_entity", "is_financial_institution" ], "description": "Common reporting standards information." } }, "required": [ "company_name", "incorporation_date", "district_court", "legal_designation", "common_reporting_standards" ], "description": "Identification information of the business." }, "terms_and_conditions": { "type": "object", "properties": { "consent_document_id": { "type": "string", "format": "uuid", "description": "UUID of the consent document." }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the terms and conditions were confirmed." } }, "required": [ "consent_document_id", "confirmed_at" ], "description": "Terms and conditions agreement." }, "data_privacy_and_sharing_agreement": { "type": "object", "properties": { "consent_document_id": { "type": "string", "format": "uuid", "description": "UUID of the data privacy and sharing agreement document." }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the data privacy and sharing agreement was confirmed." } }, "required": [ "consent_document_id", "confirmed_at" ], "description": "Data privacy and sharing agreement." }, "status": { "enum": [ "ACTIVE", "INACTIVE", "OFFBOARDING", "OFFBOARDED" ], "description": "Status of the business.\n* ACTIVE - \n* INACTIVE - \n* OFFBOARDING - \n* OFFBOARDED - " } } }, { "type": "object", "title": "Business (Sole Trader) - Create - Response", "description": "Response schema for the create business endpoint.", "properties": { "id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "contact_email": { "type": "string", "format": "email", "description": "Contact email address of the business." }, "registered_address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, "registration_number": { "type": "string", "description": "Registration number of the business." }, "tax_information": { "type": "object", "properties": { "tax_country_code": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "tax_identification_type": { "type": "string", "enum": [ "STEUERNUMMER", "WIRTSCHAFTSIDENTIFIKATIONSNUMMER" ], "description": "Type of tax identification used by the business." }, "tax_identification_number": { "type": "string", "description": "Tax identification number of the business.\n\nWhen `tax_identification_type` is `STEUERNUMMER`, the value is 10 or 11 digits, provided either as bare digits or in a state-specific slash-grouped layout. Slashes are all-or-nothing and must appear at the grouping positions:\n\n| Format | Grouping | Example |\n| --- | --- | --- |\n| Bare digits | 10 or 11 digits | `1234567890`, `12345678901` |\n| North Rhine-Westphalia | 3/4/4 | `133/8150/8159` |\n| Bavaria | 3/3/5 | `181/815/08155` |\n| Standard 10-digit | 2/3/5 | `24/815/08151` |\n| Alternative 10-digit (Berlin, Bremen, Lower Saxony) | 3/3/4 | `181/815/0815` |\n\nWhen `tax_identification_type` is `WIRTSCHAFTSIDENTIFIKATIONSNUMMER`, the value is `DE` followed by 9 digits, with an optional 5-digit distinguishing feature (for example `DE123456789` or `DE123456789-00001`)." }, "is_resident_in_multiple_tax_jurisdictions": { "type": "boolean", "description": "Indicates if the business is resident in multiple tax jurisdictions." }, "is_subject_to_fatca": { "type": "boolean", "description": "Indicates if the business is subject to FATCA regulations." } }, "required": [ "tax_country_code", "tax_identification_type", "tax_identification_number", "is_resident_in_multiple_tax_jurisdictions", "is_subject_to_fatca" ], "description": "Tax information of the business." }, "business_type": { "type": "string", "default": "SOLE_TRADER", "description": "Type of the business. Always `SOLE_TRADER` for sole trader businesses." }, "identification": { "type": "object", "properties": { "company_name": { "type": "string", "description": "Name of the sole trader business." }, "incorporation_date": { "type": "string", "description": "Incorporation date of the business in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" }, "legal_designation": { "type": "string", "enum": [ "EINZELUNTERNEHMER", "FREIBERUFLER", "EINGETRAGENER_KAUFMANN", "EINGETRAGENE_KAUFFRAU" ], "description": "Country specific legal designation of the sole trader business." } }, "required": [ "company_name", "legal_designation" ], "description": "Identification information of the sole trader business." }, "terms_and_conditions": { "type": "object", "properties": { "consent_document_id": { "type": "string", "format": "uuid", "description": "UUID of the consent document." }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the terms and conditions were confirmed." } }, "required": [ "consent_document_id", "confirmed_at" ], "description": "Terms and conditions agreement." }, "data_privacy_and_sharing_agreement": { "type": "object", "properties": { "consent_document_id": { "type": "string", "format": "uuid", "description": "UUID of the data privacy and sharing agreement document." }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the data privacy and sharing agreement was confirmed." } }, "required": [ "consent_document_id", "confirmed_at" ], "description": "Data privacy and sharing agreement." }, "status": { "enum": [ "ACTIVE", "INACTIVE", "OFFBOARDING", "OFFBOARDED" ], "description": "Status of the business.\n* ACTIVE - \n* INACTIVE - \n* OFFBOARDING - \n* OFFBOARDED - " } } } ] }, "examples": { "Company": { "summary": "Company business", "value": { "id": "a9a72268-4f3c-4de2-abb9-a553a3bb7608", "created_at": "2024-10-24T14:14:22Z", "updated_at": "2024-10-24T14:14:22Z", "contact_email": "acme.corporation@example.com", "registered_address": { "address_line1": "110", "address_line2": "Schonhauser Allee", "postcode": "101110", "city": "Berlin", "state": "BE", "country": "DE" }, "registration_number": "111221111", "tax_information": { "tax_country_code": "DE", "tax_identification_type": "STEUERNUMMER", "tax_identification_number": "12345678901", "is_resident_in_multiple_tax_jurisdictions": false, "is_subject_to_fatca": false }, "business_type": "LIMITED_LIABILITY_COMPANY", "identification": { "company_name": "Acme Corporation", "incorporation_date": "2000-10-10", "district_court": "Berlin Charlottenburg", "legal_designation": "GESELLSCHAFT_MIT_BESCHRAENKTER_HAFTUNG", "legal_entity_identifier": "213800K98H63P249S632", "common_reporting_standards": { "is_passive_non_financial_entity": false, "is_financial_institution": false } }, "terms_and_conditions": { "consent_document_id": "6a163d14-5b3d-48be-ac90-43314e96be71", "confirmed_at": "2024-10-24T14:14:22Z" }, "data_privacy_and_sharing_agreement": { "consent_document_id": "fa2227c3-2b29-47e1-84da-996d09517edc", "confirmed_at": "2024-10-24T14:16:22Z" }, "status": "ACTIVE" } }, "Sole Trader": { "summary": "Sole Trader business", "value": { "id": "a9a72268-4f3c-4de2-abb9-a553a3bb7608", "created_at": "2024-10-24T14:14:22Z", "updated_at": "2024-10-24T14:14:22Z", "contact_email": "acme.corporation@example.com", "registered_address": { "address_line1": "110", "address_line2": "Schonhauser Allee", "postcode": "101110", "city": "Berlin", "state": "BE", "country": "DE" }, "registration_number": "111221111", "tax_information": { "tax_country_code": "DE", "tax_identification_type": "STEUERNUMMER", "tax_identification_number": "12345678901", "is_resident_in_multiple_tax_jurisdictions": false, "is_subject_to_fatca": false }, "business_type": "SOLE_TRADER", "identification": { "company_name": "Max Mustermann - Web Design", "incorporation_date": "2000-10-10", "legal_designation": "EINZELUNTERNEHMER" }, "terms_and_conditions": { "consent_document_id": "6a163d14-5b3d-48be-ac90-43314e96be71", "confirmed_at": "2024-10-24T14:14:22Z" }, "data_privacy_and_sharing_agreement": { "consent_document_id": "fa2227c3-2b29-47e1-84da-996d09517edc", "confirmed_at": "2024-10-24T14:16:22Z" }, "status": "ACTIVE" } } } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/businesses/{business_id}": { "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "The unique identifier of the business. Universally Unique Identifier (UUID).", "schema": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_business", "summary": "Get a business by ID", "description": "Returns the business identified by `business_id`, including profile and status details", "tags": [ "Businesses" ], "security": [ { "oauth-client-credentials": [ "businesses:read", "businesses:admin" ] } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "description": "The requested business, either a company or a sole trader.", "oneOf": [ { "type": "object", "description": "Schema for business company information.", "properties": { "id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "contact_email": { "type": "string", "format": "email", "description": "Contact email address of the business." }, "registered_address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, "registration_number": { "type": "string", "description": "Registration number of the business." }, "tax_information": { "type": "object", "properties": { "tax_country_code": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "tax_identification_type": { "type": "string", "enum": [ "STEUERNUMMER", "WIRTSCHAFTSIDENTIFIKATIONSNUMMER" ], "description": "Type of tax identification used by the business." }, "tax_identification_number": { "type": "string", "description": "Tax identification number of the business.\n\nWhen `tax_identification_type` is `STEUERNUMMER`, the value is 10 or 11 digits, provided either as bare digits or in a state-specific slash-grouped layout. Slashes are all-or-nothing and must appear at the grouping positions:\n\n| Format | Grouping | Example |\n| --- | --- | --- |\n| Bare digits | 10 or 11 digits | `1234567890`, `12345678901` |\n| North Rhine-Westphalia | 3/4/4 | `133/8150/8159` |\n| Bavaria | 3/3/5 | `181/815/08155` |\n| Standard 10-digit | 2/3/5 | `24/815/08151` |\n| Alternative 10-digit (Berlin, Bremen, Lower Saxony) | 3/3/4 | `181/815/0815` |\n\nWhen `tax_identification_type` is `WIRTSCHAFTSIDENTIFIKATIONSNUMMER`, the value is `DE` followed by 9 digits, with an optional 5-digit distinguishing feature (for example `DE123456789` or `DE123456789-00001`)." }, "is_resident_in_multiple_tax_jurisdictions": { "type": "boolean", "description": "Indicates if the business is resident in multiple tax jurisdictions." }, "is_subject_to_fatca": { "type": "boolean", "description": "Indicates if the business is subject to FATCA regulations." } }, "required": [ "tax_country_code", "tax_identification_type", "tax_identification_number", "is_resident_in_multiple_tax_jurisdictions", "is_subject_to_fatca" ], "description": "Tax information of the business." }, "business_type": { "default": "LIMITED_LIABILITY_COMPANY", "description": "Type of the business." }, "identification": { "type": "object", "properties": { "company_name": { "type": "string", "description": "Name of the company." }, "incorporation_date": { "type": "string", "description": "Incorporation date of the business in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" }, "district_court": { "type": "string", "minLength": 1, "maxLength": 40, "description": "District court where the company is registered." }, "legal_designation": { "type": "string", "enum": [ "GESELLSCHAFT_MIT_BESCHRAENKTER_HAFTUNG", "UNTERNEHMERGESELLSCHAFT", "AKTIENGESELLSCHAFT" ], "description": "Country specific legal designation of the company.\nNote: `AKTIENGESELLSCHAFT` businesses cannot be created via the API; please contact Upvest support before onboarding such a business." }, "legal_entity_identifier": { "type": "string", "pattern": "^[A-Z0-9]{18}[0-9]{2}$", "description": "Legal Entity Identifier (LEI) of the company. A 20-character alphanumeric code as defined by [ISO 17442](https://en.wikipedia.org/wiki/Legal_Entity_Identifier)." }, "common_reporting_standards": { "type": "object", "properties": { "is_passive_non_financial_entity": { "type": "boolean", "description": "Indicates if the company is a passive non-financial entity." }, "is_financial_institution": { "type": "boolean", "description": "Indicates if the company is a financial institution." } }, "required": [ "is_passive_non_financial_entity", "is_financial_institution" ], "description": "Common reporting standards information." } }, "required": [ "company_name", "incorporation_date", "district_court", "legal_designation", "common_reporting_standards" ], "description": "Identification information of the business." }, "terms_and_conditions": { "type": "object", "properties": { "consent_document_id": { "type": "string", "format": "uuid", "description": "UUID of the consent document." }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the terms and conditions were confirmed." } }, "required": [ "consent_document_id", "confirmed_at" ], "description": "Terms and conditions agreement." }, "data_privacy_and_sharing_agreement": { "type": "object", "properties": { "consent_document_id": { "type": "string", "format": "uuid", "description": "UUID of the data privacy and sharing agreement document." }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the data privacy and sharing agreement was confirmed." } }, "required": [ "consent_document_id", "confirmed_at" ], "description": "Data privacy and sharing agreement." }, "status": { "enum": [ "ACTIVE", "INACTIVE", "OFFBOARDING", "OFFBOARDED" ], "description": "Status of the business.\n* ACTIVE - \n* INACTIVE - \n* OFFBOARDING - \n* OFFBOARDED - " } }, "required": [ "id", "contact_email", "registered_address", "registration_number", "tax_information", "business_type", "identification", "terms_and_conditions", "data_privacy_and_sharing_agreement", "status", "created_at", "updated_at" ], "additionalProperties": false }, { "type": "object", "description": "Schema for business company information.", "properties": { "id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "contact_email": { "type": "string", "format": "email", "description": "Contact email address of the business." }, "registered_address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, "registration_number": { "type": "string", "description": "Registration number of the business." }, "tax_information": { "type": "object", "properties": { "tax_country_code": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "tax_identification_type": { "type": "string", "enum": [ "STEUERNUMMER", "WIRTSCHAFTSIDENTIFIKATIONSNUMMER" ], "description": "Type of tax identification used by the business." }, "tax_identification_number": { "type": "string", "description": "Tax identification number of the business.\n\nWhen `tax_identification_type` is `STEUERNUMMER`, the value is 10 or 11 digits, provided either as bare digits or in a state-specific slash-grouped layout. Slashes are all-or-nothing and must appear at the grouping positions:\n\n| Format | Grouping | Example |\n| --- | --- | --- |\n| Bare digits | 10 or 11 digits | `1234567890`, `12345678901` |\n| North Rhine-Westphalia | 3/4/4 | `133/8150/8159` |\n| Bavaria | 3/3/5 | `181/815/08155` |\n| Standard 10-digit | 2/3/5 | `24/815/08151` |\n| Alternative 10-digit (Berlin, Bremen, Lower Saxony) | 3/3/4 | `181/815/0815` |\n\nWhen `tax_identification_type` is `WIRTSCHAFTSIDENTIFIKATIONSNUMMER`, the value is `DE` followed by 9 digits, with an optional 5-digit distinguishing feature (for example `DE123456789` or `DE123456789-00001`)." }, "is_resident_in_multiple_tax_jurisdictions": { "type": "boolean", "description": "Indicates if the business is resident in multiple tax jurisdictions." }, "is_subject_to_fatca": { "type": "boolean", "description": "Indicates if the business is subject to FATCA regulations." } }, "required": [ "tax_country_code", "tax_identification_type", "tax_identification_number", "is_resident_in_multiple_tax_jurisdictions", "is_subject_to_fatca" ], "description": "Tax information of the business." }, "business_type": { "type": "string", "default": "SOLE_TRADER", "description": "Type of the business. Always `SOLE_TRADER` for sole trader businesses." }, "identification": { "type": "object", "properties": { "company_name": { "type": "string", "description": "Name of the sole trader business." }, "incorporation_date": { "type": "string", "description": "Incorporation date of the business in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" }, "legal_designation": { "type": "string", "enum": [ "EINZELUNTERNEHMER", "FREIBERUFLER", "EINGETRAGENER_KAUFMANN", "EINGETRAGENE_KAUFFRAU" ], "description": "Country specific legal designation of the sole trader business." } }, "required": [ "company_name", "legal_designation" ], "description": "Identification information of the sole trader business." }, "terms_and_conditions": { "type": "object", "properties": { "consent_document_id": { "type": "string", "format": "uuid", "description": "UUID of the consent document." }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the terms and conditions were confirmed." } }, "required": [ "consent_document_id", "confirmed_at" ], "description": "Terms and conditions agreement." }, "data_privacy_and_sharing_agreement": { "type": "object", "properties": { "consent_document_id": { "type": "string", "format": "uuid", "description": "UUID of the data privacy and sharing agreement document." }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the data privacy and sharing agreement was confirmed." } }, "required": [ "consent_document_id", "confirmed_at" ], "description": "Data privacy and sharing agreement." }, "status": { "enum": [ "ACTIVE", "INACTIVE", "OFFBOARDING", "OFFBOARDED" ], "description": "Status of the business.\n* ACTIVE - \n* INACTIVE - \n* OFFBOARDING - \n* OFFBOARDED - " } }, "required": [ "id", "created_at", "updated_at", "contact_email", "registered_address", "tax_information", "business_type", "identification", "terms_and_conditions", "data_privacy_and_sharing_agreement", "status" ], "additionalProperties": false } ] }, "examples": { "Company": { "summary": "Company business", "value": { "id": "a9a72268-4f3c-4de2-abb9-a553a3bb7608", "created_at": "2024-10-24T14:14:22Z", "updated_at": "2024-10-24T14:14:22Z", "contact_email": "acme.corporation@example.com", "registered_address": { "address_line1": "110", "address_line2": "Schonhauser Allee", "postcode": "101110", "city": "Berlin", "state": "BE", "country": "DE" }, "registration_number": "111221111", "tax_information": { "tax_country_code": "DE", "tax_identification_type": "STEUERNUMMER", "tax_identification_number": "12345678901", "is_resident_in_multiple_tax_jurisdictions": false, "is_subject_to_fatca": false }, "business_type": "LIMITED_LIABILITY_COMPANY", "identification": { "company_name": "Acme Corporation", "incorporation_date": "2000-01-01", "district_court": "Berlin Charlottenburg", "legal_designation": "GESELLSCHAFT_MIT_BESCHRAENKTER_HAFTUNG", "legal_entity_identifier": "213800K98H63P249S632", "common_reporting_standards": { "is_passive_non_financial_entity": false, "is_financial_institution": false } }, "terms_and_conditions": { "consent_document_id": "6a163d14-5b3d-48be-ac90-43314e96be71", "confirmed_at": "2024-10-24T14:14:22Z" }, "data_privacy_and_sharing_agreement": { "consent_document_id": "fa2227c3-2b29-47e1-84da-996d09517edc", "confirmed_at": "2024-10-24T14:16:22Z" }, "status": "ACTIVE" } }, "Sole Trader": { "summary": "Sole Trader business", "value": { "id": "a9a72268-4f3c-4de2-abb9-a553a3bb7608", "created_at": "2024-10-24T14:14:22Z", "updated_at": "2024-10-24T14:14:22Z", "contact_email": "acme.corporation@example.com", "registered_address": { "address_line1": "110", "address_line2": "Schonhauser Allee", "postcode": "101110", "city": "Berlin", "state": "BE", "country": "DE" }, "registration_number": "111221111", "tax_information": { "tax_country_code": "DE", "tax_identification_type": "STEUERNUMMER", "tax_identification_number": "12345678901", "is_resident_in_multiple_tax_jurisdictions": false, "is_subject_to_fatca": false }, "business_type": "SOLE_TRADER", "identification": { "company_name": "Max Mustermann - Web Design", "incorporation_date": "2000-10-10", "legal_designation": "EINZELUNTERNEHMER" }, "terms_and_conditions": { "consent_document_id": "6a163d14-5b3d-48be-ac90-43314e96be71", "confirmed_at": "2024-10-24T14:14:22Z" }, "data_privacy_and_sharing_agreement": { "consent_document_id": "fa2227c3-2b29-47e1-84da-996d09517edc", "confirmed_at": "2024-10-24T14:16:22Z" }, "status": "ACTIVE" } } } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/businesses/{business_id}/data_change_requests": { "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "The unique identifier of the business. Universally Unique Identifier (UUID).", "schema": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "post": { "operationId": "business_data_change", "summary": "Change business data", "description": "Requests a data change for a business specified by ID.", "tags": [ "Businesses" ], "security": [ { "oauth-client-credentials": [ "businesses:admin" ] } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Request payload for changing business data. Currently supports updating the contact email address.", "anyOf": [ { "title": "Business (Company) - Update - Request", "type": "object", "description": "Request payload for updating a company business. Currently only the contact email address can be changed.", "properties": { "contact_email": { "type": "string", "format": "email", "description": "Contact email address of the business." } } } ] }, "examples": { "Contact Email": { "summary": "Contact Email", "value": { "contact_email": "acme.corporation@example.com" } } } } } }, "responses": { "202": { "description": "The request has been successfully accepted and will be processed asynchronously.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/businesses/{business_id}/checks": { "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "The unique identifier of the business. Universally Unique Identifier (UUID).", "schema": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_business_checks", "summary": "List checks for a business", "description": "Lists all checks for a business specified by ID.", "tags": [ "Business Checks" ], "security": [ { "oauth-client-credentials": [ "checks:read", "checks:admin" ] } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Business Check - List - Response", "type": "object", "description": "List of business checks.", "properties": { "data": { "type": "array", "description": "List of checks conducted for the business", "items": { "title": "Business Check", "description": "A check conducted for a business, either a KYB check or a self-assessment.", "oneOf": [ { "title": "Business Check - KYB", "type": "object", "description": "A Know Your Business (KYB) check for a business, recording confirmation timestamps and a link to the submitted documents.", "properties": { "id": { "title": "Business Check unique identifier", "type": "string", "description": "Business Check unique identifier.", "format": "uuid" }, "business_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "type": { "type": "string", "default": "KYB", "description": "The type of check must be “KYB”." }, "originally_confirmed_at": { "type": "string", "format": "date-time", "description": "The date and time when the check was first confirmed. When the check has only been confirmed once, this value is the same as check_confirmed_at. When renewing KYB check, this value remains the same as when the check was first confirmed." }, "check_confirmed_at": { "type": "string", "format": "date-time", "description": "The date and time when the check was latest confirmed" }, "status": { "type": "string", "description": "Final status of the business check.\n* IN_PROGRESS - Check is in progress\n* PASSED - Check passed\n* FAILED - Check failed", "enum": [ "IN_PROGRESS", "PASSED", "FAILED" ] }, "data_download_link": { "type": "string", "format": "uri", "description": "Link to download the document bundle submitted for the KYB check" }, "document_type": { "type": "string", "default": "KYB_DOCUMENTS", "description": "Type of the document bundle. Always `KYB_DOCUMENTS`" } }, "required": [ "id", "business_id", "type", "originally_confirmed_at", "check_confirmed_at", "status", "data_download_link", "document_type" ] }, { "title": "Business Check - Business Self Assessment", "type": "object", "description": "The Business Self Assessment check captures information about the business's activities, financials, and purpose of the business relationship for risk scoring.", "properties": { "id": { "title": "Business Check unique identifier", "type": "string", "description": "Business Check unique identifier.", "format": "uuid" }, "business_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "type": { "type": "string", "default": "BUSINESS_SELF_ASSESSMENT", "description": "The type of check must be \"BUSINESS_SELF_ASSESSMENT\"." }, "check_confirmed_at": { "type": "string", "format": "date-time", "description": "The date and time when the self assessment check was confirmed." }, "status": { "type": "string", "description": "Final status of the business check.\n* IN_PROGRESS - Check is in progress\n* PASSED - Check passed\n* FAILED - Check failed", "enum": [ "IN_PROGRESS", "PASSED", "FAILED" ] }, "business_industry": { "title": "Business Industry", "type": "string", "description": "The business industry classification.", "enum": [ "ACCOMMODATION_AND_HOSPITALITY", "ACCOMMODATION_AND_HOSPITALITY_TIMESHARING", "ADMIN_AND_SUPPORT_SERVICES", "ADMIN_AND_SUPPORT_SERVICES_CLEANING_AND_FACILITIES", "ADMIN_AND_SUPPORT_SERVICES_SECURITY_AND_INVESTIGATION", "ADMIN_AND_SUPPORT_SERVICES_SPECIFIC_SECTORS", "AGRICULTURE_FORESTRY_AND_FISHING", "CONSTRUCTION", "EDUCATION", "EDUCATION_HIGHER_EDUCATION", "ENTERTAINMENT_ARTS_AND_RECREATION", "ENTERTAINMENT_ARTS_AND_RECREATION_NATURE_AND_ZOOS", "ENTERTAINMENT_ARTS_AND_RECREATION_SPECIFIC_SECTORS", "EXTRATERRITORIAL_AND_HOUSEHOLD_ACTIVITIES", "FINANCIAL_SERVICES", "FOOD_AND_BEVERAGE_SERVICES", "HEALTHCARE", "HEALTHCARE_COUNSELLING_AND_SOCIAL_SERVICES", "INFORMATION_TECHNOLOGY_AND_MEDIA", "INFORMATION_TECHNOLOGY_AND_MEDIA_ONLINE_GAMING", "INFORMATION_TECHNOLOGY_AND_MEDIA_PRINT_PUBLISHING", "INFORMATION_TECHNOLOGY_AND_MEDIA_TELECOMMUNICATIONS", "MANUFACTURING", "MANUFACTURING_PHARMACEUTICALS", "MANUFACTURING_PRECIOUS_METALS_AND_JEWELLERY", "MANUFACTURING_WEAPONS_AND_HAZARDOUS", "MINING_AND_QUARRYING", "PERSONAL_AND_OTHER_SERVICES", "PERSONAL_AND_OTHER_SERVICES_ADULT_AND_WELLNESS", "PERSONAL_AND_OTHER_SERVICES_NONPROFIT_AND_MEMBERSHIP_ORGANISATIONS", "PROFESSIONAL_AND_TECHNICAL_SERVICES", "PROFESSIONAL_AND_TECHNICAL_SERVICES_LEGAL_AND_FIDUCIARY", "PROFESSIONAL_AND_TECHNICAL_SERVICES_UNREGULATED", "PUBLIC_ADMINISTRATION", "PUBLIC_ADMINISTRATION_JUDICIAL", "REAL_ESTATE", "REAL_ESTATE_AGENCY_AND_BROKERAGE", "RETAIL_TRADE", "RETAIL_TRADE_SPECIALITY", "RETAIL_TRADE_SPECIFIC_SECTORS", "TRANSPORTATION_AND_LOGISTICS", "TRANSPORTATION_AND_LOGISTICS_CRUISE_LINES", "TRANSPORTATION_AND_LOGISTICS_RAIL_AND_STORAGE", "UTILITIES_AND_ENERGY", "WHOLESALE_TRADE", "WHOLESALE_TRADE_INDUSTRIAL", "WHOLESALE_TRADE_LUXURY_AND_COLLECTIBLES", "WHOLESALE_TRADE_PETROLEUM_AND_CHEMICALS" ] }, "purpose_of_business_relationship": { "title": "Purpose of Business Relationship", "type": "string", "description": "The purpose of the business relationship.", "enum": [ "WEALTH_GROWTH", "TREASURY_LIQUIDITY_MANAGEMENT", "HEDGING_RISK_MANAGEMENT", "EMPLOYEE_BENEFIT_FUNDING", "STRATEGIC_INVESTMENT" ] }, "primary_countries_of_activity": { "type": "array", "description": "List of primary countries where the business operates. ISO 3166-1 alpha-2 country codes.", "items": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "minItems": 1 }, "annual_revenue": { "title": "Monetary Range", "type": "object", "description": "A monetary range defined by a lower bound and an optional upper bound.", "properties": { "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "lower_bound": { "type": "number", "description": "The lower bound of the monetary range.", "minimum": 0 }, "upper_bound": { "type": "number", "description": "The upper bound of the monetary range.", "minimum": 0 } }, "required": [ "currency", "lower_bound" ], "additionalProperties": false }, "expected_volume_of_investment": { "title": "Monetary Range", "type": "object", "description": "A monetary range defined by a lower bound and an optional upper bound.", "properties": { "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "lower_bound": { "type": "number", "description": "The lower bound of the monetary range.", "minimum": 0 }, "upper_bound": { "type": "number", "description": "The upper bound of the monetary range.", "minimum": 0 } }, "required": [ "currency", "lower_bound" ], "additionalProperties": false }, "total_asset_value": { "title": "Monetary Range", "type": "object", "description": "A monetary range defined by a lower bound and an optional upper bound.", "properties": { "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "lower_bound": { "type": "number", "description": "The lower bound of the monetary range.", "minimum": 0 }, "upper_bound": { "type": "number", "description": "The upper bound of the monetary range.", "minimum": 0 } }, "required": [ "currency", "lower_bound" ], "additionalProperties": false } }, "required": [ "id", "business_id", "type", "check_confirmed_at", "status", "business_industry", "purpose_of_business_relationship", "primary_countries_of_activity", "annual_revenue", "expected_volume_of_investment", "total_asset_value" ], "additionalProperties": false } ] } } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": [ { "id": "d3f8c9a1-4b2e-4c8e-9f3e-2a5b7e6d9c1f", "business_id": "e7a1c2d4-5f6b-7a8e-9b0c-1d2e3f4a5b6c", "type": "KYB", "originally_confirmed_at": "2020-08-24T14:15:22Z", "check_confirmed_at": "2020-08-24T14:15:22Z", "data_download_link": "https://bucket.customer.com/por/kyb.zip", "document_type": "KYB_DOCUMENTS", "status": "PASSED" } ] } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "post": { "operationId": "create_business_check", "summary": "Create a new check for a business", "description": "Creates a new check for a business specified by ID.", "tags": [ "Business Checks" ], "security": [ { "oauth-client-credentials": [ "checks:admin" ] } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Business Check - Create - Request", "description": "Request payload for creating a business check, either a KYB check or a self-assessment.", "oneOf": [ { "title": "Business Check - Know Your Business - Create - Request", "type": "object", "description": "The KYB (Know Your Business) check is completed by the client sharing the valid and relevant KYB data for the business.", "properties": { "type": { "type": "string", "default": "KYB", "description": "The type of check must be “KYB”." }, "originally_confirmed_at": { "type": "string", "format": "date-time", "description": "The date and time when the check was first confirmed. When the check has only been confirmed once, this value is the same as check_confirmed_at. When renewing KYB check, this value remains the same as when the check was first confirmed." }, "check_confirmed_at": { "type": "string", "format": "date-time", "description": "The date and time when the check was latest confirmed" }, "data_download_link": { "type": "string", "format": "uri", "description": "Link to download the document bundle submitted for the KYB check" } }, "required": [ "type", "originally_confirmed_at", "check_confirmed_at", "data_download_link" ], "additionalProperties": false }, { "title": "Business Check - Business Self Assessment - Create - Request", "type": "object", "description": "The Business Self Assessment check is completed by the client providing self-assessment information about the business for risk scoring purposes.", "properties": { "type": { "type": "string", "default": "BUSINESS_SELF_ASSESSMENT", "description": "The type of check must be \"BUSINESS_SELF_ASSESSMENT\"." }, "check_confirmed_at": { "type": "string", "format": "date-time", "description": "The date and time when the self assessment check was confirmed." }, "business_industry": { "title": "Business Industry", "type": "string", "description": "The business industry classification.", "enum": [ "ACCOMMODATION_AND_HOSPITALITY", "ACCOMMODATION_AND_HOSPITALITY_TIMESHARING", "ADMIN_AND_SUPPORT_SERVICES", "ADMIN_AND_SUPPORT_SERVICES_CLEANING_AND_FACILITIES", "ADMIN_AND_SUPPORT_SERVICES_SECURITY_AND_INVESTIGATION", "ADMIN_AND_SUPPORT_SERVICES_SPECIFIC_SECTORS", "AGRICULTURE_FORESTRY_AND_FISHING", "CONSTRUCTION", "EDUCATION", "EDUCATION_HIGHER_EDUCATION", "ENTERTAINMENT_ARTS_AND_RECREATION", "ENTERTAINMENT_ARTS_AND_RECREATION_NATURE_AND_ZOOS", "ENTERTAINMENT_ARTS_AND_RECREATION_SPECIFIC_SECTORS", "EXTRATERRITORIAL_AND_HOUSEHOLD_ACTIVITIES", "FINANCIAL_SERVICES", "FOOD_AND_BEVERAGE_SERVICES", "HEALTHCARE", "HEALTHCARE_COUNSELLING_AND_SOCIAL_SERVICES", "INFORMATION_TECHNOLOGY_AND_MEDIA", "INFORMATION_TECHNOLOGY_AND_MEDIA_ONLINE_GAMING", "INFORMATION_TECHNOLOGY_AND_MEDIA_PRINT_PUBLISHING", "INFORMATION_TECHNOLOGY_AND_MEDIA_TELECOMMUNICATIONS", "MANUFACTURING", "MANUFACTURING_PHARMACEUTICALS", "MANUFACTURING_PRECIOUS_METALS_AND_JEWELLERY", "MANUFACTURING_WEAPONS_AND_HAZARDOUS", "MINING_AND_QUARRYING", "PERSONAL_AND_OTHER_SERVICES", "PERSONAL_AND_OTHER_SERVICES_ADULT_AND_WELLNESS", "PERSONAL_AND_OTHER_SERVICES_NONPROFIT_AND_MEMBERSHIP_ORGANISATIONS", "PROFESSIONAL_AND_TECHNICAL_SERVICES", "PROFESSIONAL_AND_TECHNICAL_SERVICES_LEGAL_AND_FIDUCIARY", "PROFESSIONAL_AND_TECHNICAL_SERVICES_UNREGULATED", "PUBLIC_ADMINISTRATION", "PUBLIC_ADMINISTRATION_JUDICIAL", "REAL_ESTATE", "REAL_ESTATE_AGENCY_AND_BROKERAGE", "RETAIL_TRADE", "RETAIL_TRADE_SPECIALITY", "RETAIL_TRADE_SPECIFIC_SECTORS", "TRANSPORTATION_AND_LOGISTICS", "TRANSPORTATION_AND_LOGISTICS_CRUISE_LINES", "TRANSPORTATION_AND_LOGISTICS_RAIL_AND_STORAGE", "UTILITIES_AND_ENERGY", "WHOLESALE_TRADE", "WHOLESALE_TRADE_INDUSTRIAL", "WHOLESALE_TRADE_LUXURY_AND_COLLECTIBLES", "WHOLESALE_TRADE_PETROLEUM_AND_CHEMICALS" ] }, "purpose_of_business_relationship": { "title": "Purpose of Business Relationship", "type": "string", "description": "The purpose of the business relationship.", "enum": [ "WEALTH_GROWTH", "TREASURY_LIQUIDITY_MANAGEMENT", "HEDGING_RISK_MANAGEMENT", "EMPLOYEE_BENEFIT_FUNDING", "STRATEGIC_INVESTMENT" ] }, "primary_countries_of_activity": { "type": "array", "description": "List of primary countries where the business operates. ISO 3166-1 alpha-2 country codes.", "items": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "minItems": 1 }, "annual_revenue": { "title": "Monetary Range", "type": "object", "description": "A monetary range defined by a lower bound and an optional upper bound.", "properties": { "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "lower_bound": { "type": "number", "description": "The lower bound of the monetary range.", "minimum": 0 }, "upper_bound": { "type": "number", "description": "The upper bound of the monetary range.", "minimum": 0 } }, "required": [ "currency", "lower_bound" ], "additionalProperties": false }, "expected_volume_of_investment": { "title": "Monetary Range", "type": "object", "description": "A monetary range defined by a lower bound and an optional upper bound.", "properties": { "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "lower_bound": { "type": "number", "description": "The lower bound of the monetary range.", "minimum": 0 }, "upper_bound": { "type": "number", "description": "The upper bound of the monetary range.", "minimum": 0 } }, "required": [ "currency", "lower_bound" ], "additionalProperties": false }, "total_asset_value": { "title": "Monetary Range", "type": "object", "description": "A monetary range defined by a lower bound and an optional upper bound.", "properties": { "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "lower_bound": { "type": "number", "description": "The lower bound of the monetary range.", "minimum": 0 }, "upper_bound": { "type": "number", "description": "The upper bound of the monetary range.", "minimum": 0 } }, "required": [ "currency", "lower_bound" ], "additionalProperties": false } }, "required": [ "type", "check_confirmed_at", "business_industry", "purpose_of_business_relationship", "primary_countries_of_activity", "annual_revenue", "expected_volume_of_investment", "total_asset_value" ], "additionalProperties": false } ] }, "examples": { "KYB": { "summary": "KYB check", "value": { "type": "KYB", "originally_confirmed_at": "2020-08-24T14:15:22Z", "check_confirmed_at": "2024-08-24T14:15:22Z", "data_download_link": "https://bucket.customer.com/por/kyb.zip" } }, "BUSINESS_SELF_ASSESSMENT": { "summary": "Business Self Assessment check", "value": { "type": "BUSINESS_SELF_ASSESSMENT", "check_confirmed_at": "2021-08-24T14:15:22Z", "business_industry": "MANUFACTURING", "purpose_of_business_relationship": "WEALTH_GROWTH", "primary_countries_of_activity": [ "DE", "FR" ], "annual_revenue": { "currency": "EUR", "lower_bound": 0, "upper_bound": 50000 }, "expected_volume_of_investment": { "currency": "EUR", "lower_bound": 0, "upper_bound": 50000 }, "total_asset_value": { "currency": "EUR", "lower_bound": 0, "upper_bound": 50000 } } } } } } }, "responses": { "202": { "description": "The request has been successfully accepted.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Business Check - Create - Response", "type": "object", "description": "Response containing the unique identifier of the business check created.", "properties": { "id": { "title": "Business Check unique identifier", "type": "string", "description": "Business Check unique identifier.", "format": "uuid" } }, "required": [ "id" ], "additionalProperties": false }, "example": { "id": "e13e9d81-7f43-492d-a02a-440edced389a" } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/businesses/{business_id}/checks/{check_id}": { "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "The unique identifier of the business. Universally Unique Identifier (UUID).", "schema": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" } }, { "name": "check_id", "in": "path", "required": true, "description": "The unique identifier of the user check. Universally Unique Identifier (UUID).", "schema": { "title": "User Check unique identifier", "type": "string", "description": "User Check unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_business_check", "summary": "Get a business check by ID", "description": "Retrieves a check for a business specified by its ID.", "tags": [ "Business Checks" ], "security": [ { "oauth-client-credentials": [ "checks:read", "checks:admin" ] } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Business Check", "description": "A check conducted for a business, either a KYB check or a self-assessment.", "oneOf": [ { "title": "Business Check - KYB", "type": "object", "description": "A Know Your Business (KYB) check for a business, recording confirmation timestamps and a link to the submitted documents.", "properties": { "id": { "title": "Business Check unique identifier", "type": "string", "description": "Business Check unique identifier.", "format": "uuid" }, "business_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "type": { "type": "string", "default": "KYB", "description": "The type of check must be “KYB”." }, "originally_confirmed_at": { "type": "string", "format": "date-time", "description": "The date and time when the check was first confirmed. When the check has only been confirmed once, this value is the same as check_confirmed_at. When renewing KYB check, this value remains the same as when the check was first confirmed." }, "check_confirmed_at": { "type": "string", "format": "date-time", "description": "The date and time when the check was latest confirmed" }, "status": { "type": "string", "description": "Final status of the business check.\n* IN_PROGRESS - Check is in progress\n* PASSED - Check passed\n* FAILED - Check failed", "enum": [ "IN_PROGRESS", "PASSED", "FAILED" ] }, "data_download_link": { "type": "string", "format": "uri", "description": "Link to download the document bundle submitted for the KYB check" }, "document_type": { "type": "string", "default": "KYB_DOCUMENTS", "description": "Type of the document bundle. Always `KYB_DOCUMENTS`" } }, "required": [ "id", "business_id", "type", "originally_confirmed_at", "check_confirmed_at", "status", "data_download_link", "document_type" ] }, { "title": "Business Check - Business Self Assessment", "type": "object", "description": "The Business Self Assessment check captures information about the business's activities, financials, and purpose of the business relationship for risk scoring.", "properties": { "id": { "title": "Business Check unique identifier", "type": "string", "description": "Business Check unique identifier.", "format": "uuid" }, "business_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "type": { "type": "string", "default": "BUSINESS_SELF_ASSESSMENT", "description": "The type of check must be \"BUSINESS_SELF_ASSESSMENT\"." }, "check_confirmed_at": { "type": "string", "format": "date-time", "description": "The date and time when the self assessment check was confirmed." }, "status": { "type": "string", "description": "Final status of the business check.\n* IN_PROGRESS - Check is in progress\n* PASSED - Check passed\n* FAILED - Check failed", "enum": [ "IN_PROGRESS", "PASSED", "FAILED" ] }, "business_industry": { "title": "Business Industry", "type": "string", "description": "The business industry classification.", "enum": [ "ACCOMMODATION_AND_HOSPITALITY", "ACCOMMODATION_AND_HOSPITALITY_TIMESHARING", "ADMIN_AND_SUPPORT_SERVICES", "ADMIN_AND_SUPPORT_SERVICES_CLEANING_AND_FACILITIES", "ADMIN_AND_SUPPORT_SERVICES_SECURITY_AND_INVESTIGATION", "ADMIN_AND_SUPPORT_SERVICES_SPECIFIC_SECTORS", "AGRICULTURE_FORESTRY_AND_FISHING", "CONSTRUCTION", "EDUCATION", "EDUCATION_HIGHER_EDUCATION", "ENTERTAINMENT_ARTS_AND_RECREATION", "ENTERTAINMENT_ARTS_AND_RECREATION_NATURE_AND_ZOOS", "ENTERTAINMENT_ARTS_AND_RECREATION_SPECIFIC_SECTORS", "EXTRATERRITORIAL_AND_HOUSEHOLD_ACTIVITIES", "FINANCIAL_SERVICES", "FOOD_AND_BEVERAGE_SERVICES", "HEALTHCARE", "HEALTHCARE_COUNSELLING_AND_SOCIAL_SERVICES", "INFORMATION_TECHNOLOGY_AND_MEDIA", "INFORMATION_TECHNOLOGY_AND_MEDIA_ONLINE_GAMING", "INFORMATION_TECHNOLOGY_AND_MEDIA_PRINT_PUBLISHING", "INFORMATION_TECHNOLOGY_AND_MEDIA_TELECOMMUNICATIONS", "MANUFACTURING", "MANUFACTURING_PHARMACEUTICALS", "MANUFACTURING_PRECIOUS_METALS_AND_JEWELLERY", "MANUFACTURING_WEAPONS_AND_HAZARDOUS", "MINING_AND_QUARRYING", "PERSONAL_AND_OTHER_SERVICES", "PERSONAL_AND_OTHER_SERVICES_ADULT_AND_WELLNESS", "PERSONAL_AND_OTHER_SERVICES_NONPROFIT_AND_MEMBERSHIP_ORGANISATIONS", "PROFESSIONAL_AND_TECHNICAL_SERVICES", "PROFESSIONAL_AND_TECHNICAL_SERVICES_LEGAL_AND_FIDUCIARY", "PROFESSIONAL_AND_TECHNICAL_SERVICES_UNREGULATED", "PUBLIC_ADMINISTRATION", "PUBLIC_ADMINISTRATION_JUDICIAL", "REAL_ESTATE", "REAL_ESTATE_AGENCY_AND_BROKERAGE", "RETAIL_TRADE", "RETAIL_TRADE_SPECIALITY", "RETAIL_TRADE_SPECIFIC_SECTORS", "TRANSPORTATION_AND_LOGISTICS", "TRANSPORTATION_AND_LOGISTICS_CRUISE_LINES", "TRANSPORTATION_AND_LOGISTICS_RAIL_AND_STORAGE", "UTILITIES_AND_ENERGY", "WHOLESALE_TRADE", "WHOLESALE_TRADE_INDUSTRIAL", "WHOLESALE_TRADE_LUXURY_AND_COLLECTIBLES", "WHOLESALE_TRADE_PETROLEUM_AND_CHEMICALS" ] }, "purpose_of_business_relationship": { "title": "Purpose of Business Relationship", "type": "string", "description": "The purpose of the business relationship.", "enum": [ "WEALTH_GROWTH", "TREASURY_LIQUIDITY_MANAGEMENT", "HEDGING_RISK_MANAGEMENT", "EMPLOYEE_BENEFIT_FUNDING", "STRATEGIC_INVESTMENT" ] }, "primary_countries_of_activity": { "type": "array", "description": "List of primary countries where the business operates. ISO 3166-1 alpha-2 country codes.", "items": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "minItems": 1 }, "annual_revenue": { "title": "Monetary Range", "type": "object", "description": "A monetary range defined by a lower bound and an optional upper bound.", "properties": { "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "lower_bound": { "type": "number", "description": "The lower bound of the monetary range.", "minimum": 0 }, "upper_bound": { "type": "number", "description": "The upper bound of the monetary range.", "minimum": 0 } }, "required": [ "currency", "lower_bound" ], "additionalProperties": false }, "expected_volume_of_investment": { "title": "Monetary Range", "type": "object", "description": "A monetary range defined by a lower bound and an optional upper bound.", "properties": { "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "lower_bound": { "type": "number", "description": "The lower bound of the monetary range.", "minimum": 0 }, "upper_bound": { "type": "number", "description": "The upper bound of the monetary range.", "minimum": 0 } }, "required": [ "currency", "lower_bound" ], "additionalProperties": false }, "total_asset_value": { "title": "Monetary Range", "type": "object", "description": "A monetary range defined by a lower bound and an optional upper bound.", "properties": { "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "lower_bound": { "type": "number", "description": "The lower bound of the monetary range.", "minimum": 0 }, "upper_bound": { "type": "number", "description": "The upper bound of the monetary range.", "minimum": 0 } }, "required": [ "currency", "lower_bound" ], "additionalProperties": false } }, "required": [ "id", "business_id", "type", "check_confirmed_at", "status", "business_industry", "purpose_of_business_relationship", "primary_countries_of_activity", "annual_revenue", "expected_volume_of_investment", "total_asset_value" ], "additionalProperties": false } ] }, "examples": { "KYB": { "summary": "KYB check", "value": { "id": "f3b2d9c6-8e4f-4a7b-9c2d-7a5e1f3c4d6e", "business_id": "d4b5f9a7-8e2c-4c1d-9a3f-7b6e2d3c4f5a", "type": "KYB", "originally_confirmed_at": "2020-08-24T14:15:22Z", "check_confirmed_at": "2024-08-24T14:15:22Z", "data_download_link": "https://bucket.customer.com/por/kyb.zip", "document_type": "KYB_DOCUMENTS", "status": "IN_PROGRESS" } }, "BUSINESS_SELF_ASSESSMENT": { "summary": "Business Self Assessment check", "value": { "id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "business_id": "d4b5f9a7-8e2c-4c1d-9a3f-7b6e2d3c4f5a", "type": "BUSINESS_SELF_ASSESSMENT", "check_confirmed_at": "2021-08-24T14:15:22Z", "status": "PASSED", "business_industry": "MANUFACTURING", "purpose_of_business_relationship": "WEALTH_GROWTH", "primary_countries_of_activity": [ "DE", "FR" ], "annual_revenue": { "currency": "EUR", "lower_bound": 0, "upper_bound": 50000 }, "expected_volume_of_investment": { "currency": "EUR", "lower_bound": 0, "upper_bound": 50000 }, "total_asset_value": { "currency": "EUR", "lower_bound": 0, "upper_bound": 50000 } } } } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/businesses/{business_id}/accounts": { "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "The unique identifier of the business. Universally Unique Identifier (UUID).", "schema": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_business_accounts", "summary": "Get business accounts", "description": "Lists the accounts of a business specified by ID.", "tags": [ "Accounts" ], "security": [ { "oauth-client-credentials": [ "accounts:read", "accounts:admin" ] } ], "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "updated_at" ], "default": "created_at" }, "description": "Sort the result by `created_at`, `updated_at`." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Accounts - List - Response", "type": "object", "description": "Paginated response containing the accounts owned by a business.", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "description": "List of the business's accounts", "items": { "title": "Business Account", "type": "object", "description": "", "properties": { "id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "type": { "type": "string", "description": "Account type.\n* TRADING - Orders in accounts of this type are created on a specific instrument basis.\n* PORTFOLIO - Orders in accounts of this type are created on a portfolio basis and additional portfolio functionality is available.", "enum": [ "TRADING", "PORTFOLIO" ] }, "business_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "account_number": { "type": "integer", "description": "The serial account number of the account in the account group.", "minimum": 1 }, "name": { "type": "string", "description": "The name of the account.", "maxLength": 100 }, "status": { "type": "string", "description": "The status of the account\n* PENDING_APPROVAL - Account approval is pending - the account is visible through our API but cannot be acted on.\n* ACTIVE - Account is active - full functionality of the Investment API is accessible.\n* CLOSING - Account is closing - only sell orders or the transfer of positions out are permissible before the account is closed.\n* CLOSED - Account is closed with zero balance successfully.\n* LOCKED - Account is locked for all actions.", "enum": [ "PENDING_APPROVAL", "ACTIVE", "CLOSING", "CLOSED", "LOCKED" ] } }, "required": [ "id", "created_at", "updated_at", "account_group_id", "type", "business_id", "name", "status", "account_number" ], "additionalProperties": false } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "example": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1, "sort": "created_at", "order": "ASC" }, "data": [ { "id": "ad45b27f-c0e7-4cfb-b48c-a83670dbdfbd", "created_at": "2020-08-24T14:15:22Z", "updated_at": "2020-08-24T14:15:22Z", "account_group_id": "fa2414ed-8d62-46fd-85ed-565a340c81d6", "business_id": "bc6f8c82-1234-4b56-a7d8-9e012345f678", "type": "TRADING", "account_number": 1, "name": "Main account", "status": "ACTIVE" } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/businesses/{business_id}/account_groups": { "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "The unique identifier of the business. Universally Unique Identifier (UUID).", "schema": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_business_account_groups", "summary": "Get business account groups", "description": "Lists the account groups of a business specified by ID.", "tags": [ "Account Groups" ], "security": [ { "oauth-client-credentials": [ "accounts:read", "accounts:admin" ] } ], "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "updated_at" ], "default": "created_at" }, "description": "Sort the result by `created_at`, `updated_at`." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Account Groups - List - Response", "type": "object", "description": "Paginated response containing the account groups owned by a business.", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "description": "List of the business's account groups", "items": { "title": "Business Account Group", "type": "object", "description": "", "properties": { "id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "business_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "status": { "type": "string", "description": "Status of the account group\n* PENDING_APPROVAL - Account group approval is pending - the account group is visible through our API but cannot be acted on.\n* ACTIVE - Account group is active - full functionality of the Investment API is accessible.\n* CLOSING - Account group is closing.\n* CLOSED - Account group is closed.\n* LOCKED - Account group is locked for all actions.", "enum": [ "PENDING_APPROVAL", "ACTIVE", "CLOSING", "CLOSED", "LOCKED" ] }, "type": { "type": "string", "description": "Account group type.\n* BUSINESS - Account group of a business holding assets.", "enum": [ "BUSINESS" ] }, "securities_account_number": { "title": "Securities Account number.", "type": "string", "description": "Account unique identifier.", "format": "^\\d{7,12}$" } }, "required": [ "id", "created_at", "updated_at", "business_id", "status", "type", "securities_account_number" ], "additionalProperties": false } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "example": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1, "sort": "created_at", "order": "ASC" }, "data": [ { "id": "9d95820d-4333-46b6-98de-04ab7512e76f", "created_at": "2020-08-24T14:15:22Z", "updated_at": "2020-08-24T14:15:22Z", "type": "BUSINESS", "status": "ACTIVE", "business_id": "bc6f8c82-1234-4b56-a7d8-9e012345f678", "securities_account_number": "123456789" } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/businesses/{business_id}/reports": { "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "The unique identifier of the business. Universally Unique Identifier (UUID).", "schema": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_business_reports", "summary": "List business reports", "description": "Returns a paginated list of reports generated for the business identified by `business_id`.\n\nUse the `offset` and `limit` query parameters to page through results; `meta.total_count` gives the total number of matching reports. Use `type` and `instrument` to filter results, and `start_date`/`end_date` to limit the range of report generation dates.", "tags": [ "Reports" ], "security": [ { "oauth-client-credentials": [ "reports:read", "reports:admin" ] } ], "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "title": "Report type", "oneOf": [ { "title": "Report type", "description": "Report type\n* ACCOUNT_CLOSING - Securities account closure\n* ACCOUNT_OPENING - Securities account opening\n* AD_HOC_ACCOUNT_STATEMENT - Ad hoc account statement\n* ANNUAL_INCOME_STATEMENT - Annual tax income statement (\"Erträgnisaufstellung\")\n* ANNUAL_TAX_STATEMENT - Annual tax reporting\n* BANK_ACCOUNT_CONNECTED - Connect reference bank account\n* BUY_ORDER - Buy order\n* CANCELLED_ORDER - Cancelled buy or sell order (not yet executed, user cancels or trading venue cancelled)\n* CORPORATE_ACTION_CASH_TRANSACTION - cash transaction document (after corporate action)\n* CORPORATE_ACTION_SECURITY_TRANSACTION - security transaction document (after corporate action)\n* DIRECT_DEBIT_MANDATE - Creation of SEPA direct debit mandate\n* EX_POST_COST - Ex-post cost report\n* FEE_COLLECTION - Intake of service fees\n* FRENCH_IFU - French tax statement (Imprimé fiscal unique)\n* GENERIC_COMMUNICATION - Generic communication\n* INCOME_DISTRIBUTION - Income distribution report\n* LOSS_THRESHOLD - Notification that a holding has depreciated by 10%, or a multiple thereof, against its purchase value\n* MONTHLY_BILLING_STATEMENT - Monthly billing activities statement\n* QUARTERLY_ACCOUNT_STATEMENT - Quarterly account statement\n* REVOKED_ORDER - Revoked buy or sell order (\"Storno\")\n* SECURITIES_TRANSFER_INCOMING - Securities are transferred in\n* SECURITIES_TRANSFER_OUTGOING - Securities are being transferred out\n* SELL_ORDER - Sell order\n* TAX_CONSOLIDATED_CERTIFICATE_UK - UK Consolidated Tax Certificate\n* TAX_PAYMENT - Tax payment document\n* TAX_PREPAYMENT_DE - German tax prepayment (Vorabpauschale)\n* TAX_PREPAYMENT_DE_CANCELLATION - German tax prepayment (Vorabpauschale) cancellation\n* TAX_REFUND - Tax refund document (after tax optimization)", "type": "string", "enum": [ "ACCOUNT_CLOSING", "ACCOUNT_OPENING", "AD_HOC_ACCOUNT_STATEMENT", "ANNUAL_INCOME_STATEMENT", "ANNUAL_TAX_STATEMENT", "BANK_ACCOUNT_CONNECTED", "BUY_ORDER", "CANCELLED_ORDER", "CORPORATE_ACTION_CASH_TRANSACTION", "CORPORATE_ACTION_SECURITY_TRANSACTION", "DIRECT_DEBIT_MANDATE", "EX_POST_COST", "FEE_COLLECTION", "FRENCH_IFU", "GENERIC_COMMUNICATION", "INCOME_DISTRIBUTION", "LOSS_THRESHOLD", "MONTHLY_BILLING_STATEMENT", "QUARTERLY_ACCOUNT_STATEMENT", "REVOKED_ORDER", "SECURITIES_TRANSFER_INCOMING", "SECURITIES_TRANSFER_OUTGOING", "SELL_ORDER", "TAX_CONSOLIDATED_CERTIFICATE_UK", "TAX_PAYMENT", "TAX_PREPAYMENT_DE", "TAX_PREPAYMENT_DE_CANCELLATION", "TAX_REFUND" ] }, { "type": "string", "enum": [ "ORDER_EX_ANTE_COST", "ORDER_EX_ANTE_COST_SAVINGS_PLAN" ], "description": "The type of report must be “ORDER_EX_ANTE_COST” or “ORDER_EX_ANTE_COST_SAVINGS_PLAN”." } ] }, "description": "Filters the list to only show reports of a certain type (e.g. only buy order confirmations)", "example": "BUY_ORDER" }, { "name": "instrument", "in": "query", "required": false, "schema": { "oneOf": [ { "title": "International securities identification number, prefixed with string 'isin:'", "type": "string", "description": "International securities identification number, prefixed with string 'isin:'", "pattern": "^isin:[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, { "title": "Unique identifier, prefixed with string 'uuid:'", "type": "string", "description": "Unique identifier, prefixed with string 'uuid:'", "pattern": "^uuid:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } ], "example": "uuid:ebabcf4d-61c3-4942-875c-e265a7c2d062" }, "description": "Filters the list to only include reports concerning specified instrument" }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "title": "Date in YYYY-MM-DD format. RFC 3339, section 5.6", "description": "Returns reports generated starting from and including this date (UTC)" }, "description": "Returns reports generated on or after this date, as an [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) date in `YYYY-MM-DD` format (UTC)", "example": "2020-08-21" }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "title": "Date in YYYY-MM-DD format. RFC 3339, section 5.6", "description": "Returns reports generated up until this date (UTC)" }, "description": "Returns reports generated on or before this date, as an [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) date in `YYYY-MM-DD` format (UTC)", "example": "2020-09-25" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "id", "created_at" ], "default": "created_at" }, "description": "Field to sort the result by. Accepts `id` or `created_at`", "example": "id" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." } ], "responses": { "200": { "description": "Reports list", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Business Reports - List - Response", "type": "object", "description": "Paginated response containing the reports generated for a business.", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count", "sort", "order" ] }, "data": { "type": "array", "description": "List of reports generated for the business", "items": { "title": "Business Report", "type": "object", "properties": { "id": { "title": "Report unique identifier.", "type": "string", "description": "Report unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "business_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "type": { "title": "Report type", "description": "Report type\n* ACCOUNT_CLOSING - Securities account closure\n* ACCOUNT_OPENING - Securities account opening\n* AD_HOC_ACCOUNT_STATEMENT - Ad hoc account statement\n* ANNUAL_INCOME_STATEMENT - Annual tax income statement (\"Erträgnisaufstellung\")\n* ANNUAL_TAX_STATEMENT - Annual tax reporting\n* BANK_ACCOUNT_CONNECTED - Connect reference bank account\n* BUY_ORDER - Buy order\n* CANCELLED_ORDER - Cancelled buy or sell order (not yet executed, user cancels or trading venue cancelled)\n* CORPORATE_ACTION_CASH_TRANSACTION - cash transaction document (after corporate action)\n* CORPORATE_ACTION_SECURITY_TRANSACTION - security transaction document (after corporate action)\n* DIRECT_DEBIT_MANDATE - Creation of SEPA direct debit mandate\n* EX_POST_COST - Ex-post cost report\n* FEE_COLLECTION - Intake of service fees\n* FRENCH_IFU - French tax statement (Imprimé fiscal unique)\n* GENERIC_COMMUNICATION - Generic communication\n* INCOME_DISTRIBUTION - Income distribution report\n* LOSS_THRESHOLD - Notification that a holding has depreciated by 10%, or a multiple thereof, against its purchase value\n* MONTHLY_BILLING_STATEMENT - Monthly billing activities statement\n* QUARTERLY_ACCOUNT_STATEMENT - Quarterly account statement\n* REVOKED_ORDER - Revoked buy or sell order (\"Storno\")\n* SECURITIES_TRANSFER_INCOMING - Securities are transferred in\n* SECURITIES_TRANSFER_OUTGOING - Securities are being transferred out\n* SELL_ORDER - Sell order\n* TAX_CONSOLIDATED_CERTIFICATE_UK - UK Consolidated Tax Certificate\n* TAX_PAYMENT - Tax payment document\n* TAX_PREPAYMENT_DE - German tax prepayment (Vorabpauschale)\n* TAX_PREPAYMENT_DE_CANCELLATION - German tax prepayment (Vorabpauschale) cancellation\n* TAX_REFUND - Tax refund document (after tax optimization)", "type": "string", "enum": [ "ACCOUNT_CLOSING", "ACCOUNT_OPENING", "AD_HOC_ACCOUNT_STATEMENT", "ANNUAL_INCOME_STATEMENT", "ANNUAL_TAX_STATEMENT", "BANK_ACCOUNT_CONNECTED", "BUY_ORDER", "CANCELLED_ORDER", "CORPORATE_ACTION_CASH_TRANSACTION", "CORPORATE_ACTION_SECURITY_TRANSACTION", "DIRECT_DEBIT_MANDATE", "EX_POST_COST", "FEE_COLLECTION", "FRENCH_IFU", "GENERIC_COMMUNICATION", "INCOME_DISTRIBUTION", "LOSS_THRESHOLD", "MONTHLY_BILLING_STATEMENT", "QUARTERLY_ACCOUNT_STATEMENT", "REVOKED_ORDER", "SECURITIES_TRANSFER_INCOMING", "SECURITIES_TRANSFER_OUTGOING", "SELL_ORDER", "TAX_CONSOLIDATED_CERTIFICATE_UK", "TAX_PAYMENT", "TAX_PREPAYMENT_DE", "TAX_PREPAYMENT_DE_CANCELLATION", "TAX_REFUND" ] }, "substituted_report_id": { "oneOf": [ { "type": "null" }, { "title": "Substituted Report unique identifier.", "type": "string", "description": "References report that has been replaced by this one.", "format": "uuid" } ] }, "data": { "title": "Report Data", "type": "object", "description": "Contents of the report.", "properties": { "account": { "type": "object", "title": "Account.", "description": "Account information.", "properties": { "id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" } } }, "references": { "type": "array", "title": "References.", "items": { "title": "Report reference data", "type": "object", "description": "Reference data for a report", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "title": "Report reference type", "description": "Report reference type\n* CORPORATE_ACTION_TRANSACTION_ID - Corporate action transaction identifier\n* ACCOUNT_GROUP_ID - Account group identifier\n* ACCOUNT_ID - Account identifier\n* ORDER_ID - Order identifier", "type": "string", "enum": [ "CORPORATE_ACTION_TRANSACTION_ID", "ACCOUNT_GROUP_ID", "ACCOUNT_ID", "ORDER_ID" ] } } } } } } }, "required": [ "id", "business_id", "created_at", "type", "substituted_report_id" ], "additionalProperties": false } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "example": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1, "sort": "id", "order": "ASC" }, "data": [ { "id": "b96b1ee7-d491-43eb-b5e4-4833af9c9c2f", "created_at": "2020-08-24T14:15:22Z", "business_id": "a9a72268-4f3c-4de2-abb9-a553a3bb7608", "type": "CORPORATE_ACTION_CASH_TRANSACTION", "substituted_report_id": null, "data": { "account": { "id": "a9a4ad54-6dd1-419a-a98d-ab48f9f23bc8" }, "references": [ { "id": "b96b1ee7-d491-43eb-b5e4-4833af9c9c2f", "type": "CORPORATE_ACTION_TRANSACTION_ID" } ] } } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/businesses/{business_id}/payments/reference_accounts": { "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "The unique identifier of the business. Universally Unique Identifier (UUID).", "schema": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_business_reference_accounts", "summary": "Get reference accounts of a business", "description": "Returns the list of reference accounts for a business specified by ID.", "tags": [ "Reference Accounts" ], "security": [ { "oauth-client-credentials": [ "reference_accounts:admin", "reference_accounts:read" ] } ], "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "id", "created_at" ], "default": "created_at" }, "description": "Field of resource to sort by", "example": "id" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." } ], "responses": { "200": { "description": "Business reference accounts list.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Business Reference Accounts - List - Response", "type": "object", "description": "Paginated list of reference bank accounts for a business, including cursor-based pagination metadata.", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "items": { "title": "Business Reference Account", "type": "object", "description": "A verified reference bank account belonging to a business, used as the destination for cash withdrawals.", "properties": { "id": { "title": "Reference account unique identifier.", "type": "string", "description": "Reference account unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "business_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "account_owner": { "type": "string", "maxLength": 140, "description": "Name of the reference account holder" }, "name": { "type": "string", "maxLength": 100, "description": "Human-readable name of the reference bank account" }, "iban": { "title": "International Bank Account Number (IBAN)", "type": "string", "description": "Obfuscated International Bank Account Number [IBAN](https://en.wikipedia.org/wiki/International_Bank_Account_Number).", "pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{2}\\*{10}[A-Z0-9]{4}$" }, "bic": { "title": "Business Identifier Code", "type": "string", "description": "Business Identifier Code (also known as SWIFT-BIC, BIC, SWIFT ID or SWIFT code) [ISO 9362](https://en.wikipedia.org/wiki/ISO_9362).", "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$" }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp of when user validated the reference account" } }, "required": [ "id", "created_at", "updated_at", "account_owner", "iban", "bic", "confirmed_at" ], "additionalProperties": false } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "example": { "meta": { "offset": 0, "limit": 100, "count": 1, "total_count": 1 }, "data": [ { "id": "c18f80bd-401e-4836-9776-7dc24c32d35e", "created_at": "2020-08-24T14:15:22Z", "updated_at": "2020-08-24T14:15:22Z", "business_id": "8f8a5c5e-2a3b-4c7d-bf9e-1d2e3f4a5b6c", "account_owner": "Acme GmbH", "name": "Acme Business Account", "iban": "DE0210**********0402", "bic": "BELADEBE", "confirmed_at": "2020-08-23T14:15:22Z" } ] } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/roles": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "list_roles", "summary": "Get all roles", "description": "Returns a paginated list of roles.\n\nUse the `offset` and `limit` query parameters to page through results; `meta.total_count` gives the total number of matching roles. Use `user_id` to filter by a specific user, `entity_id` to filter by account group or business, and `sort`/`order` to control the ordering by `created_at` or `updated_at`.\n\nSee the User roles guide ([TOL](https://docs.upvest.co/products/tol/guides/users/users_onboarding_roles) / [BYOL](https://docs.upvest.co/products/byol/guides/users/users_onboarding_roles)) for role types and assignment rules.", "tags": [ "Roles" ], "security": [ { "oauth-client-credentials": [ "roles:read", "roles:admin" ] } ], "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "updated_at" ], "default": "created_at" }, "description": "The field to sort the results by. One of `created_at` or `updated_at`; defaults to `created_at`." }, { "name": "user_id", "in": "path", "required": true, "description": "The unique identifier of the user. Universally Unique Identifier (UUID).", "schema": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" } }, { "name": "user_id", "in": "query", "required": false, "description": "Filters results by user ID. Universally Unique Identifier (UUID).", "schema": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" } }, { "name": "entity_id", "in": "query", "required": false, "description": "Filters results by entity ID. Universally Unique Identifier (UUID).", "schema": { "title": "Entity unique identifier.", "type": "string", "description": "Unique identifier of the entity a role is attached to.", "format": "uuid" } }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Roles - List - Response", "type": "object", "description": "Paginated list of roles. Contains a `data` array of role objects and a `meta` object with offset/limit pagination metadata.", "properties": { "meta": { "type": "object", "properties": { "offset": { "type": "integer", "description": "Amount of resource to offset in the response." }, "limit": { "type": "integer", "description": "Total limit of the response." }, "count": { "type": "integer", "description": "Count of the resources returned in the response." }, "total_count": { "type": "integer", "description": "Total count of all the resources." }, "sort": { "type": "string", "description": "The field that the list is sorted by." }, "order": { "type": "string", "description": "The ordering of the response.\n* ASC - Ascending order\n* DESC - Descending order", "enum": [ "ASC", "DESC" ] } }, "required": [ "offset", "limit", "count", "total_count" ] }, "data": { "type": "array", "description": "List of roles matching the query.", "items": { "title": "Role", "description": "A role assigned to a user for a specific entity (business or account group).", "oneOf": [ { "title": "Account Group Role", "type": "object", "description": "Role assignment for an account group.", "properties": { "id": { "type": "string", "description": "Unique identifier for the role.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "entity_type": { "type": "string", "default": "ACCOUNT_GROUP", "description": "The entity type; must be `ACCOUNT_GROUP` for account group roles." }, "entity_id": { "title": "Entity unique identifier.", "type": "string", "description": "Unique identifier of the entity a role is attached to.", "format": "uuid" }, "role_type": { "type": "string", "description": "Role type for an account group.\n* `OWNER` — The user owns the account group.\n* `GUARDIAN` — The user is a legal custodian of a child account group.\n* `CHILD` — The user is the child beneficiary of a child account group.", "enum": [ "OWNER", "GUARDIAN", "CHILD" ] }, "custody_type": { "type": "string", "description": "Custody type for child account groups.\n* `SOLE_CUSTODY` — A single guardian has custody of the child account group.\n* `JOINT_CUSTODY` — Multiple guardians are required for the child account group.", "enum": [ "SOLE_CUSTODY", "JOINT_CUSTODY" ] }, "status": { "type": "string", "description": "Status of the role assignment.\n* `PENDING` — The role has been created but is not yet active.\n* `ACTIVE` — The role is active.\n* `DEACTIVATED` — The role has been deactivated and cannot be reactivated.", "enum": [ "PENDING", "ACTIVE", "DEACTIVATED" ] } }, "required": [ "id", "created_at", "updated_at", "user_id", "entity_type", "entity_id", "role_type", "status" ], "additionalProperties": false }, { "title": "Business Role", "type": "object", "description": "Role assignment for a business entity.", "properties": { "id": { "type": "string", "description": "Unique identifier for the role.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "entity_type": { "type": "string", "default": "BUSINESS", "description": "The entity type; must be `BUSINESS` for business roles." }, "entity_id": { "title": "Entity unique identifier.", "type": "string", "description": "Unique identifier of the entity a role is attached to.", "format": "uuid" }, "role_type": { "type": "string", "description": "Role type for a business entity.\n* `LEGAL_REPRESENTATIVE` — The user is a legal representative of the business.\n* `AUTHORISED_SIGNATORY` — The user is authorised to sign documents and make commitments on behalf of the business.\n* `ULTIMATE_BENEFICIAL_OWNER` — The user ultimately owns or controls the business.\n* `CONTRACTING_EXECUTIVE` — The user is able to enter into contracts on behalf of the business.\n* `TRADER` — The user is authorised to place orders on behalf of the business.\n* `SOLE_TRADER` — The user places orders on behalf of a sole trader entity.", "enum": [ "LEGAL_REPRESENTATIVE", "AUTHORISED_SIGNATORY", "ULTIMATE_BENEFICIAL_OWNER", "CONTRACTING_EXECUTIVE", "TRADER", "SOLE_TRADER" ] }, "status": { "type": "string", "description": "Status of the role assignment.\n* `PENDING` — The role has been created but is not yet active.\n* `ACTIVE` — The role is active.\n* `DEACTIVATED` — The role has been deactivated and cannot be reactivated.", "enum": [ "PENDING", "ACTIVE", "DEACTIVATED" ] } }, "required": [ "id", "created_at", "updated_at", "user_id", "entity_type", "entity_id", "role_type", "status" ], "additionalProperties": false } ] } } }, "required": [ "meta", "data" ], "additionalProperties": false }, "examples": { "List Roles": { "summary": "List of roles", "value": { "meta": { "offset": 0, "limit": 100, "count": 2, "total_count": 2, "sort": "created_at", "order": "ASC" }, "data": [ { "id": "baf05386-0459-4e8c-9ac9-cd6442f194dd", "created_at": "2025-04-01T10:11:40Z", "updated_at": "2025-04-01T10:11:40Z", "user_id": "9c36af78-91a0-4174-a515-fc81214e3dab", "entity_type": "ACCOUNT_GROUP", "entity_id": "413715f2-5401-4b97-8055-034a6b879f8c", "custody_type": "SOLE_CUSTODY", "role_type": "GUARDIAN", "status": "ACTIVE" }, { "id": "e8b5a51d-8baf-4d0b-8a3b-8f8f8f8f8f8f", "created_at": "2025-04-01T10:12:40Z", "updated_at": "2025-04-01T10:12:40Z", "user_id": "0d10c51f-33f2-4399-b8ab-92ec84e6b2f0", "entity_type": "BUSINESS", "entity_id": "6deb17c8-950e-4377-b500-5522af5ef712", "role_type": "LEGAL_REPRESENTATIVE", "status": "ACTIVE" } ] } }, "Empty List": { "summary": "Empty roles list", "value": { "meta": { "offset": 0, "limit": 100, "count": 0, "total_count": 0, "sort": "created_at", "order": "ASC" }, "data": [] } } } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "post": { "operationId": "create_role", "summary": "Create a role", "description": "Creates a role, assigning a user to an account group or business entity.\n\nThe `entity_type` parameter determines whether `entity_id` refers to an account group or a business, and constrains which `role_type` values are valid.\n\nSee the User roles guide ([TOL](https://docs.upvest.co/products/tol/guides/users/users_onboarding_roles) / [BYOL](https://docs.upvest.co/products/byol/guides/users/users_onboarding_roles)) for role types and assignment rules.", "tags": [ "Roles" ], "security": [ { "oauth-client-credentials": [ "roles:admin" ] } ], "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$", "example": "ccb07f42-4104-44ad-8e1f-c660bb7b269c" }, "description": "A UUID to be used as an idempotency key. This prevents a duplicate request from being replayed.\nhttps://docs.upvest.co/documentation/concepts/api_concepts/idempotency\n" } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Role - Create - Request", "description": "Request schema for creating a role.", "anyOf": [ { "title": "Account Group Role - Create - Request", "type": "object", "description": "Request to create a role assignment for an account group.", "properties": { "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "entity_type": { "type": "string", "default": "ACCOUNT_GROUP", "description": "The entity type; must be `ACCOUNT_GROUP` for account group roles." }, "entity_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "role_type": { "type": "string", "description": "Role type to assign. This request supports only `GUARDIAN`.\n* `GUARDIAN` — The user is a legal custodian of the child account group.", "enum": [ "GUARDIAN" ] }, "custody_type": { "type": "string", "description": "Custody type for child account groups.\n* `SOLE_CUSTODY` — A single guardian has custody of the child account group.\n* `JOINT_CUSTODY` — Multiple guardians are required for the child account group.", "enum": [ "SOLE_CUSTODY", "JOINT_CUSTODY" ] } }, "required": [ "user_id", "entity_type", "entity_id", "role_type" ], "additionalProperties": false }, { "title": "Business Role - Create - Request", "type": "object", "description": "Request to create a role for a business entity.", "properties": { "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "entity_type": { "type": "string", "default": "BUSINESS", "description": "The entity type; must be `BUSINESS` for business roles." }, "entity_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "role_type": { "type": "string", "description": "Role type for a business entity.\n* `LEGAL_REPRESENTATIVE` — The user is a legal representative of the business.\n* `AUTHORISED_SIGNATORY` — The user is authorised to sign documents and make commitments on behalf of the business.\n* `ULTIMATE_BENEFICIAL_OWNER` — The user ultimately owns or controls the business.\n* `CONTRACTING_EXECUTIVE` — The user is able to enter into contracts on behalf of the business.\n* `TRADER` — The user is authorised to place orders on behalf of the business.\n* `SOLE_TRADER` — The user places orders on behalf of a sole trader entity.", "enum": [ "LEGAL_REPRESENTATIVE", "AUTHORISED_SIGNATORY", "ULTIMATE_BENEFICIAL_OWNER", "CONTRACTING_EXECUTIVE", "TRADER", "SOLE_TRADER" ] } }, "required": [ "user_id", "entity_type", "entity_id", "role_type" ], "additionalProperties": false } ] }, "examples": { "Account Group": { "summary": "Account Group role", "value": { "user_id": "9c36af78-91a0-4174-a515-fc81214e3dab", "entity_type": "ACCOUNT_GROUP", "entity_id": "413715f2-5401-4b97-8055-034a6b879f8c", "role_type": "GUARDIAN", "custody_type": "SOLE_CUSTODY" } }, "Business": { "summary": "Business role", "value": { "user_id": "0d10c51f-33f2-4399-b8ab-92ec84e6b2f0", "entity_type": "BUSINESS", "entity_id": "6deb17c8-950e-4377-b500-5522af5ef712", "role_type": "LEGAL_REPRESENTATIVE" } } } } } }, "responses": { "200": { "description": "Role created.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Role - Create - Response", "description": "Response schema for creating a role.", "oneOf": [ { "title": "Account Group Role - Create - Response", "description": "Response schema for creating an account group role.", "allOf": [ { "title": "Account Group Role", "type": "object", "description": "Role assignment for an account group.", "properties": { "id": { "type": "string", "description": "Unique identifier for the role.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "entity_type": { "type": "string", "default": "ACCOUNT_GROUP", "description": "The entity type; must be `ACCOUNT_GROUP` for account group roles." }, "entity_id": { "title": "Entity unique identifier.", "type": "string", "description": "Unique identifier of the entity a role is attached to.", "format": "uuid" }, "role_type": { "type": "string", "description": "Role type for an account group.\n* `OWNER` — The user owns the account group.\n* `GUARDIAN` — The user is a legal custodian of a child account group.\n* `CHILD` — The user is the child beneficiary of a child account group.", "enum": [ "OWNER", "GUARDIAN", "CHILD" ] }, "custody_type": { "type": "string", "description": "Custody type for child account groups.\n* `SOLE_CUSTODY` — A single guardian has custody of the child account group.\n* `JOINT_CUSTODY` — Multiple guardians are required for the child account group.", "enum": [ "SOLE_CUSTODY", "JOINT_CUSTODY" ] }, "status": { "type": "string", "description": "Status of the role assignment.\n* `PENDING` — The role has been created but is not yet active.\n* `ACTIVE` — The role is active.\n* `DEACTIVATED` — The role has been deactivated and cannot be reactivated.", "enum": [ "PENDING", "ACTIVE", "DEACTIVATED" ] } }, "required": [ "id", "created_at", "updated_at", "user_id", "entity_type", "entity_id", "role_type", "status" ], "additionalProperties": false }, { "type": "object", "properties": { "role_type": { "type": "string", "description": "Role type for account group.", "enum": [ "GUARDIAN" ] } }, "required": [ "role_type" ] } ] }, { "title": "Business Role", "type": "object", "description": "Role assignment for a business entity.", "properties": { "id": { "type": "string", "description": "Unique identifier for the role.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "entity_type": { "type": "string", "default": "BUSINESS", "description": "The entity type; must be `BUSINESS` for business roles." }, "entity_id": { "title": "Entity unique identifier.", "type": "string", "description": "Unique identifier of the entity a role is attached to.", "format": "uuid" }, "role_type": { "type": "string", "description": "Role type for a business entity.\n* `LEGAL_REPRESENTATIVE` — The user is a legal representative of the business.\n* `AUTHORISED_SIGNATORY` — The user is authorised to sign documents and make commitments on behalf of the business.\n* `ULTIMATE_BENEFICIAL_OWNER` — The user ultimately owns or controls the business.\n* `CONTRACTING_EXECUTIVE` — The user is able to enter into contracts on behalf of the business.\n* `TRADER` — The user is authorised to place orders on behalf of the business.\n* `SOLE_TRADER` — The user places orders on behalf of a sole trader entity.", "enum": [ "LEGAL_REPRESENTATIVE", "AUTHORISED_SIGNATORY", "ULTIMATE_BENEFICIAL_OWNER", "CONTRACTING_EXECUTIVE", "TRADER", "SOLE_TRADER" ] }, "status": { "type": "string", "description": "Status of the role assignment.\n* `PENDING` — The role has been created but is not yet active.\n* `ACTIVE` — The role is active.\n* `DEACTIVATED` — The role has been deactivated and cannot be reactivated.", "enum": [ "PENDING", "ACTIVE", "DEACTIVATED" ] } }, "required": [ "id", "created_at", "updated_at", "user_id", "entity_type", "entity_id", "role_type", "status" ], "additionalProperties": false } ] }, "examples": { "Account Group": { "summary": "Account Group role", "value": { "id": "baf05386-0459-4e8c-9ac9-cd6442f194dd", "created_at": "2025-04-01T10:11:40Z", "updated_at": "2025-04-01T10:11:40Z", "user_id": "9c36af78-91a0-4174-a515-fc81214e3dab", "entity_type": "ACCOUNT_GROUP", "entity_id": "413715f2-5401-4b97-8055-034a6b879f8c", "role_type": "GUARDIAN", "status": "PENDING" } }, "Business": { "summary": "Business role", "value": { "id": "e8b5a51d-8baf-4d0b-8a3b-8f8f8f8f8f8f", "created_at": "2025-04-01T10:11:40Z", "updated_at": "2025-04-01T10:11:40Z", "user_id": "0d10c51f-33f2-4399-b8ab-92ec84e6b2f0", "entity_type": "BUSINESS", "entity_id": "6deb17c8-950e-4377-b500-5522af5ef712", "role_type": "LEGAL_REPRESENTATIVE", "status": "ACTIVE" } } } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/roles/{role_id}": { "parameters": [ { "name": "role_id", "in": "path", "required": true, "description": "The unique identifier of the role. Universally Unique Identifier (UUID).", "schema": { "type": "string", "description": "Unique identifier for the role.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "get": { "operationId": "retrieve_role", "summary": "Get a role by ID", "description": "Returns the role identified by `role_id`, including its status and entity assignment.", "tags": [ "Roles" ], "security": [ { "oauth-client-credentials": [ "roles:read", "roles:admin" ] } ], "responses": { "200": { "description": "OK", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Role - Retrieve - Response", "description": "Response schema for retrieving a role.", "oneOf": [ { "title": "Account Group Role", "type": "object", "description": "Role assignment for an account group.", "properties": { "id": { "type": "string", "description": "Unique identifier for the role.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "entity_type": { "type": "string", "default": "ACCOUNT_GROUP", "description": "The entity type; must be `ACCOUNT_GROUP` for account group roles." }, "entity_id": { "title": "Entity unique identifier.", "type": "string", "description": "Unique identifier of the entity a role is attached to.", "format": "uuid" }, "role_type": { "type": "string", "description": "Role type for an account group.\n* `OWNER` — The user owns the account group.\n* `GUARDIAN` — The user is a legal custodian of a child account group.\n* `CHILD` — The user is the child beneficiary of a child account group.", "enum": [ "OWNER", "GUARDIAN", "CHILD" ] }, "custody_type": { "type": "string", "description": "Custody type for child account groups.\n* `SOLE_CUSTODY` — A single guardian has custody of the child account group.\n* `JOINT_CUSTODY` — Multiple guardians are required for the child account group.", "enum": [ "SOLE_CUSTODY", "JOINT_CUSTODY" ] }, "status": { "type": "string", "description": "Status of the role assignment.\n* `PENDING` — The role has been created but is not yet active.\n* `ACTIVE` — The role is active.\n* `DEACTIVATED` — The role has been deactivated and cannot be reactivated.", "enum": [ "PENDING", "ACTIVE", "DEACTIVATED" ] } }, "required": [ "id", "created_at", "updated_at", "user_id", "entity_type", "entity_id", "role_type", "status" ], "additionalProperties": false }, { "title": "Business Role", "type": "object", "description": "Role assignment for a business entity.", "properties": { "id": { "type": "string", "description": "Unique identifier for the role.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "entity_type": { "type": "string", "default": "BUSINESS", "description": "The entity type; must be `BUSINESS` for business roles." }, "entity_id": { "title": "Entity unique identifier.", "type": "string", "description": "Unique identifier of the entity a role is attached to.", "format": "uuid" }, "role_type": { "type": "string", "description": "Role type for a business entity.\n* `LEGAL_REPRESENTATIVE` — The user is a legal representative of the business.\n* `AUTHORISED_SIGNATORY` — The user is authorised to sign documents and make commitments on behalf of the business.\n* `ULTIMATE_BENEFICIAL_OWNER` — The user ultimately owns or controls the business.\n* `CONTRACTING_EXECUTIVE` — The user is able to enter into contracts on behalf of the business.\n* `TRADER` — The user is authorised to place orders on behalf of the business.\n* `SOLE_TRADER` — The user places orders on behalf of a sole trader entity.", "enum": [ "LEGAL_REPRESENTATIVE", "AUTHORISED_SIGNATORY", "ULTIMATE_BENEFICIAL_OWNER", "CONTRACTING_EXECUTIVE", "TRADER", "SOLE_TRADER" ] }, "status": { "type": "string", "description": "Status of the role assignment.\n* `PENDING` — The role has been created but is not yet active.\n* `ACTIVE` — The role is active.\n* `DEACTIVATED` — The role has been deactivated and cannot be reactivated.", "enum": [ "PENDING", "ACTIVE", "DEACTIVATED" ] } }, "required": [ "id", "created_at", "updated_at", "user_id", "entity_type", "entity_id", "role_type", "status" ], "additionalProperties": false } ] }, "examples": { "Account Group": { "summary": "Account Group role", "value": { "id": "baf05386-0459-4e8c-9ac9-cd6442f194dd", "created_at": "2025-04-01T10:11:40Z", "updated_at": "2025-04-01T10:11:40Z", "user_id": "9c36af78-91a0-4174-a515-fc81214e3dab", "entity_type": "ACCOUNT_GROUP", "entity_id": "413715f2-5401-4b97-8055-034a6b879f8c", "role_type": "GUARDIAN", "custody_type": "JOINT_CUSTODY", "status": "ACTIVE" } }, "Business": { "summary": "Business role", "value": { "id": "e8b5a51d-8baf-4d0b-8a3b-8f8f8f8f8f8f", "created_at": "2025-04-01T10:11:40Z", "updated_at": "2025-04-01T10:11:40Z", "user_id": "0d10c51f-33f2-4399-b8ab-92ec84e6b2f0", "entity_type": "BUSINESS", "entity_id": "6deb17c8-950e-4377-b500-5522af5ef712", "role_type": "LEGAL_REPRESENTATIVE", "status": "ACTIVE" } } } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } }, "delete": { "operationId": "role_deactivation", "summary": "Deactivate a role by ID", "description": "Deactivates the role specified by its ID. The role remains queryable with status `DEACTIVATED`.\nOnly roles whose `entity_type` is `BUSINESS` may be deactivated via this endpoint; account-group roles are rejected with `403 Forbidden`.\nDeactivation is a terminal state; once deactivated, a role cannot be reactivated.\nDeactivation is idempotent: calling this endpoint on an already-deactivated role returns `202 Accepted` without side effects.\nA `ROLE.DEACTIVATED` webhook event is emitted on the first successful deactivation.", "tags": [ "Roles" ], "security": [ { "oauth-client-credentials": [ "roles:admin" ] } ], "responses": { "202": { "description": "The request has been successfully accepted and will be processed asynchronously.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }, "/tests/payments/transactions": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" } ], "post": { "operationId": "create_bank_transaction", "summary": "Trigger a bank transaction", "description": "Trigger a bank transaction for testing purposes. This can be used to simulate a money transfer for various flows which need cash settlements on one of our bank accounts.", "tags": [ "Tests" ], "security": [ { "oauth-client-credentials": [ "tests:admin" ] } ], "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$", "example": "ccb07f42-4104-44ad-8e1f-c660bb7b269c" }, "description": "A UUID to be used as an idempotency key. This prevents a duplicate request from being replayed.\nhttps://docs.upvest.co/documentation/concepts/api_concepts/idempotency\n" } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Payments - Bank Transaction - Create - Request", "type": "object", "description": "Request body for recording an incoming bank transaction against a virtual bank account.", "properties": { "account": { "allOf": [ { "type": "object", "description": "Bank account identification for a bank transaction, containing an IBAN.", "properties": { "iban": { "title": "International Bank Account Number (IBAN)", "type": "string", "description": "International Bank Account Number [IBAN](https://en.wikipedia.org/wiki/International_Bank_Account_Number).", "pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,26}$" } }, "required": [ "iban" ], "additionalProperties": false }, { "description": "The Upvest account identification" } ] }, "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "title": "Bank transaction currency", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code", "type": "string", "enum": [ "EUR", "GBP", "USD", "JPY", "CHF" ] }, "remittance_information": { "type": "string", "maxLength": 140, "pattern": "^[0-9A-Za-z+?/\\-:()\\.,'; ]{0,140}$", "description": "Information supplied to enable the matching/reconciliation of an entry with the items that the payment is intended to settle, such as commercial invoices in an accounts' receivable system, in an unstructured form." }, "client_reference": { "type": "string", "maxLength": 35, "pattern": "^[0-9A-Za-z+?/\\-:()\\.,'; ]{0,35}$", "description": "Immutable reference to the API flow that initiated the order. For client initiated API flows, this is a client provided ID. For internal initiations, it is set to the ID of the related object." }, "counterparty_name": { "type": "string", "maxLength": 140, "pattern": "^[0-9A-Za-z+?/\\-:()\\.,'; ]{0,140}$", "description": "The counterparty account owner" }, "counterparty_account": { "allOf": [ { "type": "object", "description": "Bank account identification for a bank transaction, containing an IBAN.", "properties": { "iban": { "title": "International Bank Account Number (IBAN)", "type": "string", "description": "International Bank Account Number [IBAN](https://en.wikipedia.org/wiki/International_Bank_Account_Number).", "pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,26}$" } }, "required": [ "iban" ], "additionalProperties": false }, { "description": "Unambiguous identification of the account of the counterparty of the bank transaction" } ] }, "counterparty_agent": { "allOf": [ { "type": "object", "description": "Bank agent identification for a bank transaction, containing a BIC.", "properties": { "bic": { "title": "Business Identifier Code", "type": "string", "description": "Business Identifier Code (also known as SWIFT-BIC, BIC, SWIFT ID or SWIFT code) [ISO 9362](https://en.wikipedia.org/wiki/ISO_9362).", "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$" } }, "required": [ "bic" ], "additionalProperties": false }, { "description": "Unambiguous identification of the agent of the counterparty of the bank transaction" } ] }, "virtual_bank_account_id": { "allOf": [ { "title": "Virtual bank account request unique identifier.", "type": "string", "description": "Virtual bank account request unique identifier.", "format": "uuid" }, { "description": "The ID of the virtual bank account to which you want to send the money." } ] }, "purpose_code": { "type": "string", "maxLength": 4, "description": "An optional parameter, which describes the purpose of the payment based on *ExternalPurpose1Code* from [ISO 20022](https://www.iso20022.org/catalogue-messages/additional-content-messages/external-code-sets)." } }, "required": [ "account", "amount", "currency", "client_reference", "counterparty_name", "counterparty_account" ], "additionalProperties": false }, "example": { "account": { "iban": "NL70ABNA0106295004" }, "amount": "13.37", "currency": "EUR", "client_reference": "client-reference", "remittance_information": "remittance-info", "purpose_code": "OTHR", "counterparty_name": "counterparty-name", "counterparty_account": { "iban": "DE95500105173934555844" }, "counterparty_agent": { "bic": "DEUTDEFF" }, "virtual_bank_account_id": "f7b3b3b3-7b3b-4b3b-8b3b-3b3b3b3b3b3b" } } } }, "responses": { "200": { "description": "Bank Transaction", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/json": { "schema": { "title": "Payments - Bank Transaction - Create - Response", "type": "object", "description": "Response returned after recording an incoming bank transaction. Contains the internal transaction `id` and the bank's own `bank_reference`.", "properties": { "id": { "title": "Bank transaction unique identifier", "type": "string", "description": "Bank transaction unique identifier", "format": "uuid" }, "bank_reference": { "type": "string", "description": "Bank reference of the bank transaction (created by the bank to unambiguously identify the bank transaction in the banks systems)" } }, "required": [ "id", "bank_reference" ] }, "example": { "id": "6ffa6b16-2380-4e7a-88b2-ae625c8eef99", "bank_reference": "f2f0ef23-c68d-42c1-a744-8c86f471954b" } } } }, "400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } } }, "x-webhooks": { "Instruments events": { "post": { "operationId": "instrument_event", "summary": "Instruments events", "description": "Instruments events", "tags": [ "Instruments" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Instruments - Callback", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type", "enum": [ "INSTRUMENT.ONBOARDED", "INSTRUMENT.ACTIVATED", "INSTRUMENT.DEACTIVATED", "INSTRUMENT.FRACTIONAL_TRADING_ENABLED", "INSTRUMENT.FRACTIONAL_TRADING_DISABLED", "INSTRUMENT.DATA_CHANGED" ] }, "object": { "type": "object", "properties": { "id": { "title": "Instrument unique identifier.", "type": "string", "description": "Instrument unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "isin": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, "wkn": { "title": "German securities identification code", "type": "string", "description": "German securities identification code known as [Wertpapierkennnummer](https://en.wikipedia.org/wiki/Wertpapierkennnummer).", "pattern": "^[A-HJ-NP-Z0-9]{6}$" }, "name": { "description": "Instrument name", "type": "string", "maxLength": 100 }, "fractional_trading": { "type": "boolean", "description": "Determines whether the platform can handle fractional investments within this instrument." }, "trading_status": { "title": "Instrument trading status", "description": "Instrument trading status\n* ACTIVE - The instrument can currently be traded on the Upvest platform. \n* INACTIVE - The instrument cannot currently be traded on the Upvest platform.", "type": "string", "enum": [ "ACTIVE", "INACTIVE" ] }, "details": { "title": "Details", "type": "object", "description": "Details", "properties": { "distribution_countries": { "title": "Distribution Countries", "description": "Distribution Countries", "type": "array", "items": { "description": "Country code. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "pattern": "^[A-Z]{2}$" } } } } }, "required": [ "id", "name", "fractional_trading", "trading_status", "created_at", "updated_at" ], "additionalProperties": false }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "example": { "id": "de4e9e75-5c74-44c7-b741-9b3e0d85f4de", "created_at": "2022-08-31T17:28:00.00Z", "type": "INSTRUMENT.ACTIVATED", "object": { "id": "123e4567-e89b-12d3-a456-426614174000", "created_at": "2022-03-31T17:28:00.00Z", "updated_at": "2022-08-31T17:28:00.00Z", "isin": "DE0007664005", "wkn": "766400", "name": "Volkswagen (VW) St. Aktie.", "fractional_trading": true, "trading_status": "ACTIVE" }, "webhook_id": "0af63506-289c-4051-8859-4e17ec89b002" } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Users events": { "post": { "operationId": "user_event", "summary": "Users events", "description": "Notifies subscribers of user lifecycle events.\n\nTriggered when a user is created, activated, deactivated, offboarded, or has a data change processed or rejected.\n\nSee the User webhook events guide ([TOL](https://docs.upvest.co/products/tol/guides/users/users_webhooks) / [BYOL](https://docs.upvest.co/products/byol/guides/users/users_webhooks)) for the full list of event types.", "tags": [ "Users" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Users - Callback", "type": "object", "description": "Webhook event payload emitted when a user is created, activated, deactivated, offboarded, or has a data change processed or rejected.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type indicating the user lifecycle change.", "enum": [ "USER.CREATED", "USER.ACTIVATED", "USER.DEACTIVATED", "USER.DATA_CHANGED", "USER.DATA_CHANGE_FAILED", "USER.OFFBOARDING_INITIATED", "USER.OFFBOARDED" ] }, "object": { "description": "The object the event relates to: the user for lifecycle events, or a failure object for `USER.DATA_CHANGE_FAILED` events.", "oneOf": [ { "anyOf": [ { "title": "User (BYOL)", "type": "object", "description": "A user onboarded under the Bring Your Own Licence (BYOL) operating model, where the client holds the regulatory licence.", "properties": { "id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "first_name": { "type": "string", "maxLength": 100, "minLength": 2, "description": "First name(s) of the user. Please include all first and middle names of the user." }, "last_name": { "type": "string", "maxLength": 100, "minLength": 1, "description": "Last name of the user." }, "salutation": { "type": "string", "description": "Salutation of the user used in reports and statements.\n* (empty string) - \n* SALUTATION_MALE - \n* SALUTATION_FEMALE - \n* SALUTATION_FEMALE_MARRIED - \n* SALUTATION_DIVERSE - ", "enum": [ "", "SALUTATION_MALE", "SALUTATION_FEMALE", "SALUTATION_FEMALE_MARRIED", "SALUTATION_DIVERSE" ], "default": "" }, "title": { "type": "string", "description": "Title of the user used in reports and statements.\n* (empty string) - \n* DR - Doctor\n* PROF - Professor\n* PROF_DR - \n* DIPL_ING - Graduate engineer (Diplom-Ingenieur)\n* MAGISTER - ", "enum": [ "", "DR", "PROF", "PROF_DR", "DIPL_ING", "MAGISTER" ], "default": "" }, "birth_date": { "type": "string", "format": "date", "description": "Birth date of the user in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" }, "birth_city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 }, "birth_country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "birth_name": { "type": "string", "maxLength": 100, "description": "If applicable, birth name of the user." }, "decease_date": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "date", "description": "The user's date of death in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" } ] }, "nationalities": { "type": "array", "items": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "minItems": 1, "description": "Nationalities of the user. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)." }, "address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, "postal_address": { "description": "User postal address. Needs to be specified if different to the residential address, otherwise it is automatically populated.", "oneOf": [ { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, { "type": "null" } ] }, "status": { "type": "string", "description": "Status of the user.\n* ACTIVE - \n* INACTIVE - \n* OFFBOARDING - \n* OFFBOARDED - ", "enum": [ "ACTIVE", "INACTIVE", "OFFBOARDING", "OFFBOARDED" ] }, "email": { "type": "string", "format": "email", "maxLength": 100, "description": "Email of the user. Must be a valid email address." }, "branch_id": { "title": "Branch unique identifier.", "type": "string", "description": "Unique identifier of the market the user is onboarded on. Only relevant if the client is operating in different markets and the client is configured accordingly", "format": "uuid" }, "gender": { "title": "Gender", "type": "string", "description": "Gender of the user. Required for users applying for the German pension government bonus.\n* (empty string) - \n* MALE - \n* FEMALE - \n* DIVERSE - ", "enum": [ "", "MALE", "FEMALE", "DIVERSE" ], "default": "" }, "social_security_number": { "title": "Social security number", "type": "string", "description": "The user's assigned social security number (German social insurance number, e.g. `25300972S014`). Required for users applying for the German pension government bonus.", "pattern": "^(\\d{2}(0[1-9]|[12]\\d|3[01])(0[1-9]|1[0-2])\\d{2}[A-Z]\\d{3})?$" }, "tags": { "title": "Tags", "type": "array", "items": { "type": "string", "enum": [ "CLIENT_EMPLOYEE" ] }, "uniqueItems": true, "description": "Labels applied to the user by the tenant. Omitted for users that have no tags.\n* CLIENT_EMPLOYEE - The user is an employee of the tenant.\n\nProviding this field in a data change request replaces the full set of tags; send an empty array to remove all tags." } }, "required": [ "id", "created_at", "updated_at", "first_name", "last_name", "birth_date", "nationalities", "address", "status" ], "additionalProperties": false }, { "title": "User (TOL)", "type": "object", "description": "A user onboarded under the Take Our Licence (TOL) operating model, where Upvest holds the regulatory licence. Includes the details collected during onboarding.", "properties": { "id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "first_name": { "type": "string", "maxLength": 100, "minLength": 2, "description": "First name(s) of the user. Please include all first and middle names of the user." }, "last_name": { "type": "string", "maxLength": 100, "minLength": 1, "description": "Last name of the user." }, "salutation": { "type": "string", "description": "Salutation of the user used in reports and statements.\n* (empty string) - \n* SALUTATION_MALE - \n* SALUTATION_FEMALE - \n* SALUTATION_FEMALE_MARRIED - \n* SALUTATION_DIVERSE - ", "enum": [ "", "SALUTATION_MALE", "SALUTATION_FEMALE", "SALUTATION_FEMALE_MARRIED", "SALUTATION_DIVERSE" ], "default": "" }, "title": { "type": "string", "description": "Title of the user used in reports and statements.\n* (empty string) - \n* DR - Doctor\n* PROF - Professor\n* PROF_DR - \n* DIPL_ING - Graduate engineer (Diplom-Ingenieur)\n* MAGISTER - ", "enum": [ "", "DR", "PROF", "PROF_DR", "DIPL_ING", "MAGISTER" ], "default": "" }, "birth_date": { "type": "string", "format": "date", "description": "Birth date of the user in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" }, "birth_city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 }, "birth_country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "birth_name": { "type": "string", "maxLength": 100, "description": "If applicable, birth name of the user." }, "decease_date": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "date", "description": "The user's date of death in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" } ] }, "nationalities": { "type": "array", "items": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "minItems": 1, "description": "Nationalities of the user. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)." }, "address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, "postal_address": { "description": "User postal address. Needs to be specified if different to the residential address, otherwise it is automatically populated.", "oneOf": [ { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, { "type": "null" } ] }, "status": { "type": "string", "description": "Status of the user.\n* ACTIVE - \n* INACTIVE - \n* OFFBOARDING - \n* OFFBOARDED - ", "enum": [ "ACTIVE", "INACTIVE", "OFFBOARDING", "OFFBOARDED" ] }, "email": { "type": "string", "format": "email", "maxLength": 100, "description": "Email of the user. Must be a valid email address." }, "phone_number": { "type": "string", "pattern": "^([0-9]{8,15})?$", "description": "Phone number of the user. [Phone number E.164 format](https://en.wikipedia.org/wiki/E.164)." }, "fatca": { "type": "object", "description": "The user's FATCA status and when it was confirmed", "properties": { "status": { "type": "boolean", "description": "The user’s FATCA status is true if the user is subject to paying taxes in the US, otherwise it can be set to false." }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp at which the user confirmed their FATCA status. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" } }, "required": [ "status", "confirmed_at" ] }, "terms_and_conditions": { "description": "Terms & Conditions will be needed for all users unless they are a child user or only a user on a business.", "type": "object", "properties": { "consent_document_id": { "title": "Consent unique identifier.", "type": "string", "description": "Consent unique identifier.", "format": "uuid" }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp at which the user consented to the terms & conditions. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" } }, "required": [ "consent_document_id", "confirmed_at" ] }, "data_privacy_and_sharing_agreement": { "description": "Data privacy agreement will be needed for all users unless they are a child user or only a user on a business.", "type": "object", "properties": { "consent_document_id": { "title": "Consent unique identifier.", "type": "string", "description": "Consent unique identifier.", "format": "uuid" }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp at which the user consented to the data sharing agreement. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" } }, "required": [ "consent_document_id", "confirmed_at" ] }, "branch_id": { "title": "Branch unique identifier.", "type": "string", "description": "Unique identifier of the market the user is onboarded on. Only relevant if the client is operating in different markets and the client is configured accordingly", "format": "uuid" }, "gender": { "title": "Gender", "type": "string", "description": "Gender of the user. Required for users applying for the German pension government bonus.\n* (empty string) - \n* MALE - \n* FEMALE - \n* DIVERSE - ", "enum": [ "", "MALE", "FEMALE", "DIVERSE" ], "default": "" }, "social_security_number": { "title": "Social security number", "type": "string", "description": "The user's assigned social security number (German social insurance number, e.g. `25300972S014`). Required for users applying for the German pension government bonus.", "pattern": "^(\\d{2}(0[1-9]|[12]\\d|3[01])(0[1-9]|1[0-2])\\d{2}[A-Z]\\d{3})?$" }, "tags": { "title": "Tags", "type": "array", "items": { "type": "string", "enum": [ "CLIENT_EMPLOYEE" ] }, "uniqueItems": true, "description": "Labels applied to the user by the tenant. Omitted for users that have no tags.\n* CLIENT_EMPLOYEE - The user is an employee of the tenant.\n\nProviding this field in a data change request replaces the full set of tags; send an empty array to remove all tags." } }, "required": [ "id", "created_at", "updated_at", "first_name", "last_name", "birth_date", "nationalities", "address", "status" ], "additionalProperties": false } ] }, { "title": "Webhook - Users - Callback", "type": "object", "description": "Webhook event object describing a failed user data change, including the reason for the failure.", "properties": { "user_id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "reason": { "type": "string", "maxLength": 100, "description": "The reason why the data change failed." } }, "required": [ "user_id", "reason" ], "additionalProperties": false } ] }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "examples": { "BYOL": { "summary": "BYOL user event", "value": { "id": "2df83681-6a42-4837-a554-a8197335bcfa", "created_at": "2021-11-19T13:06:51.980159529Z", "type": "USER.CREATED", "object": { "created_at": "2021-11-22T09:04:42Z", "updated_at": "2021-11-22T09:04:42Z", "first_name": "Jane", "last_name": "Doe", "email": "jane.doe@example.com", "salutation": "SALUTATION_FEMALE", "title": "PROF", "birth_date": "1990-01-01", "birth_city": "Berlin", "birth_country": "DE", "birth_name": "Smith", "decease_date": null, "nationalities": [ "DE", "CH" ], "address": { "address_line1": "Torstrasse", "address_line2": "12a", "city": "Berlin", "country": "DE", "postcode": "10115", "state": "BE" }, "id": "a1752f00-93d5-4b77-a148-959cd315581b", "postal_address": { "address_line1": "Thorstrasse", "address_line2": "123", "city": "Berlin", "country": "DE", "postcode": "10115", "state": "BE" }, "status": "ACTIVE", "branch_id": "e6373bfa-ff12-4004-8de9-747ac96764da", "tags": [ "CLIENT_EMPLOYEE" ] }, "webhook_id": "1b097e06-8a14-4181-b72a-de0972a3c57b" } }, "TOL": { "summary": "TOL user event", "value": { "id": "2df83681-6a42-4837-a554-a8197335bcfa", "created_at": "2021-11-22T09:04:42Z", "type": "USER.CREATED", "object": { "created_at": "2021-11-22T09:04:42Z", "updated_at": "2021-11-22T09:04:42Z", "first_name": "Jane", "last_name": "Doe", "salutation": "SALUTATION_FEMALE", "title": "PROF", "birth_date": "1990-01-01", "birth_city": "Berlin", "birth_country": "DE", "birth_name": "Smith", "decease_date": null, "nationalities": [ "DE", "CH" ], "address": { "address_line1": "Torstrasse", "address_line2": "12a", "city": "Berlin", "country": "DE", "postcode": "10115", "state": "BE" }, "id": "a1752f00-93d5-4b77-a148-959cd315581b", "postal_address": { "address_line1": "Thorstrasse", "address_line2": "123", "city": "Berlin", "country": "DE", "postcode": "10115", "state": "BE" }, "status": "ACTIVE", "data_privacy_and_sharing_agreement": { "confirmed_at": "2021-02-03T17:14:46Z", "consent_document_id": "7ab0fc5c-8157-4acd-b02d-6ccda0e81dec" }, "email": "janedoe@example.com", "fatca": { "confirmed_at": "2020-02-03T17:14:46Z", "status": false }, "phone_number": "0123456789", "terms_and_conditions": { "confirmed_at": "2020-02-03T17:14:46Z", "consent_document_id": "62814307-f14b-40af-bc66-5942a549a759" }, "branch_id": "a1752f00-93d5-4b77-a148-959cd315581b", "tags": [ "CLIENT_EMPLOYEE" ] }, "webhook_id": "1b097e06-8a14-4181-b72a-de0972a3c57b" } } } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "User checks events": { "post": { "operationId": "user_checks_event", "summary": "User checks events", "description": "Notifies subscribers of user check lifecycle events.\n\nTriggered when a check is created, passed, or failed for a user.\n\nSee the Conducting regulatory checks guide ([TOL](https://docs.upvest.co/products/tol/guides/users/users_onboarding_checks) / [BYOL](https://docs.upvest.co/products/byol/guides/users/users_onboarding_checks)) for check types.", "tags": [ "User Checks" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - User Checks - Callback", "type": "object", "description": "Webhook event payload emitted when a user check is created, passed, or failed.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type.\n* USER_CHECK.CREATED — a check has been created for the user.\n* USER_CHECK.PASSED — the check has passed.\n* USER_CHECK.FAILED — the check has failed.", "enum": [ "USER_CHECK.CREATED", "USER_CHECK.PASSED", "USER_CHECK.FAILED" ] }, "object": { "title": "User Check", "description": "A check conducted for a user: KYC, proof of residence, instrument fit, compliance, guardian, or self-assessment.", "oneOf": [ { "title": "User Check - Know your customer", "type": "object", "description": "The KYC (Know your customer) check is completed by the client sharing the valid and relevant KYC data for the user.", "properties": { "id": { "title": "User Check unique identifier", "type": "string", "description": "User Check unique identifier.", "format": "uuid" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "type": { "type": "string", "default": "KYC", "description": "The type of check must be “KYC”." }, "check_confirmed_at": { "type": "string", "format": "date-time", "description": "Completion date and time of the KYC check. Must not be older than 24 months." }, "data_download_link": { "type": "string", "format": "url", "maxLength": 1000, "description": "Download URL for the KYC evidence file. The file size must not exceed 250 MB." }, "document_type": { "type": "string", "description": "The type of document used in the KYC process.\n* PASSPORT - Passport\n* ID_CARD - National Identification document\n* RESIDENCE_PERMIT - Residence Permit\n* DRIVING_LICENSE - Driving License\n* TWO_PLUS_TWO_VERIFICATION_PROOF - Two plus two verification proof (for GB residence users only)\n", "enum": [ "PASSPORT", "ID_CARD", "RESIDENCE_PERMIT", "DRIVING_LICENSE", "TWO_PLUS_TWO_VERIFICATION_PROOF" ] }, "document_expiration_date": { "type": "string", "format": "date", "description": "Expiration date of the document used in KYC process in YYYY-MM-DD format.\n\n**The field is required for the following document types:**\n* PASSPORT\n* ID_CARD\n* RESIDENCE_PERMIT\n* DRIVING_LICENSE\n" }, "nationality": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Issuing country of the document used in the KYC process. [ISO 3166 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).\n\n**The field is required for the following document types:**\n* PASSPORT\n* ID_CARD\n* RESIDENCE_PERMIT\n* DRIVING_LICENSE\n" }, "status": { "type": "string", "description": "Final status of the KYC check.\n* IN_PROGRESS - KYC check is in progress\n* PASSED - KYC check passed\n* FAILED - KYC check failed", "enum": [ "IN_PROGRESS", "PASSED", "FAILED" ] }, "provider": { "type": "string", "maxLength": 100, "description": "Provider that was used to perform the KYC check." }, "method": { "type": "string", "description": "Method used for AML-compliant KYC process\n* VIDEO_ID - Video identification\n* IN_PERSON_ID - In-person identification at the post office or the client's outlet\n* ELECTRONIC_ID - Advanced electronic identification methods (namely German eID)\n* LIVENESS_PHOTO_ID - Photos and security features of the identification document in combination with a video-based liveness check (residence country must not be Germany in this case)\n* QUALIFIED_ELECTRONIC_SIGNATURE_WITH_TX - Qualified electronic signature accompanied by a bank transaction for verification\n* TWO_PLUS_TWO_VERIFICATION - A method of verifying identity by matching at least two personal details from two separate sources (for GB residence users only)\n* ID_COLLECTION - The identification document of the user is collected but has not undergone verification", "enum": [ "VIDEO_ID", "IN_PERSON_ID", "ELECTRONIC_ID", "LIVENESS_PHOTO_ID", "QUALIFIED_ELECTRONIC_SIGNATURE_WITH_TX", "TWO_PLUS_TWO_VERIFICATION", "ID_COLLECTION" ] }, "confirmed_address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, "kyc_update": { "type": "boolean", "description": "Marks this check as a KYC refresh/update as opposed to an initial record." } }, "required": [ "id", "user_id", "type", "check_confirmed_at", "data_download_link", "document_type", "status", "provider", "method" ], "additionalProperties": false }, { "title": "User Check - Proof of Residency", "type": "object", "description": "The PoR (Proof of residency) check is completed by the client sharing a valid PoR document, if not fulfilled by the KYC check.", "properties": { "id": { "title": "User Check unique identifier", "type": "string", "description": "User Check unique identifier.", "format": "uuid" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "type": { "type": "string", "default": "POR", "description": "The type of check must be POR." }, "check_confirmed_at": { "type": "string", "format": "date-time", "description": "Completion date and time of the PoR check." }, "issuance_date": { "type": "string", "format": "date", "description": "Issuance date in YYYY-MM-DD format." }, "data_download_link": { "type": "string", "format": "url", "maxLength": 1000, "description": "Download URL for the PoR evidence file. The file size must not exceed 250 MB." }, "document_type": { "type": "string", "description": "The type of document used in the PoR process. Maximum age of the document is 12 months (stated on the document) applicable for: Utility bills (water, gas, electricity), Telephone bills (only landline), Internet bills, Bank account statements. Documents that need to be still valid - Registration certificate (must be valid and issued within the past 5 years), Residence permit e.g. Blue Card (as long as valid and contains the registration address), ID Card that contains the registration address.\n* UTILITY_BILL - \n* TELEPHONE_BILL - \n* INTERNET_BILL - \n* BANK_STATEMENT - \n* REGISTRATION_CERT - \n* RESIDENCE_PERMIT - \n* ID_CARD - \n* PASSPORT - ", "enum": [ "UTILITY_BILL", "TELEPHONE_BILL", "INTERNET_BILL", "BANK_STATEMENT", "REGISTRATION_CERT", "RESIDENCE_PERMIT", "ID_CARD", "PASSPORT" ] }, "status": { "type": "string", "description": "Final status of the PoR check.\n* IN_PROGRESS - \n* PASSED - \n* FAILED - ", "enum": [ "IN_PROGRESS", "PASSED", "FAILED" ] }, "confirmed_address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] } }, "required": [ "id", "user_id", "type", "check_confirmed_at", "issuance_date", "data_download_link", "document_type", "status", "confirmed_address" ], "additionalProperties": false }, { "title": "User Check - Instrument fit", "type": "object", "description": "Instrument fit check is completed by the client providing the user's answers to the instrument appropriateness or suitability questionnaire.", "properties": { "id": { "title": "User Check unique identifier", "type": "string", "description": "User Check unique identifier.", "format": "uuid" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "type": { "type": "string", "default": "INSTRUMENT_FIT", "description": "The type of check must be INSTRUMENT_FIT." }, "check_confirmed_at": { "type": "string", "format": "date-time", "description": "Completion date and time of the instrument fit check." }, "status": { "type": "string", "description": "Final status of the instrument fit check.\n* IN_PROGRESS - Instrument fit check is in progress\n* PASSED - Instrument fit check passed\n* FAILED - Instrument fit check failed", "enum": [ "IN_PROGRESS", "PASSED", "FAILED" ] }, "instrument_suitability": { "type": "object", "description": "Outcome of the user's instrument suitability assessment.", "properties": { "suitability": { "type": "boolean", "description": "Did the user go through a suitability assessment and the outcome indicated suitability." } }, "required": [ "suitability" ] } }, "required": [ "id", "user_id", "type", "check_confirmed_at", "status", "instrument_suitability" ], "additionalProperties": false }, { "title": "User Check - Compliance", "type": "object", "description": "A compliance check conducted by Upvest for a user, including the check and user identifiers.", "properties": { "id": { "title": "User Check unique identifier", "type": "string", "description": "User Check unique identifier.", "format": "uuid" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "type": { "type": "string", "default": "COMPLIANCE", "description": "The type of check must be COMPLIANCE." }, "status": { "type": "string", "description": "Final status of the COMPLIANCE check.\n* IN_PROGRESS - Compliance check is in progress\n* PASSED - Compliance check passed\n* FAILED - Compliance check failed", "enum": [ "IN_PROGRESS", "PASSED", "FAILED" ] }, "check_confirmed_at": { "type": "string", "format": "date-time", "description": "Completion date and time of the COMPLIANCE check." } }, "required": [ "id", "user_id", "type", "check_confirmed_at" ], "additionalProperties": false }, { "title": "User Check - Guardian", "type": "object", "description": "The Guardian check is completed by the client providing documentation proving the guardian relationship with the child user.", "properties": { "id": { "title": "User Check unique identifier", "type": "string", "description": "User Check unique identifier.", "format": "uuid" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "type": { "type": "string", "default": "GUARDIAN", "description": "The type of check must be “GUARDIAN“." }, "check_confirmed_at": { "type": "string", "format": "date-time", "description": "Completion date and time of the PoR check." }, "role_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the role that this guardian check is associated with." }, "document_type": { "type": "string", "description": "The type of document used in the Guardian check.\n* BIRTH_CERTIFICATE - Birth certificate proving guardian relationship", "enum": [ "BIRTH_CERTIFICATE" ] }, "data_download_link": { "type": "string", "format": "url", "maxLength": 1000, "description": "Download URL for the guardian evidence file. The file size must not exceed 250 MB." }, "status": { "type": "string", "description": "Final status of the Guardian check.\n* IN_PROGRESS - Guardian check is in progress\n* PASSED - Guardian check passed\n* FAILED - Guardian check failed", "enum": [ "IN_PROGRESS", "PASSED", "FAILED" ] } }, "required": [ "id", "user_id", "type", "role_id", "document_type", "data_download_link", "status" ], "additionalProperties": false } ] }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "example": { "id": "38fc59d0-fc42-46ef-9512-824773219b2e", "created_at": "2021-11-19T13:06:57.820371265Z", "type": "USER_CHECK.PASSED", "object": { "check_confirmed_at": "2021-08-02T15:04:05Z", "data_download_link": "https://storage.cloud.google.com/upvest-mock-documents/Test_KYC_documents.zip", "document_expiration_date": "2028-01-02", "document_type": "PASSPORT", "id": "32cbb9a2-dd3b-4e60-a5af-9b41460049dc", "user_id": "7b39529a-e68c-4688-8242-7549d10d6084", "method": "VIDEO_ID", "nationality": "RU", "provider": "IDNOW", "status": "PASSED", "type": "KYC" }, "webhook_id": "1b097e06-8a14-4181-b72a-de0972a3c57b" } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Role events": { "post": { "operationId": "role_event", "summary": "Role events", "description": "Notifies subscribers of role lifecycle events.\n\nTriggered when a role is created, activated, or deactivated.\n\nSee the User roles guide ([TOL](https://docs.upvest.co/products/tol/guides/users/users_onboarding_roles) / [BYOL](https://docs.upvest.co/products/byol/guides/users/users_onboarding_roles)) for role types.", "tags": [ "Roles" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Roles - Callback", "type": "object", "description": "Webhook event payload emitted when a role is created, activated, or deactivated.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type.\n* `ROLE.CREATED` — A role has been created.\n* `ROLE.ACTIVATED` — A role has become active.\n* `ROLE.DEACTIVATED` — A role has been deactivated.", "enum": [ "ROLE.CREATED", "ROLE.ACTIVATED", "ROLE.DEACTIVATED" ] }, "object": { "description": "The role the event relates to — either an account group role or a business role.", "oneOf": [ { "title": "Account Group Role", "type": "object", "description": "Role assignment for an account group.", "properties": { "id": { "type": "string", "description": "Unique identifier for the role.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "entity_type": { "type": "string", "default": "ACCOUNT_GROUP", "description": "The entity type; must be `ACCOUNT_GROUP` for account group roles." }, "entity_id": { "title": "Entity unique identifier.", "type": "string", "description": "Unique identifier of the entity a role is attached to.", "format": "uuid" }, "role_type": { "type": "string", "description": "Role type for an account group.\n* `OWNER` — The user owns the account group.\n* `GUARDIAN` — The user is a legal custodian of a child account group.\n* `CHILD` — The user is the child beneficiary of a child account group.", "enum": [ "OWNER", "GUARDIAN", "CHILD" ] }, "custody_type": { "type": "string", "description": "Custody type for child account groups.\n* `SOLE_CUSTODY` — A single guardian has custody of the child account group.\n* `JOINT_CUSTODY` — Multiple guardians are required for the child account group.", "enum": [ "SOLE_CUSTODY", "JOINT_CUSTODY" ] }, "status": { "type": "string", "description": "Status of the role assignment.\n* `PENDING` — The role has been created but is not yet active.\n* `ACTIVE` — The role is active.\n* `DEACTIVATED` — The role has been deactivated and cannot be reactivated.", "enum": [ "PENDING", "ACTIVE", "DEACTIVATED" ] } }, "required": [ "id", "created_at", "updated_at", "user_id", "entity_type", "entity_id", "role_type", "status" ], "additionalProperties": false }, { "title": "Business Role", "type": "object", "description": "Role assignment for a business entity.", "properties": { "id": { "type": "string", "description": "Unique identifier for the role.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "entity_type": { "type": "string", "default": "BUSINESS", "description": "The entity type; must be `BUSINESS` for business roles." }, "entity_id": { "title": "Entity unique identifier.", "type": "string", "description": "Unique identifier of the entity a role is attached to.", "format": "uuid" }, "role_type": { "type": "string", "description": "Role type for a business entity.\n* `LEGAL_REPRESENTATIVE` — The user is a legal representative of the business.\n* `AUTHORISED_SIGNATORY` — The user is authorised to sign documents and make commitments on behalf of the business.\n* `ULTIMATE_BENEFICIAL_OWNER` — The user ultimately owns or controls the business.\n* `CONTRACTING_EXECUTIVE` — The user is able to enter into contracts on behalf of the business.\n* `TRADER` — The user is authorised to place orders on behalf of the business.\n* `SOLE_TRADER` — The user places orders on behalf of a sole trader entity.", "enum": [ "LEGAL_REPRESENTATIVE", "AUTHORISED_SIGNATORY", "ULTIMATE_BENEFICIAL_OWNER", "CONTRACTING_EXECUTIVE", "TRADER", "SOLE_TRADER" ] }, "status": { "type": "string", "description": "Status of the role assignment.\n* `PENDING` — The role has been created but is not yet active.\n* `ACTIVE` — The role is active.\n* `DEACTIVATED` — The role has been deactivated and cannot be reactivated.", "enum": [ "PENDING", "ACTIVE", "DEACTIVATED" ] } }, "required": [ "id", "created_at", "updated_at", "user_id", "entity_type", "entity_id", "role_type", "status" ], "additionalProperties": false } ] }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "examples": { "Account Group": { "summary": "Account Group role event", "value": { "id": "2df83681-6a42-4837-a554-a8197335bcfa", "created_at": "2021-11-22T09:04:42Z", "type": "ROLE.CREATED", "object": { "id": "baf05386-0459-4e8c-9ac9-cd6442f194dd", "created_at": "2025-04-01T10:11:40Z", "updated_at": "2025-04-01T10:11:40Z", "user_id": "9c36af78-91a0-4174-a515-fc81214e3dab", "entity_type": "ACCOUNT_GROUP", "entity_id": "413715f2-5401-4b97-8055-034a6b879f8c", "role_type": "GUARDIAN", "custody_type": "JOINT_CUSTODY", "status": "PENDING" }, "webhook_id": "1b097e06-8a14-4181-b72a-de0972a3c57b" } }, "Business": { "summary": "Business role event", "value": { "id": "2df83681-6a42-4837-a554-a8197335bcfa", "created_at": "2021-11-22T09:04:42Z", "type": "ROLE.ACTIVATED", "object": { "id": "e8b5a51d-8baf-4d0b-8a3b-8f8f8f8f8f8f", "created_at": "2025-04-01T10:11:40Z", "updated_at": "2025-04-01T10:11:40Z", "user_id": "0d10c51f-33f2-4399-b8ab-92ec84e6b2f0", "entity_type": "BUSINESS", "entity_id": "6deb17c8-950e-4377-b500-5522af5ef712", "role_type": "LEGAL_REPRESENTATIVE", "status": "ACTIVE" }, "webhook_id": "1b097e06-8a14-4181-b72a-de0972a3c57b" } } } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Business events": { "post": { "operationId": "business_event", "summary": "Business events", "description": "Notifies subscribers of business lifecycle events.\n\nTriggered when a business is created, activated, deactivated, offboarded, or has a data change processed or rejected.\n\nSee the Business accounts guide ([TOL](https://docs.upvest.co/products/tol/guides/accounts/businesses_overview) / [BYOL](https://docs.upvest.co/products/byol/guides/accounts/businesses_overview)) for business account types.", "tags": [ "Businesses" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Businesses - Callback", "type": "object", "description": "Webhook event payload emitted when a business is created, activated, deactivated, offboarded, or has a data change processed or rejected.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type indicating the business lifecycle change", "enum": [ "BUSINESS.CREATED", "BUSINESS.ACTIVATED", "BUSINESS.DEACTIVATED", "BUSINESS.DATA_CHANGED", "BUSINESS.DATA_CHANGE_FAILED", "BUSINESS.OFFBOARDING_INITIATED", "BUSINESS.OFFBOARDED" ] }, "object": { "description": "The object the event relates to: the business for lifecycle events, or a failure object for `BUSINESS.DATA_CHANGE_FAILED` events", "oneOf": [ { "title": "Business Event", "oneOf": [ { "type": "object", "description": "Schema for business company information.", "properties": { "id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "contact_email": { "type": "string", "format": "email", "description": "Contact email address of the business." }, "registered_address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, "registration_number": { "type": "string", "description": "Registration number of the business." }, "tax_information": { "type": "object", "properties": { "tax_country_code": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "tax_identification_type": { "type": "string", "enum": [ "STEUERNUMMER", "WIRTSCHAFTSIDENTIFIKATIONSNUMMER" ], "description": "Type of tax identification used by the business." }, "tax_identification_number": { "type": "string", "description": "Tax identification number of the business.\n\nWhen `tax_identification_type` is `STEUERNUMMER`, the value is 10 or 11 digits, provided either as bare digits or in a state-specific slash-grouped layout. Slashes are all-or-nothing and must appear at the grouping positions:\n\n| Format | Grouping | Example |\n| --- | --- | --- |\n| Bare digits | 10 or 11 digits | `1234567890`, `12345678901` |\n| North Rhine-Westphalia | 3/4/4 | `133/8150/8159` |\n| Bavaria | 3/3/5 | `181/815/08155` |\n| Standard 10-digit | 2/3/5 | `24/815/08151` |\n| Alternative 10-digit (Berlin, Bremen, Lower Saxony) | 3/3/4 | `181/815/0815` |\n\nWhen `tax_identification_type` is `WIRTSCHAFTSIDENTIFIKATIONSNUMMER`, the value is `DE` followed by 9 digits, with an optional 5-digit distinguishing feature (for example `DE123456789` or `DE123456789-00001`)." }, "is_resident_in_multiple_tax_jurisdictions": { "type": "boolean", "description": "Indicates if the business is resident in multiple tax jurisdictions." }, "is_subject_to_fatca": { "type": "boolean", "description": "Indicates if the business is subject to FATCA regulations." } }, "required": [ "tax_country_code", "tax_identification_type", "tax_identification_number", "is_resident_in_multiple_tax_jurisdictions", "is_subject_to_fatca" ], "description": "Tax information of the business." }, "business_type": { "default": "LIMITED_LIABILITY_COMPANY", "description": "Type of the business." }, "identification": { "type": "object", "properties": { "company_name": { "type": "string", "description": "Name of the company." }, "incorporation_date": { "type": "string", "description": "Incorporation date of the business in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" }, "district_court": { "type": "string", "minLength": 1, "maxLength": 40, "description": "District court where the company is registered." }, "legal_designation": { "type": "string", "enum": [ "GESELLSCHAFT_MIT_BESCHRAENKTER_HAFTUNG", "UNTERNEHMERGESELLSCHAFT", "AKTIENGESELLSCHAFT" ], "description": "Country specific legal designation of the company.\nNote: `AKTIENGESELLSCHAFT` businesses cannot be created via the API; please contact Upvest support before onboarding such a business." }, "legal_entity_identifier": { "type": "string", "pattern": "^[A-Z0-9]{18}[0-9]{2}$", "description": "Legal Entity Identifier (LEI) of the company. A 20-character alphanumeric code as defined by [ISO 17442](https://en.wikipedia.org/wiki/Legal_Entity_Identifier)." }, "common_reporting_standards": { "type": "object", "properties": { "is_passive_non_financial_entity": { "type": "boolean", "description": "Indicates if the company is a passive non-financial entity." }, "is_financial_institution": { "type": "boolean", "description": "Indicates if the company is a financial institution." } }, "required": [ "is_passive_non_financial_entity", "is_financial_institution" ], "description": "Common reporting standards information." } }, "required": [ "company_name", "incorporation_date", "district_court", "legal_designation", "common_reporting_standards" ], "description": "Identification information of the business." }, "terms_and_conditions": { "type": "object", "properties": { "consent_document_id": { "type": "string", "format": "uuid", "description": "UUID of the consent document." }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the terms and conditions were confirmed." } }, "required": [ "consent_document_id", "confirmed_at" ], "description": "Terms and conditions agreement." }, "data_privacy_and_sharing_agreement": { "type": "object", "properties": { "consent_document_id": { "type": "string", "format": "uuid", "description": "UUID of the data privacy and sharing agreement document." }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the data privacy and sharing agreement was confirmed." } }, "required": [ "consent_document_id", "confirmed_at" ], "description": "Data privacy and sharing agreement." }, "status": { "enum": [ "ACTIVE", "INACTIVE", "OFFBOARDING", "OFFBOARDED" ], "description": "Status of the business.\n* ACTIVE - \n* INACTIVE - \n* OFFBOARDING - \n* OFFBOARDED - " } }, "required": [ "id", "contact_email", "registered_address", "registration_number", "tax_information", "business_type", "identification", "terms_and_conditions", "data_privacy_and_sharing_agreement", "status", "created_at", "updated_at" ], "additionalProperties": false }, { "type": "object", "description": "Schema for business company information.", "properties": { "id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "contact_email": { "type": "string", "format": "email", "description": "Contact email address of the business." }, "registered_address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] }, "registration_number": { "type": "string", "description": "Registration number of the business." }, "tax_information": { "type": "object", "properties": { "tax_country_code": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "tax_identification_type": { "type": "string", "enum": [ "STEUERNUMMER", "WIRTSCHAFTSIDENTIFIKATIONSNUMMER" ], "description": "Type of tax identification used by the business." }, "tax_identification_number": { "type": "string", "description": "Tax identification number of the business.\n\nWhen `tax_identification_type` is `STEUERNUMMER`, the value is 10 or 11 digits, provided either as bare digits or in a state-specific slash-grouped layout. Slashes are all-or-nothing and must appear at the grouping positions:\n\n| Format | Grouping | Example |\n| --- | --- | --- |\n| Bare digits | 10 or 11 digits | `1234567890`, `12345678901` |\n| North Rhine-Westphalia | 3/4/4 | `133/8150/8159` |\n| Bavaria | 3/3/5 | `181/815/08155` |\n| Standard 10-digit | 2/3/5 | `24/815/08151` |\n| Alternative 10-digit (Berlin, Bremen, Lower Saxony) | 3/3/4 | `181/815/0815` |\n\nWhen `tax_identification_type` is `WIRTSCHAFTSIDENTIFIKATIONSNUMMER`, the value is `DE` followed by 9 digits, with an optional 5-digit distinguishing feature (for example `DE123456789` or `DE123456789-00001`)." }, "is_resident_in_multiple_tax_jurisdictions": { "type": "boolean", "description": "Indicates if the business is resident in multiple tax jurisdictions." }, "is_subject_to_fatca": { "type": "boolean", "description": "Indicates if the business is subject to FATCA regulations." } }, "required": [ "tax_country_code", "tax_identification_type", "tax_identification_number", "is_resident_in_multiple_tax_jurisdictions", "is_subject_to_fatca" ], "description": "Tax information of the business." }, "business_type": { "type": "string", "default": "SOLE_TRADER", "description": "Type of the business. Always `SOLE_TRADER` for sole trader businesses." }, "identification": { "type": "object", "properties": { "company_name": { "type": "string", "description": "Name of the sole trader business." }, "incorporation_date": { "type": "string", "description": "Incorporation date of the business in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" }, "legal_designation": { "type": "string", "enum": [ "EINZELUNTERNEHMER", "FREIBERUFLER", "EINGETRAGENER_KAUFMANN", "EINGETRAGENE_KAUFFRAU" ], "description": "Country specific legal designation of the sole trader business." } }, "required": [ "company_name", "legal_designation" ], "description": "Identification information of the sole trader business." }, "terms_and_conditions": { "type": "object", "properties": { "consent_document_id": { "type": "string", "format": "uuid", "description": "UUID of the consent document." }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the terms and conditions were confirmed." } }, "required": [ "consent_document_id", "confirmed_at" ], "description": "Terms and conditions agreement." }, "data_privacy_and_sharing_agreement": { "type": "object", "properties": { "consent_document_id": { "type": "string", "format": "uuid", "description": "UUID of the data privacy and sharing agreement document." }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the data privacy and sharing agreement was confirmed." } }, "required": [ "consent_document_id", "confirmed_at" ], "description": "Data privacy and sharing agreement." }, "status": { "enum": [ "ACTIVE", "INACTIVE", "OFFBOARDING", "OFFBOARDED" ], "description": "Status of the business.\n* ACTIVE - \n* INACTIVE - \n* OFFBOARDING - \n* OFFBOARDED - " } }, "required": [ "id", "created_at", "updated_at", "contact_email", "registered_address", "tax_information", "business_type", "identification", "terms_and_conditions", "data_privacy_and_sharing_agreement", "status" ], "additionalProperties": false } ] }, { "title": "Businesses Update Failed Event", "type": "object", "description": "Webhook event object describing a failed business data change, including the reason for the failure.", "properties": { "business_id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "reason": { "type": "string", "maxLength": 100, "description": "The reason why the data change failed." } }, "required": [ "business_id", "reason" ], "additionalProperties": false } ] }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "examples": { "Company": { "summary": "Company business event", "value": { "id": "2df83681-6a42-4837-a554-a8197335bcfa", "created_at": "2021-11-22T09:04:42Z", "type": "BUSINESS.CREATED", "object": { "id": "a9a72268-4f3c-4de2-abb9-a553a3bb7608", "created_at": "2024-10-24T14:14:22Z", "updated_at": "2024-10-24T14:14:22Z", "contact_email": "acme.corporation@example.com", "registered_address": { "address_line1": "110", "address_line2": "Schonhauser Allee", "postcode": "101110", "city": "Berlin", "state": "BE", "country": "DE" }, "registration_number": "111221111", "tax_information": { "tax_country_code": "DE", "tax_identification_type": "STEUERNUMMER", "tax_identification_number": "12345678901", "is_resident_in_multiple_tax_jurisdictions": false, "is_subject_to_fatca": false }, "business_type": "LIMITED_LIABILITY_COMPANY", "identification": { "company_name": "Acme Corporation", "incorporation_date": "2000-10-10", "district_court": "Berlin Charlottenburg", "legal_designation": "GESELLSCHAFT_MIT_BESCHRAENKTER_HAFTUNG", "legal_entity_identifier": "213800K98H63P249S632", "common_reporting_standards": { "is_passive_non_financial_entity": false, "is_financial_institution": false } }, "terms_and_conditions": { "consent_document_id": "6a163d14-5b3d-48be-ac90-43314e96be71", "confirmed_at": "2024-10-24T14:14:22Z" }, "data_privacy_and_sharing_agreement": { "consent_document_id": "fa2227c3-2b29-47e1-84da-996d09517edc", "confirmed_at": "2024-10-24T14:16:22Z" }, "status": "ACTIVE" }, "webhook_id": "1b097e06-8a14-4181-b72a-de0972a3c57b" } }, "Sole Trader": { "summary": "Sole Trader business event", "value": { "id": "2df83681-6a42-4837-a554-a8197335bcfa", "created_at": "2021-11-22T09:04:42Z", "type": "BUSINESS.CREATED", "object": { "id": "a9a72268-4f3c-4de2-abb9-a553a3bb7608", "created_at": "2024-10-24T14:14:22Z", "updated_at": "2024-10-24T14:14:22Z", "contact_email": "acme.corporation@example.com", "registered_address": { "address_line1": "110", "address_line2": "Schonhauser Allee", "postcode": "101110", "city": "Berlin", "state": "BE", "country": "DE" }, "registration_number": "111221111", "tax_information": { "tax_country_code": "DE", "tax_identification_type": "STEUERNUMMER", "tax_identification_number": "12345678901", "is_resident_in_multiple_tax_jurisdictions": false, "is_subject_to_fatca": false }, "business_type": "SOLE_TRADER", "identification": { "company_name": "Max Mustermann - Web Design", "incorporation_date": "2000-10-10", "legal_designation": "EINZELUNTERNEHMER" }, "terms_and_conditions": { "consent_document_id": "6a163d14-5b3d-48be-ac90-43314e96be71", "confirmed_at": "2024-10-24T14:14:22Z" }, "data_privacy_and_sharing_agreement": { "consent_document_id": "fa2227c3-2b29-47e1-84da-996d09517edc", "confirmed_at": "2024-10-24T14:16:22Z" }, "status": "ACTIVE" }, "webhook_id": "1b097e06-8a14-4181-b72a-de0972a3c57b" } } } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Business checks events": { "post": { "operationId": "business_checks_event", "summary": "Business checks events", "description": "Notifies subscribers of business check lifecycle events.\n\nTriggered when a check is created, passed, or failed for a business.\n\nSee the Creating a corporate business account guide ([TOL](https://docs.upvest.co/products/tol/guides/accounts/businesses_implementing_corporate) / [BYOL](https://docs.upvest.co/products/byol/guides/accounts/businesses_implementing_corporate)) for the KYB check process.", "tags": [ "Business Checks" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Business Checks - Callback", "type": "object", "description": "Webhook event payload emitted when a business check is created, passed, or failed.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type.\n* BUSINESS_CHECK.CREATED — a check has been created for the business.\n* BUSINESS_CHECK.PASSED — the check has passed.\n* BUSINESS_CHECK.FAILED — the check has failed.", "enum": [ "BUSINESS_CHECK.CREATED", "BUSINESS_CHECK.PASSED", "BUSINESS_CHECK.FAILED" ] }, "object": { "title": "Business Check", "description": "A check conducted for a business, either a KYB check or a self-assessment.", "oneOf": [ { "title": "Business Check - KYB", "type": "object", "description": "A Know Your Business (KYB) check for a business, recording confirmation timestamps and a link to the submitted documents.", "properties": { "id": { "title": "Business Check unique identifier", "type": "string", "description": "Business Check unique identifier.", "format": "uuid" }, "business_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "type": { "type": "string", "default": "KYB", "description": "The type of check must be “KYB”." }, "originally_confirmed_at": { "type": "string", "format": "date-time", "description": "The date and time when the check was first confirmed. When the check has only been confirmed once, this value is the same as check_confirmed_at. When renewing KYB check, this value remains the same as when the check was first confirmed." }, "check_confirmed_at": { "type": "string", "format": "date-time", "description": "The date and time when the check was latest confirmed" }, "status": { "type": "string", "description": "Final status of the business check.\n* IN_PROGRESS - Check is in progress\n* PASSED - Check passed\n* FAILED - Check failed", "enum": [ "IN_PROGRESS", "PASSED", "FAILED" ] }, "data_download_link": { "type": "string", "format": "uri", "description": "Link to download the document bundle submitted for the KYB check" }, "document_type": { "type": "string", "default": "KYB_DOCUMENTS", "description": "Type of the document bundle. Always `KYB_DOCUMENTS`" } }, "required": [ "id", "business_id", "type", "originally_confirmed_at", "check_confirmed_at", "status", "data_download_link", "document_type" ] }, { "title": "Business Check - Business Self Assessment", "type": "object", "description": "The Business Self Assessment check captures information about the business's activities, financials, and purpose of the business relationship for risk scoring.", "properties": { "id": { "title": "Business Check unique identifier", "type": "string", "description": "Business Check unique identifier.", "format": "uuid" }, "business_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "type": { "type": "string", "default": "BUSINESS_SELF_ASSESSMENT", "description": "The type of check must be \"BUSINESS_SELF_ASSESSMENT\"." }, "check_confirmed_at": { "type": "string", "format": "date-time", "description": "The date and time when the self assessment check was confirmed." }, "status": { "type": "string", "description": "Final status of the business check.\n* IN_PROGRESS - Check is in progress\n* PASSED - Check passed\n* FAILED - Check failed", "enum": [ "IN_PROGRESS", "PASSED", "FAILED" ] }, "business_industry": { "title": "Business Industry", "type": "string", "description": "The business industry classification.", "enum": [ "ACCOMMODATION_AND_HOSPITALITY", "ACCOMMODATION_AND_HOSPITALITY_TIMESHARING", "ADMIN_AND_SUPPORT_SERVICES", "ADMIN_AND_SUPPORT_SERVICES_CLEANING_AND_FACILITIES", "ADMIN_AND_SUPPORT_SERVICES_SECURITY_AND_INVESTIGATION", "ADMIN_AND_SUPPORT_SERVICES_SPECIFIC_SECTORS", "AGRICULTURE_FORESTRY_AND_FISHING", "CONSTRUCTION", "EDUCATION", "EDUCATION_HIGHER_EDUCATION", "ENTERTAINMENT_ARTS_AND_RECREATION", "ENTERTAINMENT_ARTS_AND_RECREATION_NATURE_AND_ZOOS", "ENTERTAINMENT_ARTS_AND_RECREATION_SPECIFIC_SECTORS", "EXTRATERRITORIAL_AND_HOUSEHOLD_ACTIVITIES", "FINANCIAL_SERVICES", "FOOD_AND_BEVERAGE_SERVICES", "HEALTHCARE", "HEALTHCARE_COUNSELLING_AND_SOCIAL_SERVICES", "INFORMATION_TECHNOLOGY_AND_MEDIA", "INFORMATION_TECHNOLOGY_AND_MEDIA_ONLINE_GAMING", "INFORMATION_TECHNOLOGY_AND_MEDIA_PRINT_PUBLISHING", "INFORMATION_TECHNOLOGY_AND_MEDIA_TELECOMMUNICATIONS", "MANUFACTURING", "MANUFACTURING_PHARMACEUTICALS", "MANUFACTURING_PRECIOUS_METALS_AND_JEWELLERY", "MANUFACTURING_WEAPONS_AND_HAZARDOUS", "MINING_AND_QUARRYING", "PERSONAL_AND_OTHER_SERVICES", "PERSONAL_AND_OTHER_SERVICES_ADULT_AND_WELLNESS", "PERSONAL_AND_OTHER_SERVICES_NONPROFIT_AND_MEMBERSHIP_ORGANISATIONS", "PROFESSIONAL_AND_TECHNICAL_SERVICES", "PROFESSIONAL_AND_TECHNICAL_SERVICES_LEGAL_AND_FIDUCIARY", "PROFESSIONAL_AND_TECHNICAL_SERVICES_UNREGULATED", "PUBLIC_ADMINISTRATION", "PUBLIC_ADMINISTRATION_JUDICIAL", "REAL_ESTATE", "REAL_ESTATE_AGENCY_AND_BROKERAGE", "RETAIL_TRADE", "RETAIL_TRADE_SPECIALITY", "RETAIL_TRADE_SPECIFIC_SECTORS", "TRANSPORTATION_AND_LOGISTICS", "TRANSPORTATION_AND_LOGISTICS_CRUISE_LINES", "TRANSPORTATION_AND_LOGISTICS_RAIL_AND_STORAGE", "UTILITIES_AND_ENERGY", "WHOLESALE_TRADE", "WHOLESALE_TRADE_INDUSTRIAL", "WHOLESALE_TRADE_LUXURY_AND_COLLECTIBLES", "WHOLESALE_TRADE_PETROLEUM_AND_CHEMICALS" ] }, "purpose_of_business_relationship": { "title": "Purpose of Business Relationship", "type": "string", "description": "The purpose of the business relationship.", "enum": [ "WEALTH_GROWTH", "TREASURY_LIQUIDITY_MANAGEMENT", "HEDGING_RISK_MANAGEMENT", "EMPLOYEE_BENEFIT_FUNDING", "STRATEGIC_INVESTMENT" ] }, "primary_countries_of_activity": { "type": "array", "description": "List of primary countries where the business operates. ISO 3166-1 alpha-2 country codes.", "items": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "minItems": 1 }, "annual_revenue": { "title": "Monetary Range", "type": "object", "description": "A monetary range defined by a lower bound and an optional upper bound.", "properties": { "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "lower_bound": { "type": "number", "description": "The lower bound of the monetary range.", "minimum": 0 }, "upper_bound": { "type": "number", "description": "The upper bound of the monetary range.", "minimum": 0 } }, "required": [ "currency", "lower_bound" ], "additionalProperties": false }, "expected_volume_of_investment": { "title": "Monetary Range", "type": "object", "description": "A monetary range defined by a lower bound and an optional upper bound.", "properties": { "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "lower_bound": { "type": "number", "description": "The lower bound of the monetary range.", "minimum": 0 }, "upper_bound": { "type": "number", "description": "The upper bound of the monetary range.", "minimum": 0 } }, "required": [ "currency", "lower_bound" ], "additionalProperties": false }, "total_asset_value": { "title": "Monetary Range", "type": "object", "description": "A monetary range defined by a lower bound and an optional upper bound.", "properties": { "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "lower_bound": { "type": "number", "description": "The lower bound of the monetary range.", "minimum": 0 }, "upper_bound": { "type": "number", "description": "The upper bound of the monetary range.", "minimum": 0 } }, "required": [ "currency", "lower_bound" ], "additionalProperties": false } }, "required": [ "id", "business_id", "type", "check_confirmed_at", "status", "business_industry", "purpose_of_business_relationship", "primary_countries_of_activity", "annual_revenue", "expected_volume_of_investment", "total_asset_value" ], "additionalProperties": false } ] }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "example": { "id": "38fc59d0-fc42-46ef-9512-824773219b2e", "created_at": "2021-11-19T13:06:57.820371265Z", "type": "BUSINESS_CHECK.PASSED", "object": { "id": "a9a72268-4f3c-4de2-abb9-a553a3bb7608", "business_id": "1b097e06-8a14-4181-b72a-de0972a3c57b", "type": "KYB", "originally_confirmed_at": "2020-08-24T14:15:22Z", "check_confirmed_at": "2020-08-24T14:15:22Z", "data_download_link": "https://bucket.customer.com/por/kyb.zip", "document_type": "KYB_DOCUMENTS", "status": "PASSED" }, "webhook_id": "1b097e06-8a14-4181-b72a-de0972a3c57b" } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Tax exemption events": { "post": { "operationId": "tax_exemption_event", "summary": "Tax Exemption Events", "description": "Tax Exemption Events", "tags": [ "Tax Exemptions" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Tax Exemptions - Updated", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "title": "Tax Exemption Update Webhook Type", "type": "string", "description": "Tax exemption events webhook type \n* TAX_EXEMPTION.CREATED - Tax exemption successfully created. \n* TAX_EXEMPTION.UPDATED - Tax exemption successfully updated. \n* TAX_EXEMPTION.DELETED - Tax exemption successfully deleted.", "enum": [ "TAX_EXEMPTION.CREATED", "TAX_EXEMPTION.UPDATED", "TAX_EXEMPTION.DELETED" ] }, "object": { "title": "Webhook - Tax exemption - Created - Tax exemption", "type": "object", "additionalProperties": false, "properties": { "id": { "title": "Tax Exemption Unique Identifier", "type": "string", "description": "Tax Exemption Unique Identifier", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "status": { "title": "Tax exemption status", "type": "string", "description": "Tax exemption status \n* NEW - The tax exemption request is created. \n* ACTIVE - The tax exemption is valid and active for the current year. \n* EXPIRED - The tax exemption is no longer `ACTIVE` and the `valid_to_date` already lies in the past. An update is not possible. \n* CANCELLED - The tax exemption could not be created or was cancelled.", "enum": [ "NEW", "ACTIVE", "EXPIRED", "CANCELLED" ] }, "user_ids": { "description": "Ids of the users for whom the tax exemption was created.", "type": "array", "items": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" } }, "country": { "description": "Country code. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "pattern": "^[A-Z]{2}$" }, "valid_from_date": { "type": "string", "format": "date", "description": "Date from which the tax exemption is valid. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" }, "valid_to_date": { "type": "string", "format": "date", "nullable": true, "description": "Date until which the tax exemption is valid. If it is unlimited, it is omitted. For Germany it is always the last day of the year (YYYY-12-31). [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339)" }, "tax_exemption_details": { "title": "Tax Exemption - German Tax Exemption Details", "type": "object", "additionalProperties": false, "properties": { "tax_exemption_type": { "title": "Tax Exemption Type", "type": "string", "description": "Tax exemption type \n* SINGLE - Tax exemption for Individual. \n* MARRIED - Tax exemption for married couples.", "enum": [ "SINGLE", "MARRIED" ] }, "tax_exemption_amount": { "title": "Tax Exemption - Create - Request - Tax Exemption Details - Amount", "type": "object", "additionalProperties": false, "properties": { "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] } }, "required": [ "amount", "currency" ] }, "utilized_amount": { "title": "Tax Exemption - Create - Request - Tax Exemption Details - Amount", "type": "object", "additionalProperties": false, "properties": { "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] } }, "required": [ "amount", "currency" ] }, "remaining_amount": { "title": "Tax Exemption - Create - Request - Tax Exemption Details - Amount", "type": "object", "additionalProperties": false, "properties": { "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "tax_exemption_type", "tax_exemption_amount", "utilized_amount", "remaining_amount" ] } }, "required": [ "id", "status", "user_ids", "country", "valid_from_date", "valid_to_date", "tax_exemption_details", "created_at", "updated_at" ] }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "examples": { "tax_exemption_created": { "summary": "Tax Exemption Created", "value": { "id": "295cf14f-368c-450e-b57e-48d115d30fe4", "created_at": "2024-01-01T10:34:43Z", "type": "TAX_EXEMPTION.CREATED", "object": { "id": "f1a57a04-1a89-4dab-ae3a-ff9b2a9377c1", "created_at": "2024-01-01T10:33:43Z", "updated_at": "2024-01-01T10:33:43Z", "status": "ACTIVE", "user_ids": [ "70821d79-366f-4873-804b-14857d690496" ], "country": "DE", "valid_from_date": "2024-01-01", "valid_to_date": "2024-12-31", "tax_exemption_details": { "tax_exemption_type": "SINGLE", "tax_exemption_amount": { "amount": "1000.00", "currency": "EUR" }, "utilized_amount": { "amount": "0.00", "currency": "EUR" }, "remaining_amount": { "amount": "1000.00", "currency": "EUR" } } }, "webhook_id": "4a80c45f-204c-4498-ac20-d900a846e166" } }, "tax_exemption_updated": { "summary": "Tax Exemption Updated", "value": { "id": "295cf14f-368c-450e-b57e-48d115d30fe4", "created_at": "2024-01-01T10:34:43Z", "type": "TAX_EXEMPTION.UPDATED", "object": { "id": "f1a57a04-1a89-4dab-ae3a-ff9b2a9377c1", "created_at": "2024-01-01T10:33:43Z", "updated_at": "2024-01-01T10:33:43Z", "status": "ACTIVE", "user_ids": [ "70821d79-366f-4873-804b-14857d690496" ], "country": "DE", "valid_from_date": "2024-01-01", "valid_to_date": "2024-12-31", "tax_exemption_details": { "tax_exemption_type": "SINGLE", "tax_exemption_amount": { "amount": "1000.00", "currency": "EUR" }, "utilized_amount": { "amount": "0.00", "currency": "EUR" }, "remaining_amount": { "amount": "1000.00", "currency": "EUR" } } }, "webhook_id": "c10c4156-5f34-46cd-82b8-4ef84f0f3e24" } }, "tax_exemption_deleted": { "summary": "Tax Exemption Deleted", "value": { "id": "295cf14f-368c-450e-b57e-48d115d30fe4", "created_at": "2024-01-01T10:34:43Z", "type": "TAX_EXEMPTION.DELETED", "object": { "id": "f1a57a04-1a89-4dab-ae3a-ff9b2a9377c1", "created_at": "2024-01-01T10:33:43Z", "updated_at": "2024-09-01T01:13:03Z", "status": "ACTIVE", "user_ids": [ "70821d79-366f-4873-804b-14857d690496" ], "country": "DE", "valid_from_date": "2024-01-01", "valid_to_date": "2024-12-31", "tax_exemption_details": { "tax_exemption_type": "SINGLE", "tax_exemption_amount": { "amount": "1000.00", "currency": "EUR" }, "utilized_amount": { "amount": "0.00", "currency": "EUR" }, "remaining_amount": { "amount": "1000.00", "currency": "EUR" } } }, "webhook_id": "cd26a6ce-7a1c-47de-a6fc-b5dfd996da99" } } } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Tax exemption failure events": { "post": { "operationId": "tax_exemption_failure_event", "summary": "Tax Exemption Failure Events", "description": "Tax Exemption Failure Events", "tags": [ "Tax Exemptions" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Tax Exemptions - Update Failed", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "title": "Tax Exemption Update Webhook Type", "type": "string", "description": "Type of the tax exemption failure events webhook. \n* TAX_EXEMPTION.CREATION_FAILED - Tax exemption creation failed. \n* TAX_EXEMPTION.UPDATE_FAILED - Tax exemption update failed. \n* TAX_EXEMPTION.DELETION_FAILED - Tax exemption deletion failed.", "enum": [ "TAX_EXEMPTION.CREATION_FAILED", "TAX_EXEMPTION.UPDATE_FAILED", "TAX_EXEMPTION.DELETION_FAILED" ] }, "object": { "title": "Webhook - Tax exemption - Created - Tax exemption", "type": "object", "additionalProperties": false, "properties": { "id": { "title": "Tax Exemption Unique Identifier", "type": "string", "description": "Tax Exemption Unique Identifier", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "reason": { "type": "string", "description": "Reason for the failure of the tax exemption request." }, "status": { "title": "Tax exemption status", "type": "string", "description": "Tax exemption status \n* NEW - The tax exemption request is created. \n* ACTIVE - The tax exemption is valid and active for the current year. \n* EXPIRED - The tax exemption is no longer `ACTIVE` and the `valid_to_date` already lies in the past. An update is not possible. \n* CANCELLED - The tax exemption could not be created or was cancelled.", "enum": [ "NEW", "ACTIVE", "EXPIRED", "CANCELLED" ] }, "user_ids": { "description": "Ids of the users for whom the tax exemption was created.", "type": "array", "items": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" } } }, "required": [ "id", "reason", "status", "user_ids", "created_at", "updated_at" ] }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "examples": { "tax_exemption_created": { "summary": "Tax Exemption Created", "value": { "id": "2ce641a1-e89c-43be-b8d8-981d4aac5bd5", "created_at": "2024-01-01T10:34:43Z", "type": "TAX_EXEMPTION.CREATION_FAILED", "object": { "id": "f1a57a04-1a89-4dab-ae3a-ff9b2a9377c1", "created_at": "2024-01-01T10:33:43Z", "updated_at": "2024-01-01T10:33:43Z", "reason": "Missing TIN", "status": "CANCELLED", "user_ids": [ "70821d79-366f-4873-804b-14857d690496" ] }, "webhook_id": "606e3c01-c9cf-4073-900e-718bfc521953" } }, "tax_exemption_updated": { "summary": "Tax Exemption Updated", "value": { "id": "2ce641a1-e89c-43be-b8d8-981d4aac5bd5", "created_at": "2024-01-01T10:34:43Z", "type": "TAX_EXEMPTION.UPDATE_FAILED", "object": { "id": "f1a57a04-1a89-4dab-ae3a-ff9b2a9377c1", "created_at": "2024-01-01T10:33:43Z", "updated_at": "2024-01-01T10:33:43Z", "reason": "Invalid Amount", "status": "CANCELLED", "user_ids": [ "70821d79-366f-4873-804b-14857d690496" ] }, "webhook_id": "0a50586f-74d7-49ea-b2e8-bb02e9e8ee3b" } }, "tax_exemption_deleted": { "summary": "Tax Exemption Deleted", "value": { "id": "43020799-f975-4973-aa5a-be2536efb6dd", "created_at": "2024-01-01T10:34:43Z", "type": "TAX_EXEMPTION.DELETION_FAILED", "object": { "id": "f1670eb3-ccfc-473b-b628-0d8530ebe62d", "reason": "Tax exemption amount already utilised", "status": "ACTIVE", "user_ids": [ "a9947111-579b-4652-a53d-d7b81f2e50c8" ], "created_at": "2024-01-01T10:33:43Z", "updated_at": "2024-01-01T10:33:43Z" }, "webhook_id": "c2588a12-a22b-4d79-bada-24cfb9794727" } } } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Tax collection events": { "post": { "operationId": "tax_collection_event", "summary": "Tax Collection Events", "description": "Tax Collection Events", "tags": [ "Tax Collections" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Tax Collection - Updated", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "title": "Tax Collection Webhook Type", "type": "string", "description": "Tax collection webhook type \n* TAX_COLLECTION.CREATED - Tax collection processing started successfully. \n* TAX_COLLECTION.FINALISED - Tax collection processing finalised successfully. \n* TAX_COLLECTION.CANCELLED - Tax collection processing cancelled successfully.", "enum": [ "TAX_COLLECTION.CREATED", "TAX_COLLECTION.FINALISED", "TAX_COLLECTION.CANCELLED" ] }, "object": { "title": "Webhook - Tax collection", "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Tax Collection Unique Identifier", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_group_id": { "type": "string", "description": "Account Group Unique Identifier", "format": "uuid" }, "type": { "type": "string", "description": "Type of the tax collection\n* TAX_PREPAYMENT_DE - German preliminary lump-sum tax payment\n* TAX_PAYMENT - Tax payment", "enum": [ "TAX_PREPAYMENT_DE", "TAX_PAYMENT" ] }, "collection_amount": { "type": "object", "description": "Total amount of taxes to be collected", "additionalProperties": false, "properties": { "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] } }, "required": [ "amount", "currency" ] }, "instrument": { "type": "object", "description": "Instrument details", "additionalProperties": false, "properties": { "uuid": { "type": "string", "description": "Instrument Unique Identifier", "format": "uuid" }, "isin": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" } }, "required": [ "uuid", "isin" ] }, "processed_amount": { "type": "object", "description": "Processed amount details", "additionalProperties": false, "properties": { "cash_balance": { "type": "object", "description": "Taxes collected from the cash balance", "additionalProperties": false, "properties": { "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] } }, "required": [ "amount", "currency" ] }, "sell_to_cover": { "type": "object", "description": "Taxes collected by selling assets", "additionalProperties": false, "properties": { "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] } }, "required": [ "amount", "currency" ] }, "offset_amount": { "type": "object", "description": "Taxes collected by offsetting automatic corrections", "additionalProperties": false, "properties": { "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "cash_balance", "sell_to_cover", "offset_amount" ] }, "status": { "type": "string", "description": "Tax collection status \n* PROCESSING - The tax collection processing has started. \n* FINALISED - The tax collection has been processed successfully. \n* CANCELLED - The tax collection was cancelled.", "enum": [ "PROCESSING", "FINALISED", "CANCELLED" ] }, "references": { "type": "array", "items": { "type": "object", "description": "Identifier related to the tax collection.", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Referenced Identifier" }, "type": { "type": "string", "description": "Type of the referenced identifier.\n* EXTERNAL_TAX_TRANSACTION_ID - External tax transaction ID", "enum": [ "EXTERNAL_TAX_TRANSACTION_ID" ] } }, "required": [ "id", "type" ] } } }, "required": [ "id", "created_at", "updated_at", "type", "collection_amount", "processed_amount", "status" ] }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "examples": { "tax_collection_created": { "summary": "Tax Collection Created", "value": { "id": "38fc59d0-fc42-46ef-9512-824773219b2e", "created_at": "2024-08-19T13:06:57.820371265Z", "type": "TAX_COLLECTION.CREATED", "webhook_id": "1b097e06-8a14-4181-b72a-de0972a3c57b", "object": { "account_group_id": "999f7566-2ca3-4007-b99d-e501be8c7222", "collection_amount": { "amount": "100.00", "currency": "EUR" }, "id": "d77e6924-9bb7-4db0-addc-404442258f4b", "type": "TAX_PREPAYMENT_DE", "instrument": { "uuid": "d77e6924-9bb7-4db0-addc-404442258f4b", "isin": "DE000A0D8QZ0" }, "processed_amount": { "cash_balance": { "amount": "0.00", "currency": "EUR" }, "sell_to_cover": { "amount": "0.00", "currency": "EUR" }, "offset_amount": { "amount": "0.00", "currency": "EUR" } }, "status": "PROCESSING", "updated_at": "2024-08-19T13:06:57.820371265Z", "created_at": "2024-08-19T13:06:57.820371265Z" } } }, "tax_collection_finalised": { "summary": "Tax Collection Finalised", "value": { "id": "38fc59d0-fc42-46ef-9512-824773219b2e", "created_at": "2024-08-19T13:06:59.000000000Z", "type": "TAX_COLLECTION.FINALISED", "webhook_id": "1b097e06-8a14-4181-b72a-de0972a3c57b", "object": { "account_group_id": "999f7566-2ca3-4007-b99d-e501be8c7222", "collection_amount": { "amount": "100.00", "currency": "EUR" }, "id": "d77e6924-9bb7-4db0-addc-404442258f4b", "type": "TAX_PREPAYMENT_DE", "instrument": { "uuid": "d77e6924-9bb7-4db0-addc-404442258f4b", "isin": "DE000A0D8QZ0" }, "processed_amount": { "cash_balance": { "amount": "0.00", "currency": "EUR" }, "sell_to_cover": { "amount": "90.00", "currency": "EUR" }, "offset_amount": { "amount": "10.00", "currency": "EUR" } }, "status": "FINALISED", "updated_at": "2024-08-19T13:06:59.000000000Z", "created_at": "2024-08-19T13:06:57.820371265Z", "references": [ { "id": "CA_AUTO_50087_265145_I_0", "type": "EXTERNAL_TAX_TRANSACTION_ID" } ] } } }, "tax_collection_cancelled": { "summary": "Tax Collection Cancelled", "value": { "id": "38fc59d0-fc42-46ef-9512-824773219b2e", "created_at": "2024-08-19T13:06:59.000000000Z", "type": "TAX_COLLECTION.CANCELLED", "webhook_id": "1b097e06-8a14-4181-b72a-de0972a3c57b", "object": { "account_group_id": "999f7566-2ca3-4007-b99d-e501be8c7222", "collection_amount": { "amount": "100.00", "currency": "EUR" }, "id": "d77e6924-9bb7-4db0-addc-404442258f4b", "type": "TAX_PREPAYMENT_DE", "instrument": { "uuid": "d77e6924-9bb7-4db0-addc-404442258f4b", "isin": "DE000A0D8QZ0" }, "processed_amount": { "cash_balance": { "amount": "0.00", "currency": "EUR" }, "sell_to_cover": { "amount": "0.00", "currency": "EUR" }, "offset_amount": { "amount": "0.00", "currency": "EUR" } }, "status": "CANCELLED", "updated_at": "2024-08-19T13:06:59.000000000Z", "created_at": "2024-08-19T13:06:57.820371265Z" } } } } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "ISA tax wrapper events": { "post": { "operationId": "isa_tax_wrappers_event", "summary": "ISA Tax Wrappers events", "description": "ISA Tax Wrappers events", "tags": [ "Tax Wrappers" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Tax Wrappers - ISA Tax Wrapper Event", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "title": "ISA Tax Wrapper Webhook Type", "type": "string", "description": "The type of ISA tax wrapper event\n* NEW - The tax wrapper is newly created and not yet active due to pending checks.\n* ACTIVE - The tax wrapper is currently active and in use.\n* INACTIVE - The tax wrapper is not currently active. New subscriptions not allowed.\n* CLOSED - The tax wrapper has been closed and is no longer available.", "enum": [ "ISA_WRAPPER.NEW", "ISA_WRAPPER.ACTIVE", "ISA_WRAPPER.INACTIVE", "ISA_WRAPPER.CLOSED" ] }, "object": { "title": "Tax Wrappers - ISA Tax Wrapper", "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Tax wrapper unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "description": "The date and time the tax wrapper was created.", "format": "date-time" }, "updated_at": { "type": "string", "description": "The date and time the tax wrapper was last updated.", "format": "date-time" }, "account_group_id": { "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "is_flexible": { "type": "boolean", "description": "True if tax wrapper is flexible." }, "status": { "type": "string", "description": "Status of the tax wrapper\n* NEW - The tax wrapper is newly created and not yet active due to pending checks.\n* ACTIVE - The tax wrapper is currently active and in use.\n* INACTIVE - The tax wrapper is not currently active. New subscriptions not allowed.\n* CLOSED - The tax wrapper has been closed and is no longer available.", "enum": [ "NEW", "ACTIVE", "INACTIVE", "CLOSED" ] }, "type": { "type": "string", "description": "Types of the ISA tax wrapper", "enum": [ "STOCKS_AND_SHARES_ISA" ], "default": "STOCKS_AND_SHARES_ISA" } }, "required": [ "id", "created_at", "updated_at", "account_group_id", "is_flexible", "status", "type" ] }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "type", "object", "webhook_id", "created_at" ], "additionalProperties": false }, "examples": { "tax_wrapper_new": { "summary": "Tax Wrapper New", "value": { "id": "295cf14f-368c-450e-b57e-48d115d30fe4", "created_at": "2025-08-01T10:34:43Z", "type": "ISA_WRAPPER.NEW", "object": { "id": "f1a57a04-1a89-4dab-ae3a-ff9b2a9377c1", "created_at": "2025-08-01T10:33:43Z", "updated_at": "2025-08-01T10:33:43Z", "account_group_id": "d4b5c6e7-89f0-4a1b-9c2d-3e4f5a6b7c8d", "is_flexible": true, "status": "NEW", "type": "STOCKS_AND_SHARES_ISA" }, "webhook_id": "4a80c45f-204c-4498-ac20-d900a846e166" } } } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "ISA allowance events": { "post": { "operationId": "isa_allowance_event", "summary": "ISA Allowance events", "description": "ISA Allowance events", "tags": [ "Tax Wrappers" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Tax Wrappers - ISA Allowance Event", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "title": "ISA Allowance Webhook Type", "type": "string", "description": "The type of ISA allowance event:\n* CREATED: Allowance was created.\n* UPDATED: Allowance was updated.\n* EXPIRED: Allowance is no longer valid.", "enum": [ "ISA_WRAPPER_ALLOWANCE.CREATED", "ISA_WRAPPER_ALLOWANCE.UPDATED", "ISA_WRAPPER_ALLOWANCE.EXPIRED" ] }, "object": { "title": "Tax Wrappers - ISA Allowance", "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Allowance unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "description": "The date and time the tax wrapper was created.", "format": "date-time" }, "updated_at": { "type": "string", "description": "The date and time the tax wrapper was last updated.", "format": "date-time" }, "tax_wrapper_id": { "type": "string", "description": "Tax wrapper unique identifier.", "format": "uuid" }, "tax_year": { "oneOf": [ { "type": "null" }, { "type": "string", "description": "Tax year the allowance applies to, in the format 'YYYY/YYYY'.", "pattern": "^[0-9]{4}/[0-9]{4}$" } ] }, "type": { "type": "string", "description": "Type of the allowance:\n* ANNUAL - Allowance valid for a tax year.", "enum": [ "ANNUAL" ], "default": "ANNUAL" }, "status": { "type": "string", "description": "Status of the allowance:\n* ACTIVE - Current allowance.\n* EXPIRED - Allowance from previous years.", "enum": [ "ACTIVE", "EXPIRED" ] }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* GBP - British Pound Sterling", "enum": [ "GBP" ], "default": "GBP" }, "used_amount": { "type": "string", "pattern": "^-?[0-9]{1,9}(\\.[0-9]{2})?$" }, "remaining_amount": { "type": "string", "pattern": "^-?[0-9]{1,9}(\\.[0-9]{2})?$" }, "valid_from": { "type": "string", "description": "The date from which the allowance is valid.", "format": "date-time" }, "valid_to": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "date-time", "description": "The date until which the allowance is valid." } ] }, "first_subscription_at": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "date-time", "description": "The date of the first subscription that used this allowance." } ] } }, "required": [ "id", "created_at", "updated_at", "tax_wrapper_id", "type", "status", "currency", "used_amount", "remaining_amount", "valid_from" ] }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "type", "object", "webhook_id", "created_at" ], "additionalProperties": false }, "examples": { "allowance_updated": { "summary": "Allowance Updated", "value": { "id": "295cf14f-368c-450e-b57e-48d115d30fe4", "created_at": "2025-08-01T10:34:43Z", "type": "ISA_WRAPPER_ALLOWANCE.UPDATED", "object": { "id": "f1a57a04-1a89-4dab-ae3a-ff9b2a9377c1", "created_at": "2025-10-05T14:48:00.000Z", "updated_at": "2025-10-05T14:48:00.000Z", "tax_wrapper_id": "0d68fea2-66e8-4ea8-b507-276e7a1eb4aa", "tax_year": "2025/2026", "type": "ANNUAL", "status": "ACTIVE", "currency": "GBP", "used_amount": "1000.00", "remaining_amount": "19000.00", "valid_from": "2025-04-06T00:00:00.000Z", "valid_to": "2026-04-05T23:59:59.000Z", "first_subscription_at": "2025-05-13T00:00:00.000Z" }, "webhook_id": "4a80c45f-204c-4498-ac20-d900a846e166" } } } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Orders events": { "post": { "operationId": "order_event", "summary": "Orders events", "description": "Orders events", "tags": [ "Orders" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Orders - Callback", "type": "object", "description": "Webhook callback payload for order lifecycle events (`ORDER.NEW`, `ORDER.PROCESSING`, `ORDER.FILLED`, `ORDER.CANCELLED`).", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type", "enum": [ "ORDER.NEW", "ORDER.PROCESSING", "ORDER.FILLED", "ORDER.CANCELLED" ] }, "object": { "title": "Order", "type": "object", "description": "Represents an investment order placed by an end user or on their behalf. An order transitions through states (`NEW` → `PROCESSING` → `FILLED` or `CANCELLED`) as it is routed and executed.", "properties": { "id": { "title": "Order unique identifier", "type": "string", "description": "Unique identifier for an order. Universally Unique Identifier (UUID).", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "type": "string", "format": "uuid", "description": "The ID of the user. Either user ID or business ID must be specified." }, "business_id": { "type": "string", "format": "uuid", "description": "The ID of the business. Either user ID or business ID must be specified." }, "account_id": { "type": "string", "format": "uuid", "description": "The ID of the account that owns the order" }, "cash_amount": { "allOf": [ { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, { "description": "Cash amount for a nominal order, not required if a share quantity is specified." } ] }, "currency": { "allOf": [ { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound\n* USD - US Dollar", "enum": [ "EUR", "GBP", "USD" ] }, { "description": "The currency for the order." } ] }, "side": { "type": "string", "description": "Side of the order.\n* BUY — purchases the specified instrument.\n* SELL — disposes of the specified instrument.", "enum": [ "BUY", "SELL" ] }, "instrument_id": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, "instrument_id_type": { "description": "The type of the ID used in the request.\n* ISIN - ", "enum": [ "ISIN" ], "default": "ISIN", "type": "string" }, "order_type": { "type": "string", "description": "Type of the order.\n* MARKET — executes immediately at the best available market price.\n* LIMIT — executes only at or better than the specified `limit_price`.\n* STOP — triggers when the market price reaches `stop_price`, then executes at the prevailing market price.", "enum": [ "MARKET", "LIMIT", "STOP" ] }, "quantity": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "Quantity of securities for the order. Only required if the cash amount is not specified." } ] }, "user_instrument_fit_acknowledgement": { "type": "boolean", "description": "Only applicable if the user has failed the instrument fit check for the instrument type being ordered. True if the user has acknowledged their willingness to trade." }, "limit_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The limit price for orders of the type 'limit'." } ] }, "stop_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The stop price for orders of the type 'stop'." } ] }, "expiry_date": { "allOf": [ { "title": "Expiry date", "type": "string", "description": "Order expiration date in YYYY-MM-DD format. Only applicable to `LIMIT` and `STOP` orders — the order will not execute after this date. Defaults to order creation date plus 359 days.", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, { "description": "The order expiration date (last day the order can trade) in the YYYY-MM-DD format. The expiry date can only be set for LIMIT and STOP orders. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339. The default value is order creation date + 359 days" } ] }, "status": { "type": "string", "description": "The execution status of the order.\n* NEW — the order has been received and validated, awaiting routing.\n* PROCESSING — the order is being routed for execution.\n* FILLED — the order has been fully executed.\n* CANCELLED — the order was cancelled before being fully executed.", "enum": [ "NEW", "PROCESSING", "FILLED", "CANCELLED" ] }, "fee": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "cancellation_reason": { "type": "string", "description": "Reason for order cancellation. Present only when `status` is `CANCELLED`.\n* CANCELLED_BY_CLIENT — cancelled at the end user's or client's request via the API.\n* CANCELLED_BY_UPVEST_OPERATIONS — cancelled by Upvest operations.\n* CANCELLED_BY_TRADING_PARTNER — cancelled by the executing partner.\n* CANCELLED_BY_UPVEST_PLATFORM — cancelled automatically by the Upvest platform.", "enum": [ "CANCELLED_BY_CLIENT", "CANCELLED_BY_UPVEST_OPERATIONS", "CANCELLED_BY_TRADING_PARTNER", "CANCELLED_BY_UPVEST_PLATFORM" ] }, "initiation_flow": { "type": "string", "description": "Identifies what triggered the order.\n* API — initiated directly via the client API.\n* PORTFOLIO — initiated by a portfolio rebalancing flow.\n* CASH_DIVIDEND_REINVESTMENT — initiated as part of dividend reinvestment.\n* PORTFOLIO_REBALANCING — initiated by an automated rebalancing.\n* SELL_TO_COVER_FEES — initiated automatically to cover outstanding fees.\n* SELL_TO_COVER_TAXES — initiated automatically to cover tax obligations.\n* ACCOUNT_LIQUIDATION — initiated as part of an account liquidation.\n* UPVEST_OPERATIONS — initiated by Upvest operations.\n* SAVINGS_PLAN — initiated by a savings plan execution.\n* CLIENT_OPERATIONS — initiated by client operations.", "enum": [ "API", "PORTFOLIO", "CASH_DIVIDEND_REINVESTMENT", "PORTFOLIO_REBALANCING", "SELL_TO_COVER_FEES", "SELL_TO_COVER_TAXES", "ACCOUNT_LIQUIDATION", "UPVEST_OPERATIONS", "SAVINGS_PLAN", "CLIENT_OPERATIONS" ] }, "execution_flow": { "type": "string", "description": "Execution flow for order processing. Defaults to `STRAIGHT_THROUGH` if not specified.\n* STRAIGHT_THROUGH — the order is routed and executed directly without manual intervention.\n* BLOCK — the order is bundled with other orders for block execution.", "enum": [ "STRAIGHT_THROUGH", "BLOCK" ] }, "executions": { "type": "array", "description": "Order executions associated with this order", "items": { "title": "Order execution", "type": "object", "description": "Represents a single execution (trade fill) within an order. An order may have multiple executions if it is partially filled across several trades.", "properties": { "id": { "title": "Order execution unique identifier", "type": "string", "format": "uuid" }, "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "share_quantity": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "price": { "type": "string", "description": "Price of an instrument for a trade execution provided as a decimal string.", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,4})?$" }, "transaction_time": { "type": "string", "format": "date-time", "description": "Timestamp of when the trade was executed at the market. [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) date-time format." }, "taxes": { "type": "array", "description": "Taxes deducted as part of this execution.", "items": { "title": "Tax", "type": "object", "description": "Tax deducted as part of an order execution. Contains the tax type and the deducted amount.", "properties": { "type": { "type": "string", "description": "Tax type\n* TOTAL - ", "default": "TOTAL", "enum": [ "TOTAL" ] }, "amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" } }, "required": [ "type", "amount" ] } }, "order_id": { "title": "Order unique identifier", "type": "string", "description": "Unique identifier for an order. Universally Unique Identifier (UUID).", "format": "uuid" }, "status": { "type": "string", "description": "Status of the execution.\n* FILLED — the execution has been filled.\n* SETTLED — the execution has settled and securities and cash have been exchanged.\n* CANCELLED — the execution was cancelled before settlement.", "enum": [ "FILLED", "SETTLED", "CANCELLED" ] }, "side": { "type": "string", "description": "Side of the execution.\n* BUY — a buy execution.\n* SELL — a sell execution.", "enum": [ "BUY", "SELL" ] }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound\n* USD - US Dollar", "enum": [ "EUR", "GBP", "USD" ] }, "settlement_date": { "allOf": [ { "title": "Settlement date", "type": "string", "description": "Trade settlement date in YYYY-MM-DD format. The date on which securities and cash are exchanged following execution.", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, { "description": "Order execution settlement date in the YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339" } ] }, "venue_id": { "type": "string", "format": "uuid", "description": "The ID of the venue" } }, "required": [ "id", "cash_amount", "share_quantity", "price", "transaction_time", "taxes", "order_id", "status", "side", "currency", "venue_id" ], "additionalProperties": false } }, "client_reference": { "type": "string", "description": "Immutable reference to the API flow that initiated the order. For client initiated API flows, this is a client provided ID. For internal initiations, it is set to the ID of the related object.", "maxLength": 100 }, "fee_configuration": { "type": "array", "description": "Fee configuration applied to this order. Determines how the order fee is calculated.", "items": { "title": "Fee", "description": "A fee applied to an order. Either a fixed absolute cash fee (`absolute_fee_configuration_item`) or a reference to a predefined transaction fee model.", "oneOf": [ { "title": "Absolute Fee", "type": "object", "description": "A fixed cash fee applied to an order, specified as an absolute amount in a given currency.", "properties": { "type": { "title": "Fee type", "description": "Fee type\n* TRANSACTION_FEE_BUY - \n* TRANSACTION_FEE_SELL - ", "type": "string", "enum": [ "TRANSACTION_FEE_BUY", "TRANSACTION_FEE_SELL" ] }, "value_type": { "type": "string", "default": "ABSOLUTE", "description": "The value type must be “ABSOLUTE”." }, "charge_method": { "title": "Fee charge method", "type": "string", "description": "Indicates whether the fee will be charged by client or by other methods.\n* CHARGED_BY_CLIENT - \n* COLLECTED_BY_UPVEST - ", "enum": [ "CHARGED_BY_CLIENT", "COLLECTED_BY_UPVEST" ] }, "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound\n* USD - US Dollar", "enum": [ "EUR", "GBP", "USD" ] } }, "required": [ "type", "value_type", "charge_method", "cash_amount", "currency" ], "additionalProperties": false }, { "title": "Transaction Fee Model", "type": "object", "description": "A fee configuration that references a predefined transaction fee model by its ID, rather than specifying a fee amount directly.", "properties": { "type": { "title": "Fee type", "description": "Fee type\n* TRANSACTION_FEE_BUY - \n* TRANSACTION_FEE_SELL - ", "type": "string", "enum": [ "TRANSACTION_FEE_BUY", "TRANSACTION_FEE_SELL" ] }, "transaction_fee_model_id": { "type": "string", "format": "uuid", "description": "The ID of the transaction fee model." } }, "required": [ "type", "transaction_fee_model_id" ], "additionalProperties": false } ] } }, "decision_maker_id": { "type": "string", "description": "ID of the user behind the decision to place an order. Required only if different from the user_id. (e.g. child account order placed by a guardian)" } }, "required": [ "id", "created_at", "updated_at", "account_id", "cash_amount", "currency", "side", "instrument_id", "instrument_id_type", "order_type", "quantity", "status", "fee", "initiation_flow", "executions" ], "additionalProperties": false }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "example": { "id": "8962b496-8d42-4560-bfab-10490dd1a721", "created_at": "2021-07-21T14:10:00.00Z", "type": "ORDER.NEW", "object": { "id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "user_id": "2dedfeb0-58cd-44f2-ae08-0e41fe0413d9", "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3", "cash_amount": "56.65", "currency": "EUR", "side": "BUY", "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "order_type": "MARKET", "quantity": "0.05", "status": "NEW", "fee": "0.5", "executions": [], "initiation_flow": "API" }, "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6" } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Executions events": { "post": { "operationId": "execution_event", "summary": "Executions events", "description": "Executions events", "tags": [ "Orders" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Executions - Callback", "type": "object", "description": "Webhook callback payload for order execution events (`EXECUTION.FILLED`, `EXECUTION.SETTLED`, `EXECUTION.CANCELLED`).", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type", "enum": [ "EXECUTION.FILLED", "EXECUTION.SETTLED", "EXECUTION.CANCELLED" ] }, "object": { "title": "Order execution", "type": "object", "description": "Represents a single execution (trade fill) within an order. An order may have multiple executions if it is partially filled across several trades.", "properties": { "id": { "title": "Order execution unique identifier", "type": "string", "format": "uuid" }, "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "share_quantity": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "price": { "type": "string", "description": "Price of an instrument for a trade execution provided as a decimal string.", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,4})?$" }, "transaction_time": { "type": "string", "format": "date-time", "description": "Timestamp of when the trade was executed at the market. [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) date-time format." }, "taxes": { "type": "array", "description": "Taxes deducted as part of this execution.", "items": { "title": "Tax", "type": "object", "description": "Tax deducted as part of an order execution. Contains the tax type and the deducted amount.", "properties": { "type": { "type": "string", "description": "Tax type\n* TOTAL - ", "default": "TOTAL", "enum": [ "TOTAL" ] }, "amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" } }, "required": [ "type", "amount" ] } }, "order_id": { "title": "Order unique identifier", "type": "string", "description": "Unique identifier for an order. Universally Unique Identifier (UUID).", "format": "uuid" }, "status": { "type": "string", "description": "Status of the execution.\n* FILLED — the execution has been filled.\n* SETTLED — the execution has settled and securities and cash have been exchanged.\n* CANCELLED — the execution was cancelled before settlement.", "enum": [ "FILLED", "SETTLED", "CANCELLED" ] }, "side": { "type": "string", "description": "Side of the execution.\n* BUY — a buy execution.\n* SELL — a sell execution.", "enum": [ "BUY", "SELL" ] }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound\n* USD - US Dollar", "enum": [ "EUR", "GBP", "USD" ] }, "settlement_date": { "allOf": [ { "title": "Settlement date", "type": "string", "description": "Trade settlement date in YYYY-MM-DD format. The date on which securities and cash are exchanged following execution.", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, { "description": "Order execution settlement date in the YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339" } ] }, "venue_id": { "type": "string", "format": "uuid", "description": "The ID of the venue" } }, "required": [ "id", "cash_amount", "share_quantity", "price", "transaction_time", "taxes", "order_id", "status", "side", "currency", "venue_id" ], "additionalProperties": false }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "example": { "id": "8962b496-8d42-4560-bfab-10490dd1a721", "created_at": "2022-11-17T10:42:34.758Z", "type": "EXECUTION.FILLED", "object": { "cash_amount": "852.20", "currency": "EUR", "id": "b40f4631-e83b-4737-a003-c0cb36382bc5", "order_id": "cd2d6019-c11d-4114-aab3-b2e5dbe58cbf", "price": "85.22", "share_quantity": "10", "side": "BUY", "status": "FILLED", "taxes": [ { "amount": "0", "type": "TOTAL" } ], "transaction_time": "2022-11-17T10:42:34.758Z", "venue_id": "20d6024b-2df4-41ae-8d42-62e4744e455b" }, "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6" } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Order Cancellations events": { "post": { "operationId": "order_cancellation_event", "summary": "Order Cancellations events", "description": "Order Cancellations events", "tags": [ "Orders" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Order Cancellations - Callback", "type": "object", "description": "Webhook callback payload for order cancellation rejection events (`ORDER_CANCELLATION.REJECTED`).", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type", "enum": [ "ORDER_CANCELLATION.REJECTED" ] }, "object": { "title": "Order Cancellation", "type": "object", "description": "Represents the result of an order cancellation request. If the cancellation is rejected, `status` is `REJECTED` and the `reason` field explains why.", "properties": { "order_id": { "title": "Order unique identifier", "type": "string", "description": "Unique identifier for an order. Universally Unique Identifier (UUID).", "format": "uuid" }, "status": { "type": "string", "description": "Status of the order cancellation process", "enum": [ "REJECTED" ] }, "reason": { "type": "string", "description": "Reason behind order cancellation rejection." } }, "required": [ "order_id", "status" ], "additionalProperties": false }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "example": { "id": "e0b1f0ac-d34a-4f07-b268-545278110231", "created_at": "2023-08-01T14:10:00.00Z", "type": "ORDER_CANCELLATION.REJECTED", "object": { "order_id": "120c5382-d400-4a8e-95fc-d297903f3568", "status": "REJECTED", "reason": "Cancellation not possible" }, "webhook_id": "0e225118-168c-4d4d-84d9-c36096163162" } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Positions events": { "post": { "operationId": "position_event", "summary": "Positions events", "description": "Positions events", "tags": [ "Positions" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Positions - Callback", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type", "enum": [ "POSITION.UPDATED" ], "default": "POSITION.UPDATED" }, "object": { "type": "object", "properties": { "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "instrument": { "type": "object", "properties": { "uuid": { "type": "string", "description": "Instrument unique identifier.", "format": "uuid" }, "isin": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" } }, "required": [ "uuid" ], "additionalProperties": false }, "quantity": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "locked_for_trading": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "pending_settlement": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "available_for_trading": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "available_for_instruction": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "settled_quantity": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" } }, "required": [ "account_id", "instrument", "quantity", "locked_for_trading", "pending_settlement", "available_for_trading", "available_for_instruction", "settled_quantity" ], "additionalProperties": false }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "example": { "id": "8962b496-8d42-4560-bfab-10490dd1a724", "created_at": "2021-07-21T14:10:00.00Z", "type": "POSITION.UPDATED", "object": { "account_id": "c5161455-4d27-4781-bc74-f05532e49a77", "instrument": { "isin": "US0378331005", "uuid": "ccb86937-8a39-4160-8d33-85bf9e902321" }, "quantity": "10.4", "locked_for_trading": "5", "pending_settlement": "2.2", "available_for_trading": "5.4", "available_for_instruction": "5.4", "settled_quantity": "8.2" }, "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6" } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Cash Balance events": { "post": { "operationId": "cash_balance_event", "summary": "Cash Balance events", "description": "Cash Balance events", "tags": [ "Cash Balances" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Positions - Callback", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type", "enum": [ "CASH_BALANCE.UPDATED" ], "default": "CASH_BALANCE.UPDATED" }, "object": { "type": "object", "properties": { "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling\n* USD - The United States dollar", "enum": [ "EUR", "GBP", "USD" ] }, "balance": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "locked_for_trading": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "pending_settlement": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "available_for_withdrawal": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "available_for_trading": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" } }, "required": [ "account_group_id", "currency", "balance", "locked_for_trading", "pending_settlement", "available_for_withdrawal", "available_for_trading" ], "additionalProperties": false }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "examples": { "cash_balance_updated": { "summary": "Cash Balance Updated", "value": { "id": "8962b496-8d42-4560-bfab-10490dd1a724", "created_at": "2021-07-21T14:10:00.00Z", "type": "CASH_BALANCE.UPDATED", "object": { "account_group_id": "d0fc0305-97b7-4e3b-bddf-66d3c434898c", "currency": "EUR", "balance": "100", "locked_for_trading": "10", "pending_settlement": "10", "available_for_withdrawal": "80", "available_for_trading": "80" }, "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6" } }, "cash_balance_not_available_for_new_withdrawal": { "summary": "Cash Balance not available for NEW withdrawal", "value": { "id": "a59c81ee-7770-4f6b-9ebe-8c268b78beb4", "created_at": "2021-07-22T14:12:00.00Z", "type": "CASH_BALANCE.UPDATED", "object": { "account_group_id": "d0fc0305-97b7-4e3b-bddf-66d3c434898c", "currency": "EUR", "balance": "200", "locked_for_trading": "0", "pending_settlement": "0", "available_for_withdrawal": "0", "available_for_trading": "0" }, "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6" } }, "cash_balance_empty_for_confirmed_withdrawal": { "summary": "Cash Balance empty for CONFIRMED withdrawal", "value": { "id": "8c049f77-dc72-489d-8f5f-3871db782252", "created_at": "2021-07-21T14:11:00.00Z", "type": "CASH_BALANCE.UPDATED", "object": { "account_group_id": "d0fc0305-97b7-4e3b-bddf-66d3c434898c", "currency": "EUR", "balance": "0", "locked_for_trading": "0", "pending_settlement": "0", "available_for_withdrawal": "0", "available_for_trading": "0" }, "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6" } } } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Cash transactions events": { "post": { "operationId": "cash_transaction_event", "summary": "Cash transactions events", "description": "Cash transactions events", "tags": [ "Transactions" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Cash Transactions - Callback", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type", "enum": [ "CASH_TRANSACTION.EXECUTED" ], "default": "CASH_TRANSACTION.EXECUTED" }, "object": { "title": "Cash Transaction", "type": "object", "properties": { "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "booking_date": { "title": " Transaction booking date", "type": "string", "description": " Transaction booking date and time. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "delta": { "title": "Cash transaction delta", "description": "Entity representing cash transaction delta.", "type": "object", "properties": { "amount": { "type": "string", "pattern": "^-?[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling\n* USD - The United States dollar", "enum": [ "EUR", "GBP", "USD" ] } }, "required": [ "amount", "currency" ], "additionalProperties": false }, "id": { "title": "Cash transaction unique identifier", "type": "string", "description": "Cash transaction unique identifier.", "format": "uuid" }, "instrument": { "title": "Instrument", "description": "Entity representing instrument.", "type": "object", "properties": { "uuid": { "description": "Internal instrument identifier.", "type": "string", "format": "uuid" }, "isin": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" } }, "required": [ "uuid" ], "additionalProperties": false }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "taxes": { "type": "array", "items": { "title": "Transaction tax", "description": "Entity representing the transaction tax.", "type": "object", "properties": { "amount": { "type": "string", "pattern": "^-?[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling\n* USD - The United States dollar", "enum": [ "EUR", "GBP", "USD" ] }, "type": { "type": "string", "description": "Type of the tax.\n* TOTAL - Total taxes", "enum": [ "TOTAL" ], "default": "TOTAL" } }, "required": [ "amount", "currency", "type" ], "additionalProperties": false } }, "taxes_details": { "title": "Transaction taxes details", "description": "Entity representing the transaction taxes details.", "type": "object", "properties": { "total_amount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^-?[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling\n* USD - The United States dollar", "enum": [ "EUR", "GBP", "USD" ] } }, "required": [ "amount", "currency" ] }, "tax_breakdown": { "type": "array", "items": { "title": "Transaction tax", "description": "Entity representing the transaction tax.", "type": "object", "properties": { "amount": { "type": "string", "pattern": "^-?[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling\n* USD - The United States dollar", "enum": [ "EUR", "GBP", "USD" ] }, "type": { "type": "string", "description": "Type of the tax.", "enum": [ "CAPITAL_GAINS", "CHURCH_TAX", "SOLIDARITY_SURCHARGE", "FINANCIAL_TRANSACTION_TAX", "STAMP_DUTY", "INTERNATIONAL_WITHHOLDING_TAX" ] }, "taxing_jurisdiction": { "description": "Country code. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "pattern": "^[A-Z]{2}$" } }, "required": [ "amount", "currency", "type", "taxing_jurisdiction" ], "additionalProperties": false } } }, "required": [ "total_amount", "tax_breakdown" ], "additionalProperties": false }, "fees": { "type": "array", "items": { "title": "Transaction fee", "description": "Entity representing the transaction fee.", "type": "object", "properties": { "amount": { "type": "string", "pattern": "^-?[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling\n* USD - The United States dollar", "enum": [ "EUR", "GBP", "USD" ] }, "type": { "type": "string", "description": "Type of the fee.\n* TOTAL - Total fees", "enum": [ "TOTAL" ], "default": "TOTAL" }, "charge_method": { "type": "string", "description": "Indicates whether the fee was charged by client or by other methods.\n* CHARGED_BY_CLIENT - Charged by client\n* COLLECTED_BY_UPVEST - Charged by client and collected by Upvest", "enum": [ "CHARGED_BY_CLIENT", "COLLECTED_BY_UPVEST" ] } }, "required": [ "amount", "currency", "type", "charge_method" ], "additionalProperties": false } }, "references": { "type": "array", "items": { "title": "Cash transaction reference", "description": "Entity representing cash transaction reference.", "type": "object", "properties": { "id": { "title": "Unique identifier for a resource of given type", "type": "string", "description": "Unique identifier for a resource of given type.", "format": "uuid" }, "type": { "type": "string", "description": "Type of the reference.\n* ACCOUNT_GROUP - Account group\n* CASH_BALANCE_TRANSFER - Cash balance transfer\n* CORPORATE_ACTION - Corporate action\n* CORPORATE_ACTION_TRANSACTION_ID - Corporate action transaction ID\n* CREDIT_FUNDING - Credit Funding\n* DIRECT_DEBIT - Direct debit funding request\n* FEE_COLLECTION - Fee collection\n* ISA_TRANSFER - ISA transfer\n* ORDER - Order\n* ORDER_EXECUTION - Order execution\n* TAX_TRANSACTION - Tax transaction\n* TOPUP - Cash top up\n* TRANSACTION_FEE_EXECUTION - Transaction fee execution\n* VIRTUAL_CASH_DECREASE - Virtual cash decreased\n* VIRTUAL_CASH_INCREASE - Virtual cash increased\n* WITHDRAWAL - Cash withdrawal", "enum": [ "ACCOUNT_GROUP", "CASH_BALANCE_TRANSFER", "CORPORATE_ACTION", "CORPORATE_ACTION_TRANSACTION_ID", "CREDIT_FUNDING", "DIRECT_DEBIT", "FEE_COLLECTION", "ISA_TRANSFER", "ORDER", "ORDER_EXECUTION", "TAX_TRANSACTION", "TOPUP", "TRANSACTION_FEE_EXECUTION", "VIRTUAL_CASH_DECREASE", "VIRTUAL_CASH_INCREASE", "WITHDRAWAL" ] } }, "required": [ "id", "type" ], "additionalProperties": false } }, "type": { "title": "Transaction type", "description": "Transaction type\n* ACCUMULATION - Accumulation\n* ACCUMULATION_CANCELLATION - Accumulation cancellation\n* ANNUAL_GENERAL_MEETING - Annual general meeting\n* ANNUAL_GENERAL_MEETING_CANCELLATION - Annual general meeting cancellation\n* ATTACHMENT - Attachment\n* ATTACHMENT_CANCELLATION - Attachment cancellation\n* BALANCE_CORRECTION - Balance correction\n* BALANCE_CORRECTION_CANCELLATION - Balance correction cancellation\n* BANKRUPTCY - Bankruptcy\n* BANKRUPTCY_CANCELLATION - Bankruptcy cancellation\n* BOND_DEFAULT - Bond default\n* BOND_DEFAULT_CANCELLATION - Bond default cancellation\n* BOND_HOLDER_MEETING - Bond holder meeting\n* BOND_HOLDER_MEETING_CANCELLATION - Bond holder meeting cancellation\n* BONUS_ISSUE - Bonus Issue/Capitalisation Issue\n* BONUS_ISSUE_CANCELLATION - Bonus Issue/Capitalisation Issue, Cancellation\n* CALL_ON_INTERMEDIATE_SECURITIES - Call on Intermediate Securities\n* CALL_ON_INTERMEDIATE_SECURITIES_CANCELLATION - Call on Intermediate Securities cancellation\n* CAPITAL_DISTRIBUTION - Capital distribution\n* CAPITAL_DISTRIBUTION_CANCELLATION - Capital distribution cancellation\n* CAPITAL_GAINS_DISTRIBUTION - Capital gains distribution\n* CAPITAL_GAINS_DISTRIBUTION_CANCELLATION - Capital gains distribution cancellation\n* CAPITALISATION - Capitalisation\n* CAPITALISATION_CANCELLATION - Capitalisation cancellation\n* CASH_DISTRIBUTION_FROM_NON_ELIGIBLE_SECURITIES_SALES - Cash distribution from non eligible securities sales\n* CASH_DISTRIBUTION_FROM_NON_ELIGIBLE_SECURITIES_SALES_CANCELLATION - Cash distribution from non eligible securities sales cancellation\n* CASH_DIVIDEND - Cash dividend\n* CASH_DIVIDEND_CANCELLATION - Cash dividend cancellation\n* CHANGE - Change\n* CHANGE_CANCELLATION - Change, Cancellation\n* CLASS_ACTION - Class action\n* CLASS_ACTION_CANCELLATION - Class action cancellation\n* COMPANY_OPTION - Company option\n* COMPANY_OPTION_CANCELLATION - Company option cancellation\n* CONSENT - Consent\n* CONSENT_CANCELLATION - Consent cancellation\n* CONVERSION - Conversion\n* CONVERSION_CANCELLATION - Conversion cancellation\n* COURT_MEETING - Court meeting\n* COURT_MEETING_CANCELLATION - Court meeting cancellation\n* CREDIT_EVENT - Credit event\n* CREDIT_EVENT_CANCELLATION - Credit event cancellation\n* CREDIT_FUNDING - Credit funding\n* CREDIT_FUNDING_CHARGE_BACK - Credit funding charge back\n* DD_REFUND_REJECT_FEE - Direct debit refund reject fee\n* DD_REFUND_REJECT_FEE_CANCELLATION - Direct debit refund reject fee cancellation\n* DECREASE_IN_VALUE - Decrease in Value\n* DECREASE_IN_VALUE_CANCELLATION - Decrease in Value, Cancellation\n* DETACHMENT - Detachment\n* DETACHMENT_CANCELLATION - Detachment cancellation\n* DISCLOSURE - Disclosure\n* DISCLOSURE_CANCELLATION - Disclosure cancellation\n* DIVIDEND_OPTION - Dividend Option\n* DIVIDEND_OPTION_CANCELLATION - Dividend Option, Cancellation\n* DIVIDEND_REINVESTMENT - Dividend Reinvestment\n* DIVIDEND_REINVESTMENT_CANCELLATION - Dividend Reinvestment, Cancellation\n* DRAWING - Drawing\n* DRAWING_CANCELLATION - Drawing cancellation\n* DUTCH_AUCTION - Dutch Auction\n* DUTCH_AUCTION_CANCELLATION - Dutch Auction, Cancellation\n* EXCHANGE - Exchange\n* EXCHANGE_CANCELLATION - Exchange cancellation\n* EXTRAORDINARY_OR_SPECIAL_GENERAL_MEETING - Extraordinary or special general meeting\n* EXTRAORDINARY_OR_SPECIAL_GENERAL_MEETING_CANCELLATION - Extraordinary or special general meeting cancellation\n* FEE_COLLECTION - Fee collection\n* FEE_COLLECTION_CANCELLATION - Fee collection cancellation\n* FINAL_MATURITY - Final maturity\n* FINAL_MATURITY_CANCELLATION - Final maturity cancellation\n* FULL_CALL - Full call\n* FULL_CALL_CANCELLATION - Full call cancellation\n* INCREASE_IN_VALUE - Increase in Value\n* INCREASE_IN_VALUE_CANCELLATION - Increase in Value, Cancellation\n* INFORMATION - Information\n* INFORMATION_CANCELLATION - Information cancellation\n* INSTALMENT_CALL - Instalment call\n* INSTALMENT_CALL_CANCELLATION - Instalment call cancellation\n* INTEREST_PAYMENT - Interest payment\n* INTEREST_PAYMENT_CANCELLATION - Interest payment cancellation\n* INTERMEDIATE_SECURITIES_DISTRIBUTION - Intermediate Securities Distribution\n* INTERMEDIATE_SECURITIES_DISTRIBUTION_CANCELLATION - Intermediate Securities Distribution, Cancellation\n* INTERNAL_CASH_TRANSFER - Internal cash transfer\n* INTERNAL_CASH_TRANSFER_CANCELLATION - Internal cash transfer, Cancellation\n* ISA_TRANSFER - ISA transfer\n* LIQUIDATION_PAYMENT - Liquidation Dividend/Liquidation Payment\n* LIQUIDATION_PAYMENT_CANCELLATION - Liquidation Dividend/Liquidation Payment, Cancellation\n* MATURITY_EXTENSION - Maturity extension\n* MATURITY_EXTENSION_CANCELLATION - Maturity extension cancellation\n* MERGER - Merger\n* MERGER_CANCELLATION - Merger, Cancellation\n* NON_OFFICIAL_OFFER - Non-Official Offer\n* NON_OFFICIAL_OFFER_CANCELLATION - Non-Official Offer, Cancellation\n* NON_US_TEFRA_D_CERTIFICATION - Non us tefra d certification\n* NON_US_TEFRA_D_CERTIFICATION_CANCELLATION - Non us tefra d certification cancellation\n* ODD_LOT_SALE - Odd Lot Sale/Purchase\n* ODD_LOT_SALE_CANCELLATION - Odd Lot Sale/Purchase, Cancellation\n* ORDER_EXECUTION - Order execution\n* ORDER_EXECUTION_CANCELLATION - Order execution cancellation\n* ORDINARY_GENERAL_MEETING - Ordinary general meeting\n* ORDINARY_GENERAL_MEETING_CANCELLATION - Ordinary general meeting cancellation\n* OTHER_EVENT - Other Event\n* OTHER_EVENT_CANCELLATION - Other Event, Cancellation\n* PARI_PASSU - Pari passu\n* PARI_PASSU_CANCELLATION - Pari passu cancellation\n* PARTIAL_DEFEASANCE - Partial defeasance\n* PARTIAL_DEFEASANCE_CANCELLATION - Partial defeasance cancellation\n* PARTIAL_REDEMPTION_WITH_POOL_FACTOR_REDUCTION - Partial redemption with pool factor reduction\n* PARTIAL_REDEMPTION_WITH_POOL_FACTOR_REDUCTION_CANCELLATION - Partial redemption with pool factor reduction cancellation\n* PARTIAL_REDEMPTION_WITHOUT_POOL_FACTOR_REDUCTION - Partial redemption without pool factor reduction\n* PARTIAL_REDEMPTION_WITHOUT_POOL_FACTOR_REDUCTION_CANCELLATION - Partial redemption without pool factor reduction cancellation\n* PAY_IN_KIND - Pay in kind\n* PAY_IN_KIND_CANCELLATION - Pay in kind cancellation\n* PEAK_FRACTION_COMPENSATION - Peak fraction compensation\n* PEAK_ORDER_ADJUSTMENT - Peak order adjustment\n* PLACE_OF_INCORPORATION - Place of incorporation\n* PLACE_OF_INCORPORATION_CANCELLATION - Place of incorporation cancellation\n* PRIORITY_ISSUE - Priority Issue\n* PRIORITY_ISSUE_CANCELLATION - Priority Issue, Cancellation\n* PUT_REDEMPTION - Put redemption\n* PUT_REDEMPTION_CANCELLATION - Put redemption cancellation\n* REDENOMINATION - Redenomination\n* REDENOMINATION_CANCELLATION - Redenomination cancellation\n* REMARKETING_AGREEMENT - Remarketing agreement\n* REMARKETING_AGREEMENT_CANCELLATION - Remarketing agreement cancellation\n* REPURCHASE_OFFER - Repurchase Offer/Issuer Bid/Reverse Rights\n* REPURCHASE_OFFER_CANCELLATION - Repurchase Offer/Issuer Bid/Reverse Rights, Cancellation\n* REVERSE_STOCK_SPLIT - Reverse Stock Split/Change in Nominal Value\n* REVERSE_STOCK_SPLIT_CANCELLATION - Reverse Stock Split/Change in Nominal Value, Cancellation\n* RIGHTS_ISSUE - Rights Issue/Subscription Rights/Rights Offer\n* RIGHTS_ISSUE_CANCELLATION - Rights Issue/Subscription Rights/Rights Offer, Cancellation\n* SCRIP_DIVIDEND - Scrip dividend\n* SCRIP_DIVIDEND_CANCELLATION - Scrip dividend cancellation\n* SEPA_DIRECT_DEBIT - Sepa direct debit\n* SEPA_DIRECT_DEBIT_CHARGE_BACK - Sepa direct debit charge back\n* SHARES_PREMIUM_DIVIDEND - Shares Premium Dividend\n* SHARES_PREMIUM_DIVIDEND_CANCELLATION - Shares Premium Dividend, Cancellation\n* SMALLEST_NEGOTIABLE_UNIT - Smallest negotiable unit\n* SMALLEST_NEGOTIABLE_UNIT_CANCELLATION - Smallest negotiable unit cancellation\n* SPIN_OFF - Spin-Off\n* SPIN_OFF_CANCELLATION - Spin-Off, Cancellation\n* STOCK_DIVIDEND - Stock Dividend\n* STOCK_DIVIDEND_CANCELLATION - Stock Dividend, Cancellation\n* STOCK_SPLIT - Stock Split/Change in Nominal Value/Subdivision\n* STOCK_SPLIT_CANCELLATION - Stock Split/Change in Nominal Value/Subdivision, Cancellation\n* TAX_ON_NON_DISTRIBUTED_PROCEEDS - Tax on non distributed proceeds\n* TAX_ON_NON_DISTRIBUTED_PROCEEDS_CANCELLATION - Tax on non distributed proceeds cancellation\n* TAX_PAYMENT - Tax payment\n* TAX_PREPAYMENT_DE - German tax prepayment (Vorabpauschale)\n* TAX_RECLAIM - Tax reclaim\n* TAX_RECLAIM_CANCELLATION - Tax reclaim cancellation\n* TAX_REFUND - Tax refund\n* TENDER - Tender/Acquisition/Takeover/Purchase Offer\n* TENDER_CANCELLATION - Tender/Acquisition/Takeover/Purchase Offer, Cancellation\n* TOPUP - Cash top up\n* TOPUP_CANCELLATION - Top up cancellation\n* TRADING_STATUS_ACTIVE - Trading status active\n* TRADING_STATUS_ACTIVE_CANCELLATION - Trading status active cancellation\n* TRADING_STATUS_DELISTED - Trading status delisted\n* TRADING_STATUS_DELISTED_CANCELLATION - Trading status delisted cancellation\n* TRADING_STATUS_SUSPENDED - Trading status suspended\n* TRADING_STATUS_SUSPENDED_CANCELLATION - Trading status suspended cancellation\n* TREASURY_PAYMENT - Treasury payment\n* VIRTUAL_CASH_CORRECTION - Virtual cash correction\n* VIRTUAL_CASH_CORRECTION_CANCELLATION - Virtual cash correction cancellation\n* VIRTUAL_CASH_DECREASE - Virtual cash decreased\n* VIRTUAL_CASH_INCREASE - Virtual cash increased\n* WARRANT_EXERCISE - Warrant exercise\n* WARRANT_EXERCISE_CANCELLATION - Warrant exercise cancellation\n* WITHDRAWAL - Withdrawal\n* WITHDRAWAL_CANCELLATION - Withdrawal cancellation\n* WORTHLESS - Worthless\n* WORTHLESS_CANCELLATION - Worthless, Cancellation\n* WITHHOLDING_TAX_RELIEF_CERTIFICATION - Withholding tax relief certification\n* WITHHOLDING_TAX_RELIEF_CERTIFICATION_CANCELLATION - Withholding tax relief certification cancellation", "type": "string", "enum": [ "ACCUMULATION", "ACCUMULATION_CANCELLATION", "ANNUAL_GENERAL_MEETING", "ANNUAL_GENERAL_MEETING_CANCELLATION", "ATTACHMENT", "ATTACHMENT_CANCELLATION", "BALANCE_CORRECTION", "BALANCE_CORRECTION_CANCELLATION", "BANKRUPTCY", "BANKRUPTCY_CANCELLATION", "BOND_DEFAULT", "BOND_DEFAULT_CANCELLATION", "BOND_HOLDER_MEETING", "BOND_HOLDER_MEETING_CANCELLATION", "BONUS_ISSUE", "BONUS_ISSUE_CANCELLATION", "CALL_ON_INTERMEDIATE_SECURITIES", "CALL_ON_INTERMEDIATE_SECURITIES_CANCELLATION", "CAPITAL_DISTRIBUTION", "CAPITAL_DISTRIBUTION_CANCELLATION", "CAPITAL_GAINS_DISTRIBUTION", "CAPITAL_GAINS_DISTRIBUTION_CANCELLATION", "CAPITALISATION", "CAPITALISATION_CANCELLATION", "CASH_DISTRIBUTION_FROM_NON_ELIGIBLE_SECURITIES_SALES", "CASH_DISTRIBUTION_FROM_NON_ELIGIBLE_SECURITIES_SALES_CANCELLATION", "CASH_DIVIDEND", "CASH_DIVIDEND_CANCELLATION", "CHANGE", "CHANGE_CANCELLATION", "CLASS_ACTION", "CLASS_ACTION_CANCELLATION", "COMPANY_OPTION", "COMPANY_OPTION_CANCELLATION", "CONSENT", "CONSENT_CANCELLATION", "CONVERSION", "CONVERSION_CANCELLATION", "COURT_MEETING", "COURT_MEETING_CANCELLATION", "CREDIT_EVENT", "CREDIT_EVENT_CANCELLATION", "CREDIT_FUNDING", "CREDIT_FUNDING_CHARGE_BACK", "DD_REFUND_REJECT_FEE", "DD_REFUND_REJECT_FEE_CANCELLATION", "DECREASE_IN_VALUE", "DECREASE_IN_VALUE_CANCELLATION", "DETACHMENT", "DETACHMENT_CANCELLATION", "DISCLOSURE", "DISCLOSURE_CANCELLATION", "DIVIDEND_OPTION", "DIVIDEND_OPTION_CANCELLATION", "DIVIDEND_REINVESTMENT", "DIVIDEND_REINVESTMENT_CANCELLATION", "DRAWING", "DRAWING_CANCELLATION", "DUTCH_AUCTION", "DUTCH_AUCTION_CANCELLATION", "EXCHANGE", "EXCHANGE_CANCELLATION", "EXTRAORDINARY_OR_SPECIAL_GENERAL_MEETING", "EXTRAORDINARY_OR_SPECIAL_GENERAL_MEETING_CANCELLATION", "FEE_COLLECTION", "FEE_COLLECTION_CANCELLATION", "FINAL_MATURITY", "FINAL_MATURITY_CANCELLATION", "FULL_CALL", "FULL_CALL_CANCELLATION", "INCREASE_IN_VALUE", "INCREASE_IN_VALUE_CANCELLATION", "INFORMATION", "INFORMATION_CANCELLATION", "INSTALMENT_CALL", "INSTALMENT_CALL_CANCELLATION", "INTEREST_PAYMENT", "INTEREST_PAYMENT_CANCELLATION", "INTERMEDIATE_SECURITIES_DISTRIBUTION", "INTERMEDIATE_SECURITIES_DISTRIBUTION_CANCELLATION", "INTERNAL_CASH_TRANSFER", "INTERNAL_CASH_TRANSFER_CANCELLATION", "ISA_TRANSFER", "LIQUIDATION_PAYMENT", "LIQUIDATION_PAYMENT_CANCELLATION", "MATURITY_EXTENSION", "MATURITY_EXTENSION_CANCELLATION", "MERGER", "MERGER_CANCELLATION", "NON_OFFICIAL_OFFER", "NON_OFFICIAL_OFFER_CANCELLATION", "NON_US_TEFRA_D_CERTIFICATION", "NON_US_TEFRA_D_CERTIFICATION_CANCELLATION", "ODD_LOT_SALE", "ODD_LOT_SALE_CANCELLATION", "ORDER_EXECUTION", "ORDER_EXECUTION_CANCELLATION", "ORDINARY_GENERAL_MEETING", "ORDINARY_GENERAL_MEETING_CANCELLATION", "OTHER_EVENT", "OTHER_EVENT_CANCELLATION", "PARI_PASSU", "PARI_PASSU_CANCELLATION", "PARTIAL_DEFEASANCE", "PARTIAL_DEFEASANCE_CANCELLATION", "PARTIAL_REDEMPTION_WITH_POOL_FACTOR_REDUCTION", "PARTIAL_REDEMPTION_WITH_POOL_FACTOR_REDUCTION_CANCELLATION", "PARTIAL_REDEMPTION_WITHOUT_POOL_FACTOR_REDUCTION", "PARTIAL_REDEMPTION_WITHOUT_POOL_FACTOR_REDUCTION_CANCELLATION", "PAY_IN_KIND", "PAY_IN_KIND_CANCELLATION", "PEAK_FRACTION_COMPENSATION", "PEAK_ORDER_ADJUSTMENT", "PLACE_OF_INCORPORATION", "PLACE_OF_INCORPORATION_CANCELLATION", "PRIORITY_ISSUE", "PRIORITY_ISSUE_CANCELLATION", "PUT_REDEMPTION", "PUT_REDEMPTION_CANCELLATION", "REDENOMINATION", "REDENOMINATION_CANCELLATION", "REMARKETING_AGREEMENT", "REMARKETING_AGREEMENT_CANCELLATION", "REPURCHASE_OFFER", "REPURCHASE_OFFER_CANCELLATION", "REVERSE_STOCK_SPLIT", "REVERSE_STOCK_SPLIT_CANCELLATION", "RIGHTS_ISSUE", "RIGHTS_ISSUE_CANCELLATION", "SCRIP_DIVIDEND", "SCRIP_DIVIDEND_CANCELLATION", "SEPA_DIRECT_DEBIT", "SEPA_DIRECT_DEBIT_CHARGE_BACK", "SHARES_PREMIUM_DIVIDEND", "SHARES_PREMIUM_DIVIDEND_CANCELLATION", "SMALLEST_NEGOTIABLE_UNIT", "SMALLEST_NEGOTIABLE_UNIT_CANCELLATION", "SPIN_OFF", "SPIN_OFF_CANCELLATION", "STOCK_DIVIDEND", "STOCK_DIVIDEND_CANCELLATION", "STOCK_SPLIT", "STOCK_SPLIT_CANCELLATION", "TAX_ON_NON_DISTRIBUTED_PROCEEDS", "TAX_ON_NON_DISTRIBUTED_PROCEEDS_CANCELLATION", "TAX_PAYMENT", "TAX_PREPAYMENT_DE", "TAX_RECLAIM", "TAX_RECLAIM_CANCELLATION", "TAX_REFUND", "TENDER", "TENDER_CANCELLATION", "TOPUP", "TOPUP_CANCELLATION", "TRADING_STATUS_ACTIVE", "TRADING_STATUS_ACTIVE_CANCELLATION", "TRADING_STATUS_DELISTED", "TRADING_STATUS_DELISTED_CANCELLATION", "TRADING_STATUS_SUSPENDED", "TRADING_STATUS_SUSPENDED_CANCELLATION", "TREASURY_PAYMENT", "VIRTUAL_CASH_CORRECTION", "VIRTUAL_CASH_CORRECTION_CANCELLATION", "VIRTUAL_CASH_DECREASE", "VIRTUAL_CASH_INCREASE", "WARRANT_EXERCISE", "WARRANT_EXERCISE_CANCELLATION", "WITHDRAWAL", "WITHDRAWAL_CANCELLATION", "WORTHLESS", "WORTHLESS_CANCELLATION", "WITHHOLDING_TAX_RELIEF_CERTIFICATION", "WITHHOLDING_TAX_RELIEF_CERTIFICATION_CANCELLATION" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "value_date": { "title": "Transaction value date", "type": "string", "description": "Transaction value date and time. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)", "format": "date-time" } }, "required": [ "id", "type", "account_group_id", "delta", "taxes", "taxes_details", "references", "booking_date", "value_date", "created_at", "updated_at" ], "additionalProperties": true }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "examples": { "cash_dividend": { "summary": "Cash Dividend", "value": { "id": "55a877ce-effa-11ed-a05b-0242ac120003", "created_at": "2023-01-01T00:00:00.000Z", "type": "CASH_TRANSACTION.EXECUTED", "object": { "id": "6dc9fbca-8835-11ed-a217-2eabd0c03f8a", "created_at": "2023-01-01T00:00:00.000Z", "updated_at": "2023-01-01T00:00:00.000Z", "type": "CASH_DIVIDEND", "account_id": "0255e6c4-effa-11ed-a05b-0242ac120003", "account_group_id": "6409e3f2-8835-11ed-96a4-2eabd0c03f8a", "instrument": { "uuid": "ccb86937-8a39-4160-8d33-85bf9e902321", "isin": "US0378331005" }, "delta": { "amount": "25.00", "currency": "EUR" }, "taxes": [ { "amount": "2.00", "currency": "EUR", "type": "TOTAL" } ], "taxes_details": { "total_amount": { "amount": "2.00", "currency": "EUR" }, "tax_breakdown": [ { "amount": "0.50", "currency": "EUR", "type": "INTERNATIONAL_WITHHOLDING_TAX", "taxing_jurisdiction": "FR" }, { "amount": "0.20", "currency": "EUR", "type": "CAPITAL_GAINS", "taxing_jurisdiction": "FR" }, { "amount": "0.80", "currency": "EUR", "type": "SOLIDARITY_SURCHARGE", "taxing_jurisdiction": "DE" }, { "amount": "0.50", "currency": "EUR", "type": "CHURCH_TAX", "taxing_jurisdiction": "DE" } ] }, "references": [ { "id": "c29a9ee8-ed64-11ef-a2e4-2eabd0c03f8a", "type": "CORPORATE_ACTION" }, { "id": "1f5758d3-1ef7-4b4c-96ec-6b3da2bf1a8a", "type": "CORPORATE_ACTION_TRANSACTION_ID" } ], "booking_date": "2023-01-01T00:00:00.000Z", "value_date": "2023-01-01T00:00:00.000Z" }, "webhook_id": "9d3ac2e0-effa-11ed-a05b-0242ac120003" } }, "cash_dividend_cancellation": { "summary": "Cash Dividend Cancellation", "value": { "id": "e23218bc-effa-11ed-a05b-0242ac120003", "created_at": "2023-01-01T00:00:00.000Z", "type": "CASH_TRANSACTION.EXECUTED", "object": { "id": "dafd9954-effa-11ed-a05b-0242ac120003", "created_at": "2023-01-01T00:00:00.000Z", "updated_at": "2023-01-01T00:00:00.000Z", "type": "CASH_DIVIDEND_CANCELLATION", "account_id": "0255e6c4-effa-11ed-a05b-0242ac120003", "account_group_id": "6409e3f2-8835-11ed-96a4-2eabd0c03f8a", "instrument": { "uuid": "ccb86937-8a39-4160-8d33-85bf9e902321", "isin": "US0378331005" }, "delta": { "amount": "-25.00", "currency": "EUR" }, "taxes": [ { "amount": "-2.00", "currency": "EUR", "type": "TOTAL" } ], "taxes_details": { "total_amount": { "amount": "-2.00", "currency": "EUR" }, "tax_breakdown": [ { "amount": "-0.50", "currency": "EUR", "type": "INTERNATIONAL_WITHHOLDING_TAX", "taxing_jurisdiction": "FR" }, { "amount": "-0.20", "currency": "EUR", "type": "CAPITAL_GAINS", "taxing_jurisdiction": "FR" }, { "amount": "-0.80", "currency": "EUR", "type": "SOLIDARITY_SURCHARGE", "taxing_jurisdiction": "DE" }, { "amount": "-0.50", "currency": "EUR", "type": "CHURCH_TAX", "taxing_jurisdiction": "DE" } ] }, "references": [ { "id": "1f5758d3-1ef7-4b4c-96ec-6b3da2bf1a8a", "type": "CORPORATE_ACTION_TRANSACTION_ID" } ], "booking_date": "2023-01-01T00:00:00.000Z", "value_date": "2023-01-01T00:00:00.000Z" }, "webhook_id": "d68273ae-effa-11ed-a05b-0242ac120003" } }, "buy_order_execution": { "summary": "Buy Order Execution", "value": { "id": "398278e2-8835-11ed-97e3-2eabd0c03f8a", "created_at": "2023-01-01T00:00:00.000Z", "type": "CASH_TRANSACTION.EXECUTED", "object": { "id": "6dc9fbca-8835-11ed-a217-2eabd0c03f8a", "created_at": "2023-01-01T00:00:00.000Z", "updated_at": "2023-01-01T00:00:00.000Z", "type": "ORDER_EXECUTION", "account_group_id": "6409e3f2-8835-11ed-96a4-2eabd0c03f8a", "delta": { "amount": "-104.00", "currency": "EUR" }, "taxes": [ { "amount": "4.00", "currency": "EUR", "type": "TOTAL" } ], "taxes_details": { "total_amount": { "amount": "4.00", "currency": "EUR" }, "tax_breakdown": [ { "amount": "4.00", "currency": "EUR", "type": "FINANCIAL_TRANSACTION_TAX", "taxing_jurisdiction": "FR" } ] }, "references": [ { "id": "7579a672-8835-11ed-9455-2eabd0c03f8a", "type": "ORDER_EXECUTION" }, { "id": "1f5758d3-1ef7-4b4c-96ec-6b3da2bf1a8a", "type": "ORDER" } ], "booking_date": "2023-01-01T00:00:00.000Z", "value_date": "2023-01-01T00:00:00.000Z" }, "webhook_id": "35701970-effb-11ed-a05b-0242ac120003" } }, "buy_order_execution_with_fees_charged_by_client": { "summary": "Buy Order Execution with fees charged by client", "value": { "id": "398278e2-8835-11ed-97e3-2eabd0c03f8a", "created_at": "2023-01-01T00:00:00.000Z", "type": "CASH_TRANSACTION.EXECUTED", "object": { "id": "6dc9fbca-8835-11ed-a217-2eabd0c03f8a", "created_at": "2023-01-01T00:00:00.000Z", "updated_at": "2023-01-01T00:00:00.000Z", "type": "ORDER_EXECUTION", "account_group_id": "6409e3f2-8835-11ed-96a4-2eabd0c03f8a", "delta": { "amount": "-104.00", "currency": "EUR" }, "taxes": [ { "amount": "4.00", "currency": "EUR", "type": "TOTAL" } ], "taxes_details": { "total_amount": { "amount": "4.00", "currency": "EUR" }, "tax_breakdown": [ { "amount": "4.00", "currency": "EUR", "type": "FINANCIAL_TRANSACTION_TAX", "taxing_jurisdiction": "FR" } ] }, "fees": [ { "amount": "1.00", "currency": "EUR", "type": "TOTAL", "charge_method": "CHARGED_BY_CLIENT" } ], "references": [ { "id": "7579a672-8835-11ed-9455-2eabd0c03f8a", "type": "ORDER_EXECUTION" }, { "id": "1f5758d3-1ef7-4b4c-96ec-6b3da2bf1a8a", "type": "ORDER" } ], "booking_date": "2023-01-01T00:00:00.000Z", "value_date": "2023-01-01T00:00:00.000Z" }, "webhook_id": "35701970-effb-11ed-a05b-0242ac120003" } }, "buy_order_execution_with_fees_collected_by_upvest": { "summary": "Buy Order Execution with fees charged by client and collected by Upvest", "value": { "id": "398278e2-8835-11ed-97e3-2eabd0c03f8a", "created_at": "2023-01-01T00:00:00.000Z", "type": "CASH_TRANSACTION.EXECUTED", "object": { "id": "6dc9fbca-8835-11ed-a217-2eabd0c03f8a", "created_at": "2023-01-01T00:00:00.000Z", "updated_at": "2023-01-01T00:00:00.000Z", "type": "ORDER_EXECUTION", "account_group_id": "6409e3f2-8835-11ed-96a4-2eabd0c03f8a", "delta": { "amount": "-105.00", "currency": "EUR" }, "taxes": [ { "amount": "4.00", "currency": "EUR", "type": "TOTAL" } ], "taxes_details": { "total_amount": { "amount": "4.00", "currency": "EUR" }, "tax_breakdown": [ { "amount": "4.00", "currency": "EUR", "type": "FINANCIAL_TRANSACTION_TAX", "taxing_jurisdiction": "FR" } ] }, "fees": [ { "amount": "1.00", "currency": "EUR", "type": "TOTAL", "charge_method": "COLLECTED_BY_UPVEST" } ], "references": [ { "id": "7579a672-8835-11ed-9455-2eabd0c03f8a", "type": "ORDER_EXECUTION" }, { "id": "1f5758d3-1ef7-4b4c-96ec-6b3da2bf1a8a", "type": "ORDER" }, { "id": "6add5e16-79eb-11f0-8944-3aa3573bef52", "type": "TRANSACTION_FEE_EXECUTION" } ], "booking_date": "2023-01-01T00:00:00.000Z", "value_date": "2023-01-01T00:00:00.000Z" }, "webhook_id": "35701970-effb-11ed-a05b-0242ac120003" } }, "buy_order_execution_cancellation": { "summary": "Buy Order Execution Cancellation", "value": { "id": "1dac4156-effb-11ed-a05b-0242ac120003", "created_at": "2023-01-01T00:00:00.000Z", "type": "CASH_TRANSACTION.EXECUTED", "object": { "id": "25c56ab6-effb-11ed-a05b-0242ac120003", "created_at": "2023-01-01T00:00:00.000Z", "updated_at": "2023-01-01T00:00:00.000Z", "type": "ORDER_EXECUTION_CANCELLATION", "account_group_id": "6409e3f2-8835-11ed-96a4-2eabd0c03f8a", "delta": { "amount": "104.00", "currency": "EUR" }, "taxes": [ { "amount": "-4.00", "currency": "EUR", "type": "TOTAL" } ], "taxes_details": { "total_amount": { "amount": "-4.00", "currency": "EUR" }, "tax_breakdown": [ { "amount": "-4.00", "currency": "EUR", "type": "FINANCIAL_TRANSACTION_TAX", "taxing_jurisdiction": "FR" } ] }, "references": [ { "id": "7579a672-8835-11ed-9455-2eabd0c03f8a", "type": "ORDER_EXECUTION" }, { "id": "1f5758d3-1ef7-4b4c-96ec-6b3da2bf1a8a", "type": "ORDER" } ], "booking_date": "2023-01-01T00:00:00.000Z", "value_date": "2023-01-01T00:00:00.000Z" }, "webhook_id": "162db946-effb-11ed-a05b-0242ac120003" } }, "sell_order_execution": { "summary": "Sell Order Execution", "value": { "id": "398278e2-8835-11ed-97e3-2eabd0c03f8a", "created_at": "2023-01-01T00:00:00.000Z", "type": "CASH_TRANSACTION.EXECUTED", "object": { "id": "6dc9fbca-8835-11ed-a217-2eabd0c03f8a", "created_at": "2023-01-01T00:00:00.000Z", "updated_at": "2023-01-01T00:00:00.000Z", "type": "ORDER_EXECUTION", "account_group_id": "6409e3f2-8835-11ed-96a4-2eabd0c03f8a", "delta": { "amount": "96.00", "currency": "EUR" }, "taxes": [ { "amount": "4.00", "currency": "EUR", "type": "TOTAL" } ], "taxes_details": { "total_amount": { "amount": "4.00", "currency": "EUR" }, "tax_breakdown": [ { "amount": "1.50", "currency": "EUR", "type": "SOLIDARITY_SURCHARGE", "taxing_jurisdiction": "DE" }, { "amount": "0.50", "currency": "EUR", "type": "CHURCH_TAX", "taxing_jurisdiction": "DE" }, { "amount": "2.00", "currency": "EUR", "type": "CAPITAL_GAINS", "taxing_jurisdiction": "DE" } ] }, "references": [ { "id": "7579a672-8835-11ed-9455-2eabd0c03f8a", "type": "ORDER_EXECUTION" }, { "id": "1f5758d3-1ef7-4b4c-96ec-6b3da2bf1a8a", "type": "ORDER" } ], "booking_date": "2023-01-01T00:00:00.000Z", "value_date": "2023-01-01T00:00:00.000Z" }, "webhook_id": "35701970-effb-11ed-a05b-0242ac120003" } }, "sell_order_execution_cancellation": { "summary": "Sell Order Execution Cancellation", "value": { "id": "1dac4156-effb-11ed-a05b-0242ac120003", "created_at": "2023-01-01T00:00:00.000Z", "type": "CASH_TRANSACTION.EXECUTED", "object": { "id": "25c56ab6-effb-11ed-a05b-0242ac120003", "created_at": "2023-01-01T00:00:00.000Z", "updated_at": "2023-01-01T00:00:00.000Z", "type": "ORDER_EXECUTION_CANCELLATION", "account_group_id": "6409e3f2-8835-11ed-96a4-2eabd0c03f8a", "delta": { "amount": "-96.00", "currency": "EUR" }, "taxes": [ { "amount": "-4.00", "currency": "EUR", "type": "TOTAL" } ], "taxes_details": { "total_amount": { "amount": "-4.00", "currency": "EUR" }, "tax_breakdown": [ { "amount": "-1.50", "currency": "EUR", "type": "SOLIDARITY_SURCHARGE", "taxing_jurisdiction": "DE" }, { "amount": "-0.50", "currency": "EUR", "type": "CHURCH_TAX", "taxing_jurisdiction": "DE" }, { "amount": "-2.00", "currency": "EUR", "type": "CAPITAL_GAINS", "taxing_jurisdiction": "DE" } ] }, "references": [ { "id": "7579a672-8835-11ed-9455-2eabd0c03f8a", "type": "ORDER_EXECUTION" }, { "id": "1f5758d3-1ef7-4b4c-96ec-6b3da2bf1a8a", "type": "ORDER" } ], "booking_date": "2023-01-01T00:00:00.000Z", "value_date": "2023-01-01T00:00:00.000Z" }, "webhook_id": "162db946-effb-11ed-a05b-0242ac120003" } }, "fee_collection": { "summary": "Fee Collection", "value": { "id": "1d27576e-f4a3-11ed-a05b-0242ac120003", "created_at": "2023-01-01T00:00:00.000Z", "type": "CASH_TRANSACTION.EXECUTED", "object": { "id": "2349857c-f4a3-11ed-a05b-0242ac120003", "created_at": "2023-01-01T00:00:00.000Z", "updated_at": "2023-01-01T00:00:00.000Z", "type": "FEE_COLLECTION", "account_group_id": "6409e3f2-8835-11ed-96a4-2eabd0c03f8a", "delta": { "amount": "-10.00", "currency": "EUR" }, "taxes": [], "taxes_details": { "total_amount": { "amount": "0.00", "currency": "EUR" }, "tax_breakdown": [] }, "references": [ { "id": "17c36d9e-f4a3-11ed-a05b-0242ac120003", "type": "FEE_COLLECTION" } ], "booking_date": "2023-01-01T00:00:00.000Z", "value_date": "2023-01-01T00:00:00.000Z" }, "webhook_id": "1216067c-f4a3-11ed-a05b-0242ac120003" } }, "fee_collection_cancellation": { "summary": "Fee Collection Cancellation", "value": { "id": "3cdfad72-f4a3-11ed-a05b-0242ac120003", "created_at": "2023-01-01T00:00:00.000Z", "type": "CASH_TRANSACTION.EXECUTED", "object": { "id": "2349857c-f4a3-11ed-a05b-0242ac120003", "created_at": "2023-01-01T00:00:00.000Z", "updated_at": "2023-01-01T00:00:00.000Z", "type": "FEE_COLLECTION_CANCELLATION", "account_group_id": "6409e3f2-8835-11ed-96a4-2eabd0c03f8a", "delta": { "amount": "10.00", "currency": "EUR" }, "taxes": [], "taxes_details": { "total_amount": { "amount": "0.00", "currency": "EUR" }, "tax_breakdown": [] }, "references": [ { "id": "45d15c46-f4a3-11ed-a05b-0242ac120003", "type": "FEE_COLLECTION" } ], "booking_date": "2023-01-01T00:00:00.000Z", "value_date": "2023-01-01T00:00:00.000Z" }, "webhook_id": "40fb1252-f4a3-11ed-a05b-0242ac120003" } }, "sepa_direct_debit": { "summary": "Sepa Direct Debit", "value": { "id": "a9a76224-eff8-11ed-a05b-0242ac120003", "created_at": "2023-01-01T00:00:00.000Z", "type": "CASH_TRANSACTION.EXECUTED", "object": { "id": "9e7a3188-eff8-11ed-a05b-0242ac120003", "created_at": "2023-01-01T00:00:00.000Z", "updated_at": "2023-01-01T00:00:00.000Z", "type": "SEPA_DIRECT_DEBIT", "account_group_id": "6409e3f2-8835-11ed-96a4-2eabd0c03f8a", "delta": { "amount": "305.00", "currency": "EUR" }, "taxes": [], "taxes_details": { "total_amount": { "amount": "0.00", "currency": "EUR" }, "tax_breakdown": [] }, "references": [ { "id": "98f01200-eff8-11ed-a05b-0242ac120003", "type": "DIRECT_DEBIT" } ], "booking_date": "2023-01-01T00:00:00.000Z", "value_date": "2023-01-01T00:00:00.000Z" }, "webhook_id": "9390c822-eff8-11ed-a05b-0242ac120003" } }, "sepa_direct_debit_chargeback": { "summary": "Sepa Direct Debit Chargeback", "value": { "id": "2e471146-eff9-11ed-a05b-0242ac120003", "created_at": "2023-01-01T00:00:00.000Z", "type": "CASH_TRANSACTION.EXECUTED", "object": { "id": "23547364-eff9-11ed-a05b-0242ac120003", "created_at": "2023-01-01T00:00:00.000Z", "updated_at": "2023-01-01T00:00:00.000Z", "type": "SEPA_DIRECT_DEBIT_CHARGE_BACK", "account_group_id": "6409e3f2-8835-11ed-96a4-2eabd0c03f8a", "delta": { "amount": "-305.00", "currency": "EUR" }, "taxes": [], "taxes_details": { "total_amount": { "amount": "0.00", "currency": "EUR" }, "tax_breakdown": [] }, "references": [ { "id": "1d2a347e-eff9-11ed-a05b-0242ac120003", "type": "DIRECT_DEBIT" } ], "booking_date": "2023-01-01T00:00:00.000Z", "value_date": "2023-01-01T00:00:00.000Z" }, "webhook_id": "060844b6-eff9-11ed-a05b-0242ac120003" } }, "topup": { "summary": "Top-up", "value": { "id": "e619bf74-effb-11ed-a05b-0242ac120003", "created_at": "2023-01-01T00:00:00.000Z", "type": "CASH_TRANSACTION.EXECUTED", "object": { "id": "e165c4b4-effb-11ed-a05b-0242ac120003", "created_at": "2023-01-01T00:00:00.000Z", "updated_at": "2023-01-01T00:00:00.000Z", "type": "TOPUP", "account_group_id": "6409e3f2-8835-11ed-96a4-2eabd0c03f8a", "delta": { "amount": "100.00", "currency": "EUR" }, "taxes": [], "taxes_details": { "total_amount": { "amount": "0.00", "currency": "EUR" }, "tax_breakdown": [] }, "references": [ { "id": "dbf4d0a6-effb-11ed-a05b-0242ac120003", "type": "TOPUP" } ], "booking_date": "2023-01-01T00:00:00.000Z", "value_date": "2023-01-01T00:00:00.000Z" }, "webhook_id": "d53b06f4-effb-11ed-a05b-0242ac120003" } }, "withdrawal": { "summary": "Withdrawal", "value": { "id": "398278e2-8835-11ed-97e3-2eabd0c03f8a", "created_at": "2023-01-01T00:00:00.000Z", "type": "CASH_TRANSACTION.EXECUTED", "object": { "id": "6dc9fbca-8835-11ed-a217-2eabd0c03f8a", "created_at": "2023-01-01T00:00:00.000Z", "updated_at": "2023-01-01T00:00:00.000Z", "type": "WITHDRAWAL", "account_group_id": "6409e3f2-8835-11ed-96a4-2eabd0c03f8a", "delta": { "amount": "-305.00", "currency": "EUR" }, "taxes": [], "taxes_details": { "total_amount": { "amount": "0.00", "currency": "EUR" }, "tax_breakdown": [] }, "references": [ { "id": "1f5758d3-1ef7-4b4c-96ec-6b3da2bf1a8a", "type": "WITHDRAWAL" } ], "booking_date": "2023-01-01T00:00:00.000Z", "value_date": "2023-01-01T00:00:00.000Z" }, "webhook_id": "7eea34e2-8835-11ed-a47e-2eabd0c03f8a" } }, "withdrawal_cancellation": { "summary": "Withdrawal Cancellation", "value": { "id": "10cabec6-effc-11ed-a05b-0242ac120003", "created_at": "2023-01-01T00:00:00.000Z", "type": "CASH_TRANSACTION.EXECUTED", "object": { "id": "15750eae-effc-11ed-a05b-0242ac120003", "created_at": "2023-01-01T00:00:00.000Z", "updated_at": "2023-01-01T00:00:00.000Z", "type": "WITHDRAWAL_CANCELLATION", "account_group_id": "6409e3f2-8835-11ed-96a4-2eabd0c03f8a", "delta": { "amount": "305.00", "currency": "EUR" }, "taxes": [], "taxes_details": { "total_amount": { "amount": "0.00", "currency": "EUR" }, "tax_breakdown": [] }, "references": [ { "id": "1cffa512-effc-11ed-a05b-0242ac120003", "type": "WITHDRAWAL" } ], "booking_date": "2023-01-01T00:00:00.000Z", "value_date": "2023-01-01T00:00:00.000Z" }, "webhook_id": "0d0edd62-effc-11ed-a05b-0242ac120003" } }, "internal_cash_transfer": { "summary": "Internal Cash Transfer", "value": { "id": "e619bf74-effb-11ed-a05b-0242ac120003", "created_at": "2023-01-01T00:00:00.000Z", "type": "CASH_TRANSACTION.EXECUTED", "object": { "id": "e165c4b4-effb-11ed-a05b-0242ac120003", "created_at": "2023-01-01T00:00:00.000Z", "updated_at": "2023-01-01T00:00:00.000Z", "type": "INTERNAL_CASH_TRANSFER", "account_group_id": "6409e3f2-8835-11ed-96a4-2eabd0c03f8a", "delta": { "amount": "100.00", "currency": "EUR" }, "taxes": [], "taxes_details": { "total_amount": { "amount": "0.00", "currency": "EUR" }, "tax_breakdown": [] }, "references": [ { "id": "dbf4d0a6-effb-11ed-a05b-0242ac120003", "type": "ACCOUNT_GROUP" }, { "id": "1a9c7e2b-3f4d-4e5a-8b6c-7d8e9f0a1b2c", "type": "CASH_BALANCE_TRANSFER" } ], "booking_date": "2023-01-01T00:00:00.000Z", "value_date": "2023-01-01T00:00:00.000Z" }, "webhook_id": "d53b06f4-effb-11ed-a05b-0242ac120003" } }, "isa_transfer": { "summary": "ISA Transfer", "value": { "id": "e619bf74-effb-11ed-a05b-0242ac120003", "created_at": "2023-01-01T00:00:00.000Z", "type": "CASH_TRANSACTION.EXECUTED", "object": { "id": "e165c4b4-effb-11ed-a05b-0242ac120003", "created_at": "2023-01-01T00:00:00.000Z", "updated_at": "2023-01-01T00:00:00.000Z", "type": "ISA_TRANSFER", "account_group_id": "6409e3f2-8835-11ed-96a4-2eabd0c03f8a", "delta": { "amount": "100.00", "currency": "GBP" }, "taxes": [], "taxes_details": { "total_amount": { "amount": "0.00", "currency": "GBP" }, "tax_breakdown": [] }, "references": [ { "id": "dbf4d0a6-effb-11ed-a05b-0242ac120003", "type": "ISA_TRANSFER" } ], "booking_date": "2023-01-01T00:00:00.000Z", "value_date": "2023-01-01T00:00:00.000Z" }, "webhook_id": "d53b06f4-effb-11ed-a05b-0242ac120003" } } } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Security transactions events": { "post": { "operationId": "security_transaction_event", "summary": "Security transactions events", "description": "Security transactions events", "tags": [ "Transactions" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Security Transactions - Callback", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type", "enum": [ "SECURITY_TRANSACTION.EXECUTED" ], "default": "SECURITY_TRANSACTION.EXECUTED" }, "object": { "title": "Security Transaction", "type": "object", "properties": { "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "booking_date": { "title": " Transaction booking date", "type": "string", "description": " Transaction booking date and time. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "delta": { "title": "Security transaction delta", "description": "Entity representing the security transaction delta.", "type": "object", "properties": { "amount": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" } }, "required": [ "amount" ], "additionalProperties": true }, "id": { "title": "Security transaction unique identifier", "type": "string", "description": "Security transaction unique identifier.", "format": "uuid" }, "instrument": { "title": "Instrument", "description": "Entity representing instrument.", "type": "object", "properties": { "uuid": { "description": "Internal instrument identifier.", "type": "string", "format": "uuid" }, "isin": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" } }, "required": [ "uuid" ], "additionalProperties": false }, "type": { "title": "Transaction type", "description": "Transaction type\n* ACCUMULATION - Accumulation\n* ACCUMULATION_CANCELLATION - Accumulation cancellation\n* ANNUAL_GENERAL_MEETING - Annual general meeting\n* ANNUAL_GENERAL_MEETING_CANCELLATION - Annual general meeting cancellation\n* ATTACHMENT - Attachment\n* ATTACHMENT_CANCELLATION - Attachment cancellation\n* BALANCE_CORRECTION - Balance correction\n* BALANCE_CORRECTION_CANCELLATION - Balance correction cancellation\n* BANKRUPTCY - Bankruptcy\n* BANKRUPTCY_CANCELLATION - Bankruptcy cancellation\n* BOND_DEFAULT - Bond default\n* BOND_DEFAULT_CANCELLATION - Bond default cancellation\n* BOND_HOLDER_MEETING - Bond holder meeting\n* BOND_HOLDER_MEETING_CANCELLATION - Bond holder meeting cancellation\n* BONUS_ISSUE - Bonus Issue/Capitalisation Issue\n* BONUS_ISSUE_CANCELLATION - Bonus Issue/Capitalisation Issue, Cancellation\n* CALL_ON_INTERMEDIATE_SECURITIES - Call on Intermediate Securities\n* CALL_ON_INTERMEDIATE_SECURITIES_CANCELLATION - Call on Intermediate Securities, Cancellation\n* CAPITAL_DISTRIBUTION - Capital distribution\n* CAPITAL_DISTRIBUTION_CANCELLATION - Capital distribution cancellation\n* CAPITAL_GAINS_DISTRIBUTION - Capital gains distribution\n* CAPITAL_GAINS_DISTRIBUTION_CANCELLATION - Capital gains distribution cancellation\n* CAPITALISATION - Capitalisation\n* CAPITALISATION_CANCELLATION - Capitalisation cancellation\n* CASH_DISTRIBUTION_FROM_NON_ELIGIBLE_SECURITIES_SALES - Cash distribution from non eligible securities sales\n* CASH_DISTRIBUTION_FROM_NON_ELIGIBLE_SECURITIES_SALES_CANCELLATION - Cash distribution from non eligible securities sales cancellation\n* CASH_DIVIDEND - Cash dividend\n* CASH_DIVIDEND_CANCELLATION - Cash dividend cancellation\n* CHANGE - Change\n* CHANGE_CANCELLATION - Change, Cancellation\n* CLASS_ACTION - Class action\n* CLASS_ACTION_CANCELLATION - Class action cancellation\n* COMPANY_OPTION - Company option\n* COMPANY_OPTION_CANCELLATION - Company option cancellation\n* CONSENT - Consent\n* CONSENT_CANCELLATION - Consent cancellation\n* CONVERSION - Conversion\n* CONVERSION_CANCELLATION - Conversion cancellation\n* COURT_MEETING - Court meeting\n* COURT_MEETING_CANCELLATION - Court meeting cancellation\n* CREDIT_EVENT - Credit event\n* CREDIT_EVENT_CANCELLATION - Credit event cancellation\n* DECREASE_IN_VALUE - Decrease in value\n* DECREASE_IN_VALUE_CANCELLATION - Decrease in value cancellation\n* DETACHMENT - Detachment\n* DETACHMENT_CANCELLATION - Detachment cancellation\n* DISCLOSURE - Disclosure\n* DISCLOSURE_CANCELLATION - Disclosure cancellation\n* DIVIDEND_OPTION - Dividend Option\n* DIVIDEND_OPTION_CANCELLATION - Dividend Option, Cancellation\n* DIVIDEND_REINVESTMENT - Dividend Reinvestment\n* DIVIDEND_REINVESTMENT_CANCELLATION - Dividend Reinvestment, Cancellation\n* DRAWING - Drawing\n* DRAWING_CANCELLATION - Drawing cancellation\n* DUST_CLEANUP - Dust Cleanup\n* DUTCH_AUCTION - Dutch Auction\n* DUTCH_AUCTION_CANCELLATION - Dutch Auction, Cancellation\n* EXCHANGE - Exchange\n* EXCHANGE_CANCELLATION - Exchange cancellation\n* EXTRAORDINARY_OR_SPECIAL_GENERAL_MEETING - Extraordinary or special general meeting\n* EXTRAORDINARY_OR_SPECIAL_GENERAL_MEETING_CANCELLATION - Extraordinary or special general meeting cancellation\n* FINAL_MATURITY - Final maturity\n* FINAL_MATURITY_CANCELLATION - Final maturity cancellation\n* FULL_CALL - Full call\n* FULL_CALL_CANCELLATION - Full call cancellation\n* INCREASE_IN_VALUE - Increase in value\n* INCREASE_IN_VALUE_CANCELLATION - Increase in value cancellation\n* INFORMATION - Information\n* INFORMATION_CANCELLATION - Information cancellation\n* INSTALMENT_CALL - Instalment call\n* INSTALMENT_CALL_CANCELLATION - Instalment call cancellation\n* INTEREST_PAYMENT - Interest payment\n* INTEREST_PAYMENT_CANCELLATION - Interest payment cancellation\n* INTERMEDIATE_SECURITIES_DISTRIBUTION - Intermediate Securities Distribution\n* INTERMEDIATE_SECURITIES_DISTRIBUTION_CANCELLATION - Intermediate Securities Distribution, Cancellation\n* LIQUIDATION_PAYMENT - Liquidation Dividend/Liquidation Payment\n* LIQUIDATION_PAYMENT_CANCELLATION - Liquidation Dividend/Liquidation Payment, Cancellation\n* MATURITY_EXTENSION - Maturity extension\n* MATURITY_EXTENSION_CANCELLATION - Maturity extension cancellation\n* MERGER - Merger\n* MERGER_CANCELLATION - Merger, Cancellation\n* NON_OFFICIAL_OFFER - Non-Official Offer\n* NON_OFFICIAL_OFFER_CANCELLATION - Non-Official Offer, Cancellation\n* NON_US_TEFRA_D_CERTIFICATION - Non us tefra d certification\n* NON_US_TEFRA_D_CERTIFICATION_CANCELLATION - Non us tefra d certification cancellation\n* ODD_LOT_SALE - Odd Lot Sale/Purchase\n* ODD_LOT_SALE_CANCELLATION - Odd Lot Sale/Purchase, Cancellation\n* ORDER_EXECUTION - Order execution\n* ORDER_EXECUTION_CANCELLATION - Order execution cancellation\n* ORDINARY_GENERAL_MEETING - Ordinary general meeting\n* ORDINARY_GENERAL_MEETING_CANCELLATION - Ordinary general meeting cancellation\n* OTHER_EVENT - Other Event\n* OTHER_EVENT_CANCELLATION - Other Event cancellation\n* PARI_PASSU - Pari passu\n* PARI_PASSU_CANCELLATION - Pari passu cancellation\n* PARTIAL_DEFEASANCE - Partial defeasance\n* PARTIAL_DEFEASANCE_CANCELLATION - Partial defeasance cancellation\n* PARTIAL_REDEMPTION_WITH_POOL_FACTOR_REDUCTION - Partial redemption with pool factor reduction\n* PARTIAL_REDEMPTION_WITH_POOL_FACTOR_REDUCTION_CANCELLATION - Partial redemption with pool factor reduction cancellation\n* PARTIAL_REDEMPTION_WITHOUT_POOL_FACTOR_REDUCTION - Partial redemption without pool factor reduction\n* PARTIAL_REDEMPTION_WITHOUT_POOL_FACTOR_REDUCTION_CANCELLATION - Partial redemption without pool factor reduction cancellation\n* PAY_IN_KIND - Pay in kind\n* PAY_IN_KIND_CANCELLATION - Pay in kind cancellation\n* PEAK_FRACTION_COMPENSATION - Peak fraction compensation\n* PEAK_ORDER_ADJUSTMENT - Peak order adjustment\n* PLACE_OF_INCORPORATION - Place of incorporation\n* PLACE_OF_INCORPORATION_CANCELLATION - Place of incorporation cancellation\n* PRIORITY_ISSUE - Priority Issue\n* PRIORITY_ISSUE_CANCELLATION - Priority Issue, Cancellation\n* PUT_REDEMPTION - Put redemption\n* PUT_REDEMPTION_CANCELLATION - Put redemption cancellation\n* REDENOMINATION - Redenomination\n* REDENOMINATION_CANCELLATION - Redenomination cancellation\n* REMARKETING_AGREEMENT - Remarketing agreement\n* REMARKETING_AGREEMENT_CANCELLATION - Remarketing agreement cancellation\n* REPURCHASE_OFFER - Repurchase Offer/Issuer Bid/Reverse Rights\n* REPURCHASE_OFFER_CANCELLATION - Repurchase Offer/Issuer Bid/Reverse Rights, Cancellation\n* REVERSE_STOCK_SPLIT - Reverse Stock Split/Change in Nominal Value\n* REVERSE_STOCK_SPLIT_CANCELLATION - Reverse Stock Split/Change in Nominal Value, Cancellation\n* RIGHTS_ISSUE - Rights Issue/Subscription Rights/Rights Offer\n* RIGHTS_ISSUE_CANCELLATION - Rights Issue/Subscription Rights/Rights Offer, Cancellation\n* SCRIP_DIVIDEND - Scrip dividend\n* SCRIP_DIVIDEND_CANCELLATION - Scrip dividend cancellation\n* SECURITIES_TRANSFER - Securities transfer\n* SECURITIES_TRANSFER_CANCELLATION - Securities transfer cancellation\n* SHARES_PREMIUM_DIVIDEND - Shares premium dividend\n* SHARES_PREMIUM_DIVIDEND_CANCELLATION - Shares premium dividend cancellation\n* SMALLEST_NEGOTIABLE_UNIT - Smallest negotiable unit\n* SMALLEST_NEGOTIABLE_UNIT_CANCELLATION - Smallest negotiable unit cancellation\n* SPIN_OFF - Spin-Off\n* SPIN_OFF_CANCELLATION - Spin-Off, Cancellation\n* STOCK_DIVIDEND - Stock Dividend\n* STOCK_DIVIDEND_CANCELLATION - Stock Dividend, Cancellation\n* STOCK_SPLIT - Stock Split/Change in Nominal Value/Subdivision\n* STOCK_SPLIT_CANCELLATION - Stock Split/Change in Nominal Value/Subdivision, Cancellation\n* TAX_ON_NON_DISTRIBUTED_PROCEEDS - Tax on non distributed proceeds\n* TAX_ON_NON_DISTRIBUTED_PROCEEDS_CANCELLATION - Tax on non distributed proceeds cancellation\n* TAX_RECLAIM - Tax reclaim\n* TAX_RECLAIM_CANCELLATION - Tax reclaim cancellation\n* TENDER - Tender/Acquisition/Takeover/Purchase Offer\n* TENDER_CANCELLATION - Tender/Acquisition/Takeover/Purchase Offer, Cancellation\n* TRADING_STATUS_ACTIVE - Trading status active\n* TRADING_STATUS_ACTIVE_CANCELLATION - Trading status active cancellation\n* TRADING_STATUS_DELISTED - Trading status delisted\n* TRADING_STATUS_DELISTED_CANCELLATION - Trading status delisted cancellation\n* TRADING_STATUS_SUSPENDED - Trading status suspended\n* TRADING_STATUS_SUSPENDED_CANCELLATION - Trading status suspended cancellation\n* VIRTUAL_CASH_CORRECTION_CANCELLATION - Virtual cash correction cancellation\n* WARRANT_EXERCISE - Warrant exercise\n* WARRANT_EXERCISE_CANCELLATION - Warrant exercise cancellation\n* WITHHOLDING_TAX_RELIEF_CERTIFICATION - Withholding tax relief certification\n* WITHHOLDING_TAX_RELIEF_CERTIFICATION_CANCELLATION - Withholding tax relief certification cancellation\n* WORTHLESS - Worthless\n* WORTHLESS_CANCELLATION - Worthless, Cancellation\n* SECURITIES_LENDING - Securities lending", "type": "string", "enum": [ "ACCUMULATION", "ACCUMULATION_CANCELLATION", "ANNUAL_GENERAL_MEETING", "ANNUAL_GENERAL_MEETING_CANCELLATION", "ATTACHMENT", "ATTACHMENT_CANCELLATION", "BALANCE_CORRECTION", "BALANCE_CORRECTION_CANCELLATION", "BANKRUPTCY", "BANKRUPTCY_CANCELLATION", "BOND_DEFAULT", "BOND_DEFAULT_CANCELLATION", "BOND_HOLDER_MEETING", "BOND_HOLDER_MEETING_CANCELLATION", "BONUS_ISSUE", "BONUS_ISSUE_CANCELLATION", "CALL_ON_INTERMEDIATE_SECURITIES", "CALL_ON_INTERMEDIATE_SECURITIES_CANCELLATION", "CAPITAL_DISTRIBUTION", "CAPITAL_DISTRIBUTION_CANCELLATION", "CAPITAL_GAINS_DISTRIBUTION", "CAPITAL_GAINS_DISTRIBUTION_CANCELLATION", "CAPITALISATION", "CAPITALISATION_CANCELLATION", "CASH_DISTRIBUTION_FROM_NON_ELIGIBLE_SECURITIES_SALES", "CASH_DISTRIBUTION_FROM_NON_ELIGIBLE_SECURITIES_SALES_CANCELLATION", "CASH_DIVIDEND", "CASH_DIVIDEND_CANCELLATION", "CHANGE", "CHANGE_CANCELLATION", "CLASS_ACTION", "CLASS_ACTION_CANCELLATION", "COMPANY_OPTION", "COMPANY_OPTION_CANCELLATION", "CONSENT", "CONSENT_CANCELLATION", "CONVERSION", "CONVERSION_CANCELLATION", "COURT_MEETING", "COURT_MEETING_CANCELLATION", "CREDIT_EVENT", "CREDIT_EVENT_CANCELLATION", "DECREASE_IN_VALUE", "DECREASE_IN_VALUE_CANCELLATION", "DETACHMENT", "DETACHMENT_CANCELLATION", "DISCLOSURE", "DISCLOSURE_CANCELLATION", "DIVIDEND_OPTION", "DIVIDEND_OPTION_CANCELLATION", "DIVIDEND_REINVESTMENT", "DIVIDEND_REINVESTMENT_CANCELLATION", "DRAWING", "DRAWING_CANCELLATION", "DUST_CLEANUP", "DUTCH_AUCTION", "DUTCH_AUCTION_CANCELLATION", "EXCHANGE", "EXCHANGE_CANCELLATION", "EXTRAORDINARY_OR_SPECIAL_GENERAL_MEETING", "EXTRAORDINARY_OR_SPECIAL_GENERAL_MEETING_CANCELLATION", "FINAL_MATURITY", "FINAL_MATURITY_CANCELLATION", "FULL_CALL", "FULL_CALL_CANCELLATION", "INCREASE_IN_VALUE", "INCREASE_IN_VALUE_CANCELLATION", "INFORMATION", "INFORMATION_CANCELLATION", "INSTALMENT_CALL", "INSTALMENT_CALL_CANCELLATION", "INTEREST_PAYMENT", "INTEREST_PAYMENT_CANCELLATION", "INTERMEDIATE_SECURITIES_DISTRIBUTION", "INTERMEDIATE_SECURITIES_DISTRIBUTION_CANCELLATION", "LIQUIDATION_PAYMENT", "LIQUIDATION_PAYMENT_CANCELLATION", "MATURITY_EXTENSION", "MATURITY_EXTENSION_CANCELLATION", "MERGER", "MERGER_CANCELLATION", "NON_OFFICIAL_OFFER", "NON_OFFICIAL_OFFER_CANCELLATION", "NON_US_TEFRA_D_CERTIFICATION", "NON_US_TEFRA_D_CERTIFICATION_CANCELLATION", "ODD_LOT_SALE", "ODD_LOT_SALE_CANCELLATION", "ORDER_EXECUTION", "ORDER_EXECUTION_CANCELLATION", "ORDINARY_GENERAL_MEETING", "ORDINARY_GENERAL_MEETING_CANCELLATION", "OTHER_EVENT", "OTHER_EVENT_CANCELLATION", "PARI_PASSU", "PARI_PASSU_CANCELLATION", "PARTIAL_DEFEASANCE", "PARTIAL_DEFEASANCE_CANCELLATION", "PARTIAL_REDEMPTION_WITH_POOL_FACTOR_REDUCTION", "PARTIAL_REDEMPTION_WITH_POOL_FACTOR_REDUCTION_CANCELLATION", "PARTIAL_REDEMPTION_WITHOUT_POOL_FACTOR_REDUCTION", "PARTIAL_REDEMPTION_WITHOUT_POOL_FACTOR_REDUCTION_CANCELLATION", "PAY_IN_KIND", "PAY_IN_KIND_CANCELLATION", "PEAK_FRACTION_COMPENSATION", "PEAK_ORDER_ADJUSTMENT", "PLACE_OF_INCORPORATION", "PLACE_OF_INCORPORATION_CANCELLATION", "PRIORITY_ISSUE", "PRIORITY_ISSUE_CANCELLATION", "PUT_REDEMPTION", "PUT_REDEMPTION_CANCELLATION", "REDENOMINATION", "REDENOMINATION_CANCELLATION", "REMARKETING_AGREEMENT", "REMARKETING_AGREEMENT_CANCELLATION", "REPURCHASE_OFFER", "REPURCHASE_OFFER_CANCELLATION", "REVERSE_STOCK_SPLIT", "REVERSE_STOCK_SPLIT_CANCELLATION", "RIGHTS_ISSUE", "RIGHTS_ISSUE_CANCELLATION", "SCRIP_DIVIDEND", "SCRIP_DIVIDEND_CANCELLATION", "SECURITIES_TRANSFER", "SECURITIES_TRANSFER_CANCELLATION", "SHARES_PREMIUM_DIVIDEND", "SHARES_PREMIUM_DIVIDEND_CANCELLATION", "SMALLEST_NEGOTIABLE_UNIT", "SMALLEST_NEGOTIABLE_UNIT_CANCELLATION", "SPIN_OFF", "SPIN_OFF_CANCELLATION", "STOCK_DIVIDEND", "STOCK_DIVIDEND_CANCELLATION", "STOCK_SPLIT", "STOCK_SPLIT_CANCELLATION", "TAX_ON_NON_DISTRIBUTED_PROCEEDS", "TAX_ON_NON_DISTRIBUTED_PROCEEDS_CANCELLATION", "TAX_RECLAIM", "TAX_RECLAIM_CANCELLATION", "TENDER", "TENDER_CANCELLATION", "TRADING_STATUS_ACTIVE", "TRADING_STATUS_ACTIVE_CANCELLATION", "TRADING_STATUS_DELISTED", "TRADING_STATUS_DELISTED_CANCELLATION", "TRADING_STATUS_SUSPENDED", "TRADING_STATUS_SUSPENDED_CANCELLATION", "VIRTUAL_CASH_CORRECTION_CANCELLATION", "WARRANT_EXERCISE", "WARRANT_EXERCISE_CANCELLATION", "WITHHOLDING_TAX_RELIEF_CERTIFICATION", "WITHHOLDING_TAX_RELIEF_CERTIFICATION_CANCELLATION", "WORTHLESS", "WORTHLESS_CANCELLATION", "SECURITIES_LENDING" ] }, "references": { "type": "array", "items": { "title": "Security transaction reference", "description": "Entity representing security transaction reference.", "type": "object", "properties": { "id": { "title": "Unique identifier for a resource of given type", "type": "string", "description": "Unique identifier for a resource of given type.", "format": "uuid" }, "type": { "type": "string", "description": "Type of the reference.\n* ORDER - Order\n* ORDER_EXECUTION - Order execution\n* CORPORATE_ACTION - Corporate action\n* CORPORATE_ACTION_TRANSACTION_ID - Corporate action transaction ID", "enum": [ "ORDER", "ORDER_EXECUTION", "CORPORATE_ACTION", "CORPORATE_ACTION_TRANSACTION_ID" ] } }, "required": [ "id", "type" ], "additionalProperties": false } }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "value_date": { "title": "Transaction value date", "type": "string", "description": "Transaction value date and time. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)", "format": "date-time" } }, "required": [ "id", "type", "account_id", "account_group_id", "instrument", "delta", "references", "value_date", "booking_date", "created_at", "updated_at" ], "additionalProperties": true }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "examples": { "order_execution": { "summary": "Order Execution", "value": { "id": "543c9996-eff6-11ed-a05b-0242ac120003", "created_at": "2023-01-01T00:00:00.000Z", "type": "SECURITY_TRANSACTION.EXECUTED", "object": { "id": "6dc9fbca-8835-11ed-a217-2eabd0c03f8a", "created_at": "2023-01-01T00:00:00.000Z", "updated_at": "2023-01-01T00:00:00.000Z", "type": "ORDER_EXECUTION", "account_id": "db6290bb-1491-45bf-aafe-262dad59d497", "account_group_id": "6409e3f2-8835-11ed-96a4-2eabd0c03f8a", "instrument": { "uuid": "ccb86937-8a39-4160-8d33-85bf9e902321", "isin": "US0378331005" }, "delta": { "amount": "-2.5234543879" }, "references": [ { "id": "7579a672-8835-11ed-9455-2eabd0c03f8a", "type": "ORDER_EXECUTION" }, { "id": "1f5758d3-1ef7-4b4c-96ec-6b3da2bf1a8a", "type": "ORDER" } ], "booking_date": "2023-01-01T00:00:00.000Z", "value_date": "2023-01-01T00:00:00.000Z" }, "webhook_id": "3ae8a8a4-eff6-11ed-a05b-0242ac120003" } }, "order_execution_cancellation": { "summary": "Order Execution Cancellation", "value": { "id": "398278e2-8835-11ed-97e3-2eabd0c03f8a", "created_at": "2023-01-01T00:00:00.000Z", "type": "SECURITY_TRANSACTION.EXECUTED", "object": { "id": "6dc9fbca-8835-11ed-a217-2eabd0c03f8a", "created_at": "2023-01-01T00:00:00.000Z", "updated_at": "2023-01-01T00:00:00.000Z", "type": "ORDER_EXECUTION_CANCELLATION", "account_id": "db6290bb-1491-45bf-aafe-262dad59d497", "account_group_id": "6409e3f2-8835-11ed-96a4-2eabd0c03f8a", "instrument": { "uuid": "ccb86937-8a39-4160-8d33-85bf9e902321", "isin": "US0378331005" }, "delta": { "amount": "2.5234543879" }, "references": [ { "id": "7579a672-8835-11ed-9455-2eabd0c03f8a", "type": "ORDER_EXECUTION" }, { "id": "1f5758d3-1ef7-4b4c-96ec-6b3da2bf1a8a", "type": "ORDER" } ], "booking_date": "2023-01-01T00:00:00.000Z", "value_date": "2023-01-01T00:00:00.000Z" }, "webhook_id": "fd9690e2-effa-11ed-a05b-0242ac120003" } }, "merger": { "summary": "Merger", "value": { "id": "71478127-4688-46b6-b3c6-871febb20330", "created_at": "2023-01-01T00:00:00.000Z", "type": "SECURITY_TRANSACTION.EXECUTED", "object": { "id": "f0f6834a-ddc8-4ef4-b4e2-025a6bbd1cf1", "created_at": "2023-01-01T00:00:00.000Z", "updated_at": "2023-01-01T00:00:00.000Z", "type": "MERGER", "account_id": "db6290bb-1491-45bf-aafe-262dad59d497", "account_group_id": "6409e3f2-8835-11ed-96a4-2eabd0c03f8a", "instrument": { "uuid": "ccb86937-8a39-4160-8d33-85bf9e902321", "isin": "US0378331005" }, "delta": { "amount": "32.52" }, "references": [ { "id": "7f3a087b-2934-40f0-a311-caab2e449d9b", "type": "CORPORATE_ACTION" }, { "id": "f29af46d-d424-4b87-b656-ab2cb46e460c", "type": "CORPORATE_ACTION_TRANSACTION_ID" } ], "booking_date": "2023-01-01T00:00:00.000Z", "value_date": "2023-01-01T00:00:00.000Z" }, "webhook_id": "52a47a86-8805-43be-b631-d79e67bb5da9" } } } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Treasury reports events": { "post": { "operationId": "treasury_report_event", "summary": "Treasury reports events", "description": "Treasury reports events. `TREASURY_REPORT.CREATED` is emitted when a treasury settlement report has been generated. `TREASURY_REPORT.CONFIRMED` is emitted once the treasury operation covered by the report has been completed. It carries the same report payload as the corresponding `TREASURY_REPORT.CREATED` event and can be correlated with it via the `object.id` and `object.filename` fields. When branches are configured for the tenant, a separate treasury settlement report is generated per branch and each report emits its own set of events.", "tags": [ "Treasury Reports" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Treasury report - Callback", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type", "enum": [ "TREASURY_REPORT.CREATED", "TREASURY_REPORT.CONFIRMED" ] }, "object": { "title": "Treasury report", "type": "object", "properties": { "id": { "title": "Treasury operation unique identifier", "type": "string", "format": "uuid" }, "type": { "type": "string", "description": "Treasury operation type.\n* TRADING - \n* CORPORATE_ACTION - \n* FEE - \n* TAX - \n* TAX_ADJUSTMENT_RECEIVABLE - \n* TAX_ADJUSTMENT_PAYABLE - \n* TRANSACTION_FEE - ", "enum": [ "TRADING", "CORPORATE_ACTION", "FEE", "TAX", "TAX_ADJUSTMENT_RECEIVABLE", "TAX_ADJUSTMENT_PAYABLE", "TRANSACTION_FEE" ] }, "currency": { "type": "string", "description": "The currency of the treasury payment. Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code." }, "settlement_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "report_date": { "description": "The date when the treasury report was created.", "type": "string", "format": "date" }, "direction": { "type": "string", "description": "Direction of the treasury operation.\n* INCOMING - \n* OUTGOING - \n* NA - ", "enum": [ "INCOMING", "OUTGOING", "NA" ] }, "filename": { "description": "The report name. When branches are configured for the tenant, treasury reports are generated separately per branch and the report name carries the branch name as a suffix, e.g. `buy_trading_08052023_.csv`. Activity of users without an assigned branch is delivered in the standard report without a branch suffix.", "type": "string" } }, "required": [ "id", "type", "currency", "settlement_amount", "report_date", "direction", "filename" ], "additionalProperties": false }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "examples": { "Created": { "summary": "Report created", "value": { "id": "8962b496-8d42-4560-bfab-10490dd1a721", "created_at": "2023-05-08T10:42:34.758Z", "type": "TREASURY_REPORT.CREATED", "object": { "id": "6e736b54-ed57-46ad-8620-0ef59ddd8e6d", "type": "TRADING", "currency": "EUR", "settlement_amount": "123.12", "report_date": "2023-05-08", "direction": "OUTGOING", "filename": "buy_trading_08052023.csv" }, "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6" } }, "Confirmed": { "summary": "Report confirmed", "value": { "id": "f3b1a9c2-7d44-4e21-9b6a-83c5de40f117", "created_at": "2023-05-08T14:22:11.123Z", "type": "TREASURY_REPORT.CONFIRMED", "object": { "id": "6e736b54-ed57-46ad-8620-0ef59ddd8e6d", "type": "TRADING", "currency": "EUR", "settlement_amount": "123.12", "report_date": "2023-05-08", "direction": "OUTGOING", "filename": "buy_trading_08052023.csv" }, "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6" } } } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Reports events": { "post": { "operationId": "report_event", "summary": "Reports events", "description": "Report events for either a natural person or a business entity.", "tags": [ "Reports" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Reports - Callback", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type", "enum": [ "REPORT.CREATED" ], "default": "REPORT.CREATED" }, "object": { "title": "Report", "anyOf": [ { "title": "User Report", "type": "object", "properties": { "id": { "title": "Report unique identifier.", "type": "string", "description": "Report unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "type": { "title": "Report type", "description": "Report type\n* ACCOUNT_CLOSING - Securities account closure\n* ACCOUNT_OPENING - Securities account opening\n* AD_HOC_ACCOUNT_STATEMENT - Ad hoc account statement\n* ANNUAL_INCOME_STATEMENT - Annual tax income statement (\"Erträgnisaufstellung\")\n* ANNUAL_TAX_STATEMENT - Annual tax reporting\n* BANK_ACCOUNT_CONNECTED - Connect reference bank account\n* BUY_ORDER - Buy order\n* CANCELLED_ORDER - Cancelled buy or sell order (not yet executed, user cancels or trading venue cancelled)\n* CORPORATE_ACTION_CASH_TRANSACTION - cash transaction document (after corporate action)\n* CORPORATE_ACTION_SECURITY_TRANSACTION - security transaction document (after corporate action)\n* DIRECT_DEBIT_MANDATE - Creation of SEPA direct debit mandate\n* EX_POST_COST - Ex-post cost report\n* FEE_COLLECTION - Intake of service fees\n* FRENCH_IFU - French tax statement (Imprimé fiscal unique)\n* GENERIC_COMMUNICATION - Generic communication\n* INCOME_DISTRIBUTION - Income distribution report\n* LOSS_THRESHOLD - Notification that a holding has depreciated by 10%, or a multiple thereof, against its purchase value\n* MONTHLY_BILLING_STATEMENT - Monthly billing activities statement\n* QUARTERLY_ACCOUNT_STATEMENT - Quarterly account statement\n* REVOKED_ORDER - Revoked buy or sell order (\"Storno\")\n* SECURITIES_TRANSFER_INCOMING - Securities are transferred in\n* SECURITIES_TRANSFER_OUTGOING - Securities are being transferred out\n* SELL_ORDER - Sell order\n* TAX_CONSOLIDATED_CERTIFICATE_UK - UK Consolidated Tax Certificate\n* TAX_PAYMENT - Tax payment document\n* TAX_PREPAYMENT_DE - German tax prepayment (Vorabpauschale)\n* TAX_PREPAYMENT_DE_CANCELLATION - German tax prepayment (Vorabpauschale) cancellation\n* TAX_REFUND - Tax refund document (after tax optimization)", "type": "string", "enum": [ "ACCOUNT_CLOSING", "ACCOUNT_OPENING", "AD_HOC_ACCOUNT_STATEMENT", "ANNUAL_INCOME_STATEMENT", "ANNUAL_TAX_STATEMENT", "BANK_ACCOUNT_CONNECTED", "BUY_ORDER", "CANCELLED_ORDER", "CORPORATE_ACTION_CASH_TRANSACTION", "CORPORATE_ACTION_SECURITY_TRANSACTION", "DIRECT_DEBIT_MANDATE", "EX_POST_COST", "FEE_COLLECTION", "FRENCH_IFU", "GENERIC_COMMUNICATION", "INCOME_DISTRIBUTION", "LOSS_THRESHOLD", "MONTHLY_BILLING_STATEMENT", "QUARTERLY_ACCOUNT_STATEMENT", "REVOKED_ORDER", "SECURITIES_TRANSFER_INCOMING", "SECURITIES_TRANSFER_OUTGOING", "SELL_ORDER", "TAX_CONSOLIDATED_CERTIFICATE_UK", "TAX_PAYMENT", "TAX_PREPAYMENT_DE", "TAX_PREPAYMENT_DE_CANCELLATION", "TAX_REFUND" ] }, "substituted_report_id": { "oneOf": [ { "type": "null" }, { "title": "Substituted Report unique identifier.", "type": "string", "description": "References report that has been replaced by this one.", "format": "uuid" } ] }, "data": { "title": "Report Data", "type": "object", "description": "Contents of the report.", "properties": { "account": { "type": "object", "title": "Account.", "description": "Account information.", "properties": { "id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" } } }, "references": { "type": "array", "title": "References.", "items": { "title": "Report reference data", "type": "object", "description": "Reference data for a report", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "title": "Report reference type", "description": "Report reference type\n* CORPORATE_ACTION_TRANSACTION_ID - Corporate action transaction identifier\n* ACCOUNT_GROUP_ID - Account group identifier\n* ACCOUNT_ID - Account identifier\n* ORDER_ID - Order identifier", "type": "string", "enum": [ "CORPORATE_ACTION_TRANSACTION_ID", "ACCOUNT_GROUP_ID", "ACCOUNT_ID", "ORDER_ID" ] } } } } } } }, "required": [ "id", "user_id", "created_at", "type", "substituted_report_id" ], "additionalProperties": false }, { "title": "Business Report", "type": "object", "properties": { "id": { "title": "Report unique identifier.", "type": "string", "description": "Report unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "business_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "type": { "title": "Report type", "description": "Report type\n* ACCOUNT_CLOSING - Securities account closure\n* ACCOUNT_OPENING - Securities account opening\n* AD_HOC_ACCOUNT_STATEMENT - Ad hoc account statement\n* ANNUAL_INCOME_STATEMENT - Annual tax income statement (\"Erträgnisaufstellung\")\n* ANNUAL_TAX_STATEMENT - Annual tax reporting\n* BANK_ACCOUNT_CONNECTED - Connect reference bank account\n* BUY_ORDER - Buy order\n* CANCELLED_ORDER - Cancelled buy or sell order (not yet executed, user cancels or trading venue cancelled)\n* CORPORATE_ACTION_CASH_TRANSACTION - cash transaction document (after corporate action)\n* CORPORATE_ACTION_SECURITY_TRANSACTION - security transaction document (after corporate action)\n* DIRECT_DEBIT_MANDATE - Creation of SEPA direct debit mandate\n* EX_POST_COST - Ex-post cost report\n* FEE_COLLECTION - Intake of service fees\n* FRENCH_IFU - French tax statement (Imprimé fiscal unique)\n* GENERIC_COMMUNICATION - Generic communication\n* INCOME_DISTRIBUTION - Income distribution report\n* LOSS_THRESHOLD - Notification that a holding has depreciated by 10%, or a multiple thereof, against its purchase value\n* MONTHLY_BILLING_STATEMENT - Monthly billing activities statement\n* QUARTERLY_ACCOUNT_STATEMENT - Quarterly account statement\n* REVOKED_ORDER - Revoked buy or sell order (\"Storno\")\n* SECURITIES_TRANSFER_INCOMING - Securities are transferred in\n* SECURITIES_TRANSFER_OUTGOING - Securities are being transferred out\n* SELL_ORDER - Sell order\n* TAX_CONSOLIDATED_CERTIFICATE_UK - UK Consolidated Tax Certificate\n* TAX_PAYMENT - Tax payment document\n* TAX_PREPAYMENT_DE - German tax prepayment (Vorabpauschale)\n* TAX_PREPAYMENT_DE_CANCELLATION - German tax prepayment (Vorabpauschale) cancellation\n* TAX_REFUND - Tax refund document (after tax optimization)", "type": "string", "enum": [ "ACCOUNT_CLOSING", "ACCOUNT_OPENING", "AD_HOC_ACCOUNT_STATEMENT", "ANNUAL_INCOME_STATEMENT", "ANNUAL_TAX_STATEMENT", "BANK_ACCOUNT_CONNECTED", "BUY_ORDER", "CANCELLED_ORDER", "CORPORATE_ACTION_CASH_TRANSACTION", "CORPORATE_ACTION_SECURITY_TRANSACTION", "DIRECT_DEBIT_MANDATE", "EX_POST_COST", "FEE_COLLECTION", "FRENCH_IFU", "GENERIC_COMMUNICATION", "INCOME_DISTRIBUTION", "LOSS_THRESHOLD", "MONTHLY_BILLING_STATEMENT", "QUARTERLY_ACCOUNT_STATEMENT", "REVOKED_ORDER", "SECURITIES_TRANSFER_INCOMING", "SECURITIES_TRANSFER_OUTGOING", "SELL_ORDER", "TAX_CONSOLIDATED_CERTIFICATE_UK", "TAX_PAYMENT", "TAX_PREPAYMENT_DE", "TAX_PREPAYMENT_DE_CANCELLATION", "TAX_REFUND" ] }, "substituted_report_id": { "oneOf": [ { "type": "null" }, { "title": "Substituted Report unique identifier.", "type": "string", "description": "References report that has been replaced by this one.", "format": "uuid" } ] }, "data": { "title": "Report Data", "type": "object", "description": "Contents of the report.", "properties": { "account": { "type": "object", "title": "Account.", "description": "Account information.", "properties": { "id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" } } }, "references": { "type": "array", "title": "References.", "items": { "title": "Report reference data", "type": "object", "description": "Reference data for a report", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "title": "Report reference type", "description": "Report reference type\n* CORPORATE_ACTION_TRANSACTION_ID - Corporate action transaction identifier\n* ACCOUNT_GROUP_ID - Account group identifier\n* ACCOUNT_ID - Account identifier\n* ORDER_ID - Order identifier", "type": "string", "enum": [ "CORPORATE_ACTION_TRANSACTION_ID", "ACCOUNT_GROUP_ID", "ACCOUNT_ID", "ORDER_ID" ] } } } } } } }, "required": [ "id", "business_id", "created_at", "type", "substituted_report_id" ], "additionalProperties": false }, { "title": "User Report - Order ex-ante cost", "type": "object", "properties": { "id": { "title": "Report unique identifier.", "type": "string", "description": "Report unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "type": { "type": "string", "enum": [ "ORDER_EX_ANTE_COST", "ORDER_EX_ANTE_COST_SAVINGS_PLAN" ], "description": "The type of report must be “ORDER_EX_ANTE_COST” or “ORDER_EX_ANTE_COST_SAVINGS_PLAN”." }, "substituted_report_id": { "oneOf": [ { "type": "null" }, { "title": "Substituted Report unique identifier.", "type": "string", "description": "References report that has been replaced by this one.", "format": "uuid" } ] }, "data": { "title": "User Report Data - Order ex-ante cost", "type": "object", "description": "Contents of the order-ex-ante cost report for a user.", "properties": { "holding_period": { "type": "object", "description": "Holding period.", "properties": { "unit": { "type": "string", "description": "Unit of time. \n* YEAR - ", "enum": [ "YEAR" ], "default": "YEAR" }, "quantity": { "description": "Quantity of time units.", "type": "integer" } } }, "instrument": { "type": "object", "description": "Instrument details.", "properties": { "isin": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, "short_name": { "description": "Instrument short name.", "type": "string", "maxLength": 100 } } }, "venue": { "type": "object", "description": "Venue details.", "properties": { "name": { "description": "Venue name.", "type": "string", "maxLength": 100 } } }, "account": { "type": "object", "description": "Account details.", "properties": { "id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "account_number": { "type": "integer", "description": "The serial account number of the account in the account group.", "minimum": 1 } } }, "account_group": { "type": "object", "description": "Account group details.", "properties": { "id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "securities_account_number": { "type": "string", "description": "Securities account number.", "pattern": "^[0-9]{9}$" } } }, "user": { "type": "object", "description": "User details.", "properties": { "first_name": { "type": "string", "maxLength": 100, "minLength": 2, "description": "First name of the user." }, "last_name": { "type": "string", "maxLength": 100, "minLength": 2, "description": "Last name of the user." }, "salutation": { "type": "string", "description": "Salutation of the user used in reports and statements.\n* (empty string) - \n* SALUTATION_MALE - \n* SALUTATION_FEMALE - \n* SALUTATION_FEMALE_MARRIED - \n* SALUTATION_DIVERSE - ", "enum": [ "", "SALUTATION_MALE", "SALUTATION_FEMALE", "SALUTATION_FEMALE_MARRIED", "SALUTATION_DIVERSE" ], "default": "" }, "title": { "type": "string", "description": "Addressed user's title is used in reports and statements.\n* (empty string) - \n* DR - Doctor\n* PROF - Professor\n* PROF_DR - \n* DIPL_ING - Graduate engineer (Diplom-Ingenieur)\n* MAGISTER - ", "enum": [ "", "DR", "PROF", "PROF_DR", "DIPL_ING", "MAGISTER" ], "default": "" }, "address": { "type": "object", "description": "User residential address.", "properties": { "address_line1": { "type": "string", "description": "First line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Country code. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "pattern": "^[A-Z]{2}$" }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } } } } }, "order": { "type": "object", "description": "Order details.", "properties": { "user_id": { "type": "string", "format": "uuid", "description": "The ID of the user." }, "account_id": { "type": "string", "format": "uuid", "description": "The ID of the account that owns the order." }, "cash_amount": { "allOf": [ { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, { "description": "Cash amount for a nominal order." } ] }, "currency": { "allOf": [ { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, { "description": "The currency for the order." } ] }, "side": { "type": "string", "description": "Side of the order.\n* BUY - \n* SELL - ", "enum": [ "BUY", "SELL" ] }, "instrument_id": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, "instrument_id_type": { "description": "The type of the ID used in the request.\n* ISIN - ", "enum": [ "ISIN" ], "default": "ISIN", "type": "string" }, "order_type": { "type": "string", "description": "Order type.\n* MARKET - \n* LIMIT - \n* STOP - ", "enum": [ "MARKET", "LIMIT", "STOP" ] }, "quantity": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "Quantity of securities for the order." } ] }, "limit_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The limit price for orders of the type 'limit'." } ] }, "stop_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The stop price for orders of the type 'stop'." } ] }, "price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The estimated price for the order. In case of LIMIT or STOP order provided LIMIT/STOP price will be used." } ] } } }, "return_impact": { "type": "object", "description": "Return impact.", "properties": { "year_one": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "year_two": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "year_three": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false } } }, "total_cost": { "title": "Order ex-ante aggregated cost", "type": "object", "description": "Aggregated totals of product costs, service costs and third party payments.", "properties": { "product": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "service": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "third_party": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "total": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false } }, "additionalProperties": false }, "product_cost": { "title": "Order ex-ante product cost", "type": "object", "description": "All costs and associated charges related to the financial instrument.", "properties": { "one_off": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "ongoing": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "transaction": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "incidental": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "total": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false } }, "additionalProperties": false }, "service_cost": { "title": "Order ex-ante service cost", "type": "object", "description": "All costs and associated charges related to the investment service(s) and/or ancillary services.", "properties": { "one_off": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "ongoing": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "transaction": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "ancillary": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "incidental": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "total": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false } }, "additionalProperties": false }, "third_party_payments": { "type": "object", "description": "Third-party payments associated with the investment service.", "properties": { "total": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "received_by_client": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "received_by_upvest": { "allOf": [ { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, { "description": "Third-party payments received by Upvest. Only returned when Upvest holds the investment-firm licence for the account (TOL). Omitted for tenants operating on their own licence (BYOL), where Upvest's share is not disclosed. It stays part of `total` either way, so `total` is not always the sum of the returned properties." } ] } }, "additionalProperties": false } }, "required": [ "user" ], "additionalProperties": false } }, "required": [ "id", "user_id", "created_at", "type", "substituted_report_id" ], "additionalProperties": false }, { "title": "Business Report - Order ex-ante cost", "type": "object", "properties": { "id": { "title": "Report unique identifier.", "type": "string", "description": "Report unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "business_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "type": { "title": "Business report type", "type": "string", "enum": [ "ORDER_EX_ANTE_COST" ], "description": "The type of report must be “ORDER_EX_ANTE_COST”. Savings plan ex-ante reports are not supported for business entities." }, "substituted_report_id": { "oneOf": [ { "type": "null" }, { "title": "Substituted Report unique identifier.", "type": "string", "description": "References report that has been replaced by this one.", "format": "uuid" } ] }, "data": { "title": "Business Report Data - Order ex-ante cost", "type": "object", "description": "Contents of the order ex-ante cost report for a business.", "properties": { "holding_period": { "type": "object", "description": "Holding period.", "properties": { "unit": { "type": "string", "description": "Unit of time. \n* YEAR - ", "enum": [ "YEAR" ], "default": "YEAR" }, "quantity": { "description": "Quantity of time units.", "type": "integer" } } }, "instrument": { "type": "object", "description": "Instrument details.", "properties": { "isin": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, "short_name": { "description": "Instrument short name.", "type": "string", "maxLength": 100 } } }, "venue": { "type": "object", "description": "Venue details.", "properties": { "name": { "description": "Venue name.", "type": "string", "maxLength": 100 } } }, "account": { "type": "object", "description": "Account details.", "properties": { "id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "account_number": { "type": "integer", "description": "The serial account number of the account in the account group.", "minimum": 1 } } }, "account_group": { "type": "object", "description": "Account group details.", "properties": { "id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "securities_account_number": { "type": "string", "description": "Securities account number.", "pattern": "^[0-9]{9}$" } } }, "business": { "type": "object", "description": "Business details.", "properties": { "company_name": { "type": "string", "description": "Name of the company." }, "address": { "title": "Address", "type": "object", "description": "Address. Must not be a P.O. box or c/o address.", "properties": { "address_line1": { "type": "string", "description": "First address line of the address.", "maxLength": 100 }, "address_line2": { "type": "string", "description": "Second address line of the address.", "maxLength": 100 }, "postcode": { "title": "Postal code", "type": "string", "description": "Postal code (postcode, PIN or ZIP code)", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\s\\-]{0,8}[a-zA-Z0-9]?$" }, "country": { "description": "Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "state": { "description": "State, province, county. [ISO 3166 alpha-2 Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "maxLength": 50 }, "city": { "title": "City name", "type": "string", "minLength": 1, "maxLength": 85 } }, "required": [ "address_line1", "postcode", "country", "city" ] } } }, "order": { "type": "object", "description": "Order details.", "properties": { "business_id": { "type": "string", "format": "uuid", "description": "The ID of the business." }, "account_id": { "type": "string", "format": "uuid", "description": "The ID of the account that owns the order." }, "cash_amount": { "allOf": [ { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, { "description": "Cash amount for a nominal order." } ] }, "currency": { "allOf": [ { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, { "description": "The currency for the order." } ] }, "side": { "type": "string", "description": "Side of the order.\n* BUY - \n* SELL - ", "enum": [ "BUY", "SELL" ] }, "instrument_id": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, "instrument_id_type": { "description": "The type of the ID used in the request.\n* ISIN - ", "enum": [ "ISIN" ], "default": "ISIN", "type": "string" }, "order_type": { "type": "string", "description": "Order type.\n* MARKET - \n* LIMIT - \n* STOP - ", "enum": [ "MARKET", "LIMIT", "STOP" ] }, "quantity": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "Quantity of securities for the order." } ] }, "limit_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The limit price for orders of the type 'limit'." } ] }, "stop_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The stop price for orders of the type STOP." } ] }, "price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The estimated price for the order. In case of LIMIT or STOP order provided LIMIT/STOP price will be used." } ] } } }, "return_impact": { "type": "object", "description": "Return impact.", "properties": { "year_one": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "year_two": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "year_three": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false } } }, "total_cost": { "title": "Order ex-ante aggregated cost", "type": "object", "description": "Aggregated totals of product costs, service costs and third party payments.", "properties": { "product": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "service": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "third_party": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "total": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false } }, "additionalProperties": false }, "product_cost": { "title": "Order ex-ante product cost", "type": "object", "description": "All costs and associated charges related to the financial instrument.", "properties": { "one_off": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "ongoing": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "transaction": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "incidental": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "total": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false } }, "additionalProperties": false }, "service_cost": { "title": "Order ex-ante service cost", "type": "object", "description": "All costs and associated charges related to the investment service(s) and/or ancillary services.", "properties": { "one_off": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "ongoing": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "transaction": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "ancillary": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "incidental": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "total": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false } }, "additionalProperties": false }, "third_party_payments": { "type": "object", "description": "Third party payments associated with the investment service.", "properties": { "total": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "received_by_client": { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, "received_by_upvest": { "allOf": [ { "title": "Cost", "type": "object", "properties": { "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "as_percentage": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The cost value represented as a percentage." } ] } }, "additionalProperties": false }, { "description": "Third-party payments received by Upvest. Only returned when Upvest holds the investment-firm licence for the account (TOL). Omitted for tenants operating on their own licence (BYOL), where Upvest's share is not disclosed. It stays part of `total` either way, so `total` is not always the sum of the returned properties." } ] } }, "additionalProperties": false } }, "required": [ "business" ], "additionalProperties": false } }, "required": [ "id", "business_id", "created_at", "type", "substituted_report_id" ], "additionalProperties": false } ] }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "examples": { "user_report": { "summary": "User report", "value": { "id": "8962b496-8d42-4560-bfab-10490dd1a721", "created_at": "2021-07-21T14:10:00.00Z", "type": "REPORT.CREATED", "object": { "id": "b96b1ee7-d491-43eb-b5e4-4833af9c9c2f", "created_at": "2020-08-24T14:15:22Z", "user_id": "d1a4be99-8bb6-4e78-b897-8168f6823ab5", "type": "CORPORATE_ACTION_CASH_TRANSACTION", "substituted_report_id": null, "data": { "account": { "id": "a9a4ad54-6dd1-419a-a98d-ab48f9f23bc8" }, "references": [ { "id": "b96b1ee7-d491-43eb-b5e4-4833af9c9c2f", "type": "CORPORATE_ACTION_TRANSACTION_ID" } ] } }, "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6" } }, "business_report": { "summary": "Business report", "value": { "id": "8962b496-8d42-4560-bfab-10490dd1a721", "created_at": "2021-07-21T14:10:00.00Z", "type": "REPORT.CREATED", "object": { "id": "b96b1ee7-d491-43eb-b5e4-4833af9c9c2f", "created_at": "2020-08-24T14:15:22Z", "business_id": "a9a72268-4f3c-4de2-abb9-a553a3bb7608", "type": "CORPORATE_ACTION_CASH_TRANSACTION", "substituted_report_id": null, "data": { "account": { "id": "a9a4ad54-6dd1-419a-a98d-ab48f9f23bc8" }, "references": [ { "id": "b96b1ee7-d491-43eb-b5e4-4833af9c9c2f", "type": "CORPORATE_ACTION_TRANSACTION_ID" } ] } }, "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6" } } } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Account events": { "post": { "operationId": "account_event", "summary": "Account events", "description": "Account events", "tags": [ "Accounts" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Accounts - Callback", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type", "enum": [ "ACCOUNT.CREATED", "ACCOUNT.ACTIVATED", "ACCOUNT.CLOSING_INITIATED", "ACCOUNT.CLOSED", "ACCOUNT.LOCKED", "ACCOUNT.UPDATED" ] }, "object": { "oneOf": [ { "title": "Account", "type": "object", "description": "", "properties": { "id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "type": { "type": "string", "description": "Account type.\n* TRADING - Orders in accounts of this type are created on a specific instrument basis.\n* PORTFOLIO - Orders in accounts of this type are created on a portfolio basis and additional portfolio functionality is available.", "enum": [ "TRADING", "PORTFOLIO" ] }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "type": { "type": "string", "description": "Relation type\n* OWNER - Account Group Owner\n* CHILD - Child Account Group Owner\n* GUARDIAN - Child Account Group Guardian", "enum": [ "OWNER", "GUARDIAN", "CHILD" ] } } } }, "account_number": { "type": "integer", "description": "The serial account number of the account in the account group.", "minimum": 1 }, "name": { "type": "string", "description": "The name of the account.", "maxLength": 100 }, "status": { "type": "string", "description": "The status of the account\n* PENDING_APPROVAL - Account approval is pending - the account is visible through our API but cannot be acted on.\n* ACTIVE - Account is active - full functionality of the Investment API is accessible.\n* CLOSING - Account is closing - only sell orders or the transfer of positions out are permissible before the account is closed.\n* CLOSED - Account is closed with zero balance successfully.\n* LOCKED - Account is locked for all actions.", "enum": [ "PENDING_APPROVAL", "ACTIVE", "CLOSING", "CLOSED", "LOCKED" ] } }, "required": [ "id", "created_at", "updated_at", "account_group_id", "type", "users", "name", "status", "account_number" ], "additionalProperties": false }, { "title": "Business Account", "type": "object", "description": "", "properties": { "id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "type": { "type": "string", "description": "Account type.\n* TRADING - Orders in accounts of this type are created on a specific instrument basis.\n* PORTFOLIO - Orders in accounts of this type are created on a portfolio basis and additional portfolio functionality is available.", "enum": [ "TRADING", "PORTFOLIO" ] }, "business_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "account_number": { "type": "integer", "description": "The serial account number of the account in the account group.", "minimum": 1 }, "name": { "type": "string", "description": "The name of the account.", "maxLength": 100 }, "status": { "type": "string", "description": "The status of the account\n* PENDING_APPROVAL - Account approval is pending - the account is visible through our API but cannot be acted on.\n* ACTIVE - Account is active - full functionality of the Investment API is accessible.\n* CLOSING - Account is closing - only sell orders or the transfer of positions out are permissible before the account is closed.\n* CLOSED - Account is closed with zero balance successfully.\n* LOCKED - Account is locked for all actions.", "enum": [ "PENDING_APPROVAL", "ACTIVE", "CLOSING", "CLOSED", "LOCKED" ] } }, "required": [ "id", "created_at", "updated_at", "account_group_id", "type", "business_id", "name", "status", "account_number" ], "additionalProperties": false } ] }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "examples": { "User Account": { "summary": "User account event", "value": { "id": "56510309-d9de-4730-9b5b-4a0ed047f3a9", "created_at": "2021-07-21T14:10:00.00Z", "type": "ACCOUNT.CREATED", "object": { "id": "ad45b27f-c0e7-4cfb-b48c-a83670dbdfbd", "created_at": "2020-08-24T14:15:22Z", "updated_at": "2020-08-24T14:15:22Z", "account_group_id": "fa2414ed-8d62-46fd-85ed-565a340c81d6", "type": "TRADING", "users": [ { "id": "9c36af78-91a0-4174-a515-fc81214e3dab", "type": "OWNER" } ], "account_number": 1, "name": "Main account", "status": "ACTIVE" }, "webhook_id": "b838bde5-b6df-4f1f-bfc4-71d3fb01d430" } }, "Business Account": { "summary": "Business account event", "value": { "id": "56510309-d9de-4730-9b5b-4a0ed047f3a9", "created_at": "2021-07-21T14:10:00.00Z", "type": "ACCOUNT.CREATED", "object": { "id": "ad45b27f-c0e7-4cfb-b48c-a83670dbdfbd", "created_at": "2020-08-24T14:15:22Z", "updated_at": "2020-08-24T14:15:22Z", "account_group_id": "fa2414ed-8d62-46fd-85ed-565a340c81d6", "type": "TRADING", "business_id": "bc6f8c82-1234-4b56-a7d8-9e012345f678", "account_number": 1, "name": "Main account", "status": "ACTIVE" }, "webhook_id": "b838bde5-b6df-4f1f-bfc4-71d3fb01d430" } } } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Account Group events": { "post": { "operationId": "account_group_event", "summary": "Account group events", "description": "Account group events", "tags": [ "Account Groups" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Account Groups - Callback", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type", "enum": [ "ACCOUNT_GROUP.CREATED", "ACCOUNT_GROUP.ACTIVATED", "ACCOUNT_GROUP.CLOSING_INITIATED", "ACCOUNT_GROUP.CLOSED", "ACCOUNT_GROUP.LOCKED", "ACCOUNT_GROUP.UPDATED" ] }, "object": { "oneOf": [ { "title": "Account Group", "type": "object", "description": "", "properties": { "id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "type": { "type": "string", "description": "Relation type\n* OWNER - Account Group Owner\n* CHILD - Child Account Group Owner\n* GUARDIAN - Child Account Group Guardian", "enum": [ "OWNER", "CHILD", "GUARDIAN" ] } } } }, "status": { "type": "string", "description": "Status of the account group\n* PENDING_APPROVAL - Account group approval is pending - the account group is visible through our API but cannot be acted on.\n* ACTIVE - Account group is active - full functionality of the Investment API is accessible.\n* CLOSING - Account group is closing.\n* CLOSED - Account group is closed.\n* LOCKED - Account group is locked for all actions.", "enum": [ "PENDING_APPROVAL", "ACTIVE", "CLOSING", "CLOSED", "LOCKED" ] }, "type": { "type": "string", "description": "Account group type.\n* PERSONAL - Account group of a person holding assets on their own behalf.\n* LEGAL_ENTITY - Account group of a legal entity holding assets on behalf of their users.\n* FRENCH_PEA - Account group of a french resident holding assets in Plan d'Epargne en Actions.\n* ISA - Account group of a UK resident holding assets in an individual savings account.\n* CHILD - Account group of a child user holding assets in a child account.", "enum": [ "PERSONAL", "LEGAL_ENTITY", "FRENCH_PEA", "ISA", "CHILD" ] }, "securities_account_number": { "title": "Securities Account number.", "type": "string", "description": "Account unique identifier.", "format": "^\\d{7,12}$" } }, "required": [ "id", "created_at", "updated_at", "users", "status", "type", "securities_account_number" ], "additionalProperties": false }, { "title": "Business Account Group", "type": "object", "description": "", "properties": { "id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "business_id": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, "status": { "type": "string", "description": "Status of the account group\n* PENDING_APPROVAL - Account group approval is pending - the account group is visible through our API but cannot be acted on.\n* ACTIVE - Account group is active - full functionality of the Investment API is accessible.\n* CLOSING - Account group is closing.\n* CLOSED - Account group is closed.\n* LOCKED - Account group is locked for all actions.", "enum": [ "PENDING_APPROVAL", "ACTIVE", "CLOSING", "CLOSED", "LOCKED" ] }, "type": { "type": "string", "description": "Account group type.\n* BUSINESS - Account group of a business holding assets.", "enum": [ "BUSINESS" ] }, "securities_account_number": { "title": "Securities Account number.", "type": "string", "description": "Account unique identifier.", "format": "^\\d{7,12}$" } }, "required": [ "id", "created_at", "updated_at", "business_id", "status", "type", "securities_account_number" ], "additionalProperties": false } ] }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "examples": { "User Account Group": { "summary": "User account group event", "value": { "id": "72da9e41-9926-419f-976e-4c8069a04249", "created_at": "2021-07-21T14:10:00.00Z", "type": "ACCOUNT_GROUP.CREATED", "object": { "id": "9d95820d-4333-46b6-98de-04ab7512e76f", "created_at": "2020-08-24T14:15:22Z", "updated_at": "2020-08-24T14:15:22Z", "type": "PERSONAL", "status": "ACTIVE", "users": [ { "id": "413715f2-5401-4b97-8055-034a6b879f8c", "type": "OWNER" } ], "securities_account_number": "123456789" }, "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6" } }, "Business Account Group": { "summary": "Business account group event", "value": { "id": "72da9e41-9926-419f-976e-4c8069a04249", "created_at": "2021-07-21T14:10:00.00Z", "type": "ACCOUNT_GROUP.CREATED", "object": { "id": "9d95820d-4333-46b6-98de-04ab7512e76f", "created_at": "2020-08-24T14:15:22Z", "updated_at": "2020-08-24T14:15:22Z", "type": "BUSINESS", "status": "ACTIVE", "business_id": "bc6f8c82-1234-4b56-a7d8-9e012345f678", "securities_account_number": "123456789" }, "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6" } } } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Direct Debit events": { "post": { "operationId": "direct_debit_event", "summary": "Direct Debit events", "description": "Webhook callback payload for direct debit lifecycle events. Delivered when a direct debit transitions to `DIRECT_DEBIT.NEW`, `DIRECT_DEBIT.PROCESSING`, `DIRECT_DEBIT.CONFIRMED`, or `DIRECT_DEBIT.CANCELLED`.", "tags": [ "Direct Debits" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Direct Debits - Callback", "type": "object", "description": "Webhook callback payload for direct debit lifecycle events (`DIRECT_DEBIT.NEW`, `DIRECT_DEBIT.PROCESSING`, `DIRECT_DEBIT.CONFIRMED`, `DIRECT_DEBIT.CANCELLED`).", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type", "enum": [ "DIRECT_DEBIT.NEW", "DIRECT_DEBIT.PROCESSING", "DIRECT_DEBIT.CONFIRMED", "DIRECT_DEBIT.CANCELLED" ] }, "object": { "type": "object", "description": "Represents a SEPA Direct Debit funding request for an account group. Debits are initiated via a mandate and transition through `NEW` → `PROCESSING` → `CONFIRMED` or `CANCELLED` as they are processed.", "properties": { "id": { "title": "Direct debit funding request unique identifier", "type": "string", "description": "Direct debit funding request unique identifier", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "allOf": [ { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" } ], "description": "The ID of the user. For business-initiated direct debits, this field will be absent.", "deprecated": true }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "mandate_id": { "title": "Direct Debit Mandate unique identifier.", "type": "string", "description": "Direct Debit Mandate unique identifier.", "format": "uuid" }, "cash_amount": { "type": "string", "pattern": "^-?[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "remittance_information": { "type": "string", "maxLength": 140, "pattern": "^[0-9A-Za-z+?/\\-:()\\.,';_ ]{0,140}$", "description": "Payment reference the end user will see in their bank statement for the corresponding direct debit booking (“Verwendungszweck”). We recommend that you keep this info concise and avoid special characters or non-standardised formatting ([see more](/documentation/guides/payments/direct_debit/direct_debit_submitting))." }, "status": { "type": "string", "description": "Status of the direct debit\n* NEW - Direct debit is created but not started processing.\n* PROCESSING - Direct debit is in processing.\n* CONFIRMED - Direct debit was successfully processed.\n* CANCELLED - Direct debit was cancelled.", "enum": [ "NEW", "PROCESSING", "CONFIRMED", "CANCELLED" ] }, "cancellation_reason": { "title": "Cancellation reason code for direct debit", "description": "Reason the direct debit was cancelled. The field is present in case the direct debit has a status of CANCELLED.\n* CANCELLED_BY_BANK - The payment was not completed by your bank. Please check your account details or contact support.\n* CANCELLED_BY_UPVEST - The payment was cancelled. Contact support for details.\n* CANCELLED_BY_CLIENT - The payment was cancelled at your request.\n* OTHER - Reason not available (applies to historical data only).", "type": "string", "enum": [ "CANCELLED_BY_BANK", "CANCELLED_BY_UPVEST", "CANCELLED_BY_CLIENT", "OTHER" ] }, "purpose_code": { "type": "string", "maxLength": 4, "description": "Purpose of the payment based on *ExternalPurpose1Code* from [ISO 20022](https://www.iso20022.org/catalogue-messages/additional-content-messages/external-code-sets)." } }, "required": [ "id", "created_at", "account_group_id", "mandate_id", "cash_amount", "currency" ], "additionalProperties": false }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "example": { "id": "8962b496-8d42-4560-bfab-10490dd1a721", "created_at": "2021-07-21T14:10:00.00Z", "type": "DIRECT_DEBIT.NEW", "object": { "id": "1ab4fef9-a097-4c6f-9345-647025d5fde6", "created_at": "2020-08-24T14:15:22Z", "user_id": "82b49999-1145-4e05-916a-567662daa7bc", "account_group_id": "1ea60f56-b67b-61fc-829a-0242ac130003", "mandate_id": "730b8719-0bc6-401d-98dd-b2de72afbf05", "cash_amount": "200.00", "currency": "EUR", "remittance_information": "payment for green energy portfolio", "status": "NEW" }, "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6" } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Top-up events": { "post": { "operationId": "topup_event", "summary": "Top-up events", "description": "Webhook callback payload for top-up lifecycle events. Delivered when a top-up transitions to `TOPUP.CONFIRMED`, `TOPUP.SETTLED`, or `TOPUP.CANCELLED`.", "tags": [ "Top-ups" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Top up - Callback", "type": "object", "description": "Webhook callback payload for top-up lifecycle events (`TOPUP.CONFIRMED`, `TOPUP.SETTLED`, `TOPUP.CANCELLED`).", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type", "enum": [ "TOPUP.CONFIRMED", "TOPUP.SETTLED", "TOPUP.CANCELLED" ] }, "object": { "type": "object", "description": "Represents a top-up funding request for an account group. After creation, the end user must send a SEPA Credit Transfer with the provided `settlement_reference` to complete the funding.", "properties": { "id": { "title": "Top up request unique identifier.", "type": "string", "description": "Top up request unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "settlement_reference": { "type": "string", "maxLength": 130, "pattern": "^[0-9A-Za-z+?/\\-:()\\.,'; ]{0,130}$", "description": "Settlement reference to be included in the corresponding bank transfer to settle this top up." }, "status": { "type": "string", "description": "Status of the top up\n* CONFIRMED - The top up is created and confirmed.\n* SETTLED - The top up is settled.\n* CANCELLED - The top up is cancelled", "enum": [ "CONFIRMED", "SETTLED", "CANCELLED" ] } }, "required": [ "id", "created_at", "account_group_id", "cash_amount", "currency" ], "additionalProperties": false }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "example": { "id": "ac62dbc4-c94e-45e4-a16e-381c51c8de38", "created_at": "2022-12-05T12:34:56Z", "type": "TOPUP.SETTLED", "object": { "id": "a4496ff8-ce69-4e23-9f2e-6c3c7914b95c", "account_group_id": "2a761567-251b-450e-8615-025d61dcc95e", "settlement_reference": "91a44df3-7278-4dee-a1bf-2bc254eca66c", "cash_amount": "100.01", "currency": "EUR", "created_at": "2022-12-05T12:34:56Z", "status": "SETTLED" }, "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6" } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Securities Transfers events": { "post": { "operationId": "securities_transfer_event", "summary": "Securities Transfers events", "description": "Securities Transfers events", "tags": [ "Securities Transfers" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Securities Transfers - Callback", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type", "enum": [ "SECURITIES_TRANSFER.NEW", "SECURITIES_TRANSFER.PROCESSING", "SECURITIES_TRANSFER.SETTLED", "SECURITIES_TRANSFER.CANCELLED", "SECURITIES_TRANSFER.DATA_CHANGED" ] }, "object": { "type": "object", "properties": { "id": { "title": "Securities transfer request unique identifier.", "type": "string", "description": "Securities transfer request unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "direction": { "type": "string", "description": "Direction of the securities transfer\n* `INCOMING` - Securities transfer is incoming to the user.\n* `OUTGOING` - Securities transfer is outgoing from the user.", "enum": [ "INCOMING", "OUTGOING" ] }, "status": { "type": "string", "description": "Status of the securities transfer\n* `NEW` - Securities transfer is created but not started processing.\n* `PROCESSING` - Securities transfer is in processing.\n* `SETTLED` - Securities transfer was successfully settled.\n* `CANCELLED` - Securities transfer was cancelled.", "enum": [ "NEW", "PROCESSING", "SETTLED", "CANCELLED" ] }, "transfer_type": { "type": "string", "description": "Type of the securities transfer\n* `NO_OWNER_CHANGE` - No change of ownership.", "enum": [ "NO_OWNER_CHANGE" ] }, "instrument_id": { "type": "string", "description": "`ISIN` or other identity (depends on instrument_id_type) of the security to be transferred." }, "instrument_id_type": { "type": "string", "description": "Type of the instrument_id\n* `ISIN` - International Securities Identification Number", "enum": [ "ISIN" ] }, "quantity": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$", "description": "The quantity of instrument to move in or out." }, "quantity_settled": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$", "description": "The quantity of instruments settled." }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "place_of_settlement": { "title": "Business Identifier Code", "type": "string", "description": "Business Identifier Code (also known as SWIFT-BIC, BIC, SWIFT ID or SWIFT code) [ISO 9362](https://en.wikipedia.org/wiki/ISO_9362).", "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$" }, "settlement_reference": { "type": "string", "pattern": "^[0-9A-Za-z+?/\\-:()\\.,' ]*$", "description": "Unique identifier of the securities transfer set by API consumers. Useful for API consumers to build special logic on top of it.\n*NOTE: For automatic incoming transfers where API users will subscribe to the corresponding webhook, the value is set by Upvest!*" }, "counterparty": { "title": "Counterparty", "description": "Counterparty for securities transfer. The `type` field determines which counterparty variant is present in the payload.", "oneOf": [ { "type": "object", "title": "Securities transfer counterparty - BIC", "description": "Counterparty with BIC (Bank Identifier Code) based identification for securities transfer.", "properties": { "type": { "default": "BIC", "type": "string", "description": "Type of the counterparty." }, "id": { "title": "Business Identifier Code", "type": "string", "description": "Business Identifier Code (also known as SWIFT-BIC, BIC, SWIFT ID or SWIFT code) [ISO 9362](https://en.wikipedia.org/wiki/ISO_9362).", "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$" }, "account_number": { "title": "Account Number", "description": "The account number is composed of valid Swift charset with a max length of 28 if provided. The account number helps other brokers identify the owner of the assets.", "type": "string", "pattern": "^[0-9A-Za-z+?/\\-:()\\.,' ]{0,28}$" }, "name": { "title": "Full name of the counterparty", "description": "The name is going to be split into 4 lines of 35 characters, the split is space based. This means that even if the name is exactly 140 of length, we may drop out the last parts if they don't fit into 4x35.", "type": "string", "pattern": "^[0-9A-Za-z+?/\\-:()\\.,' ]{0,140}$" } }, "required": [ "type", "id" ], "additionalProperties": false } ] }, "settlement_counterparties": { "title": "Settlement Counterparties", "description": "Settlement counterparties for the securities transfer.\nWhen `settlement_counterparties` is provided, `settlement_agent` is required. Other participants are optional but must respect the following dependency rules:\n* `settlement_custodian` presence requires `settlement_party` to be present.\n* `settlement_intermediary_1` presence requires `settlement_custodian` to be present.\n* `settlement_intermediary_2` presence requires `settlement_intermediary_1` to be present.\n\n Note: `settlement_custodian` can be provided without an explicit `settlement_party` since the default `counterparty` field at transfer level serves as the settlement party.", "type": "object", "properties": { "settlement_agent": { "title": "Settlement Counterparty", "description": "A participant in the settlement chain, identified by an identification and an optional account.", "type": "object", "properties": { "identification": { "title": "Settlement Counterparty Identification", "description": "Identification of a settlement counterparty.\n* `BIC` Party identified by BIC.\n* `PROPRIETARY` Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` Party identified by name and address.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of identification.\n* `BIC` - Party identified by BIC.\n* `PROPRIETARY` - Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` - Party identified by name and address.", "enum": [ "BIC", "PROPRIETARY", "NAME_AND_ADDRESS" ] }, "value": { "type": "string", "description": "Identification value. The format depends on the `type`:\n* For `BIC`: A valid BIC code.\n* For `PROPRIETARY`: A proprietary identifier under the given `scheme`.\n* For `NAME_AND_ADDRESS`: Name and address of the party." }, "scheme": { "type": "string", "pattern": "^[A-Z]{1,8}$", "description": "ISO Data Source Scheme code. **Required** when `type` is `PROPRIETARY`. Identifies the source of the proprietary identification (e.g. `CRST`, `DAKV`, `CEDE`)." } }, "required": [ "type", "value" ], "additionalProperties": false }, "account": { "title": "Settlement Counterparty Account", "description": "Account of a settlement counterparty.\n* `SAFE` - Safekeeping account.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of the account.\n* `SAFE` - Safekeeping account.", "enum": [ "SAFE" ] }, "value": { "type": "string", "description": "Account identifier value." } }, "required": [ "type", "value" ], "additionalProperties": false } }, "required": [ "identification" ], "additionalProperties": false }, "settlement_custodian": { "title": "Settlement Counterparty", "description": "A participant in the settlement chain, identified by an identification and an optional account.", "type": "object", "properties": { "identification": { "title": "Settlement Counterparty Identification", "description": "Identification of a settlement counterparty.\n* `BIC` Party identified by BIC.\n* `PROPRIETARY` Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` Party identified by name and address.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of identification.\n* `BIC` - Party identified by BIC.\n* `PROPRIETARY` - Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` - Party identified by name and address.", "enum": [ "BIC", "PROPRIETARY", "NAME_AND_ADDRESS" ] }, "value": { "type": "string", "description": "Identification value. The format depends on the `type`:\n* For `BIC`: A valid BIC code.\n* For `PROPRIETARY`: A proprietary identifier under the given `scheme`.\n* For `NAME_AND_ADDRESS`: Name and address of the party." }, "scheme": { "type": "string", "pattern": "^[A-Z]{1,8}$", "description": "ISO Data Source Scheme code. **Required** when `type` is `PROPRIETARY`. Identifies the source of the proprietary identification (e.g. `CRST`, `DAKV`, `CEDE`)." } }, "required": [ "type", "value" ], "additionalProperties": false }, "account": { "title": "Settlement Counterparty Account", "description": "Account of a settlement counterparty.\n* `SAFE` - Safekeeping account.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of the account.\n* `SAFE` - Safekeeping account.", "enum": [ "SAFE" ] }, "value": { "type": "string", "description": "Account identifier value." } }, "required": [ "type", "value" ], "additionalProperties": false } }, "required": [ "identification" ], "additionalProperties": false }, "settlement_intermediary_1": { "title": "Settlement Counterparty", "description": "A participant in the settlement chain, identified by an identification and an optional account.", "type": "object", "properties": { "identification": { "title": "Settlement Counterparty Identification", "description": "Identification of a settlement counterparty.\n* `BIC` Party identified by BIC.\n* `PROPRIETARY` Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` Party identified by name and address.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of identification.\n* `BIC` - Party identified by BIC.\n* `PROPRIETARY` - Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` - Party identified by name and address.", "enum": [ "BIC", "PROPRIETARY", "NAME_AND_ADDRESS" ] }, "value": { "type": "string", "description": "Identification value. The format depends on the `type`:\n* For `BIC`: A valid BIC code.\n* For `PROPRIETARY`: A proprietary identifier under the given `scheme`.\n* For `NAME_AND_ADDRESS`: Name and address of the party." }, "scheme": { "type": "string", "pattern": "^[A-Z]{1,8}$", "description": "ISO Data Source Scheme code. **Required** when `type` is `PROPRIETARY`. Identifies the source of the proprietary identification (e.g. `CRST`, `DAKV`, `CEDE`)." } }, "required": [ "type", "value" ], "additionalProperties": false }, "account": { "title": "Settlement Counterparty Account", "description": "Account of a settlement counterparty.\n* `SAFE` - Safekeeping account.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of the account.\n* `SAFE` - Safekeeping account.", "enum": [ "SAFE" ] }, "value": { "type": "string", "description": "Account identifier value." } }, "required": [ "type", "value" ], "additionalProperties": false } }, "required": [ "identification" ], "additionalProperties": false }, "settlement_intermediary_2": { "title": "Settlement Counterparty", "description": "A participant in the settlement chain, identified by an identification and an optional account.", "type": "object", "properties": { "identification": { "title": "Settlement Counterparty Identification", "description": "Identification of a settlement counterparty.\n* `BIC` Party identified by BIC.\n* `PROPRIETARY` Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` Party identified by name and address.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of identification.\n* `BIC` - Party identified by BIC.\n* `PROPRIETARY` - Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` - Party identified by name and address.", "enum": [ "BIC", "PROPRIETARY", "NAME_AND_ADDRESS" ] }, "value": { "type": "string", "description": "Identification value. The format depends on the `type`:\n* For `BIC`: A valid BIC code.\n* For `PROPRIETARY`: A proprietary identifier under the given `scheme`.\n* For `NAME_AND_ADDRESS`: Name and address of the party." }, "scheme": { "type": "string", "pattern": "^[A-Z]{1,8}$", "description": "ISO Data Source Scheme code. **Required** when `type` is `PROPRIETARY`. Identifies the source of the proprietary identification (e.g. `CRST`, `DAKV`, `CEDE`)." } }, "required": [ "type", "value" ], "additionalProperties": false }, "account": { "title": "Settlement Counterparty Account", "description": "Account of a settlement counterparty.\n* `SAFE` - Safekeeping account.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of the account.\n* `SAFE` - Safekeeping account.", "enum": [ "SAFE" ] }, "value": { "type": "string", "description": "Account identifier value." } }, "required": [ "type", "value" ], "additionalProperties": false } }, "required": [ "identification" ], "additionalProperties": false }, "settlement_party": { "title": "Settlement Counterparty", "description": "A participant in the settlement chain, identified by an identification and an optional account.", "type": "object", "properties": { "identification": { "title": "Settlement Counterparty Identification", "description": "Identification of a settlement counterparty.\n* `BIC` Party identified by BIC.\n* `PROPRIETARY` Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` Party identified by name and address.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of identification.\n* `BIC` - Party identified by BIC.\n* `PROPRIETARY` - Party identified by a proprietary code under a Data Source Scheme.\n* `NAME_AND_ADDRESS` - Party identified by name and address.", "enum": [ "BIC", "PROPRIETARY", "NAME_AND_ADDRESS" ] }, "value": { "type": "string", "description": "Identification value. The format depends on the `type`:\n* For `BIC`: A valid BIC code.\n* For `PROPRIETARY`: A proprietary identifier under the given `scheme`.\n* For `NAME_AND_ADDRESS`: Name and address of the party." }, "scheme": { "type": "string", "pattern": "^[A-Z]{1,8}$", "description": "ISO Data Source Scheme code. **Required** when `type` is `PROPRIETARY`. Identifies the source of the proprietary identification (e.g. `CRST`, `DAKV`, `CEDE`)." } }, "required": [ "type", "value" ], "additionalProperties": false }, "account": { "title": "Settlement Counterparty Account", "description": "Account of a settlement counterparty.\n* `SAFE` - Safekeeping account.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of the account.\n* `SAFE` - Safekeeping account.", "enum": [ "SAFE" ] }, "value": { "type": "string", "description": "Account identifier value." } }, "required": [ "type", "value" ], "additionalProperties": false } }, "required": [ "identification" ], "additionalProperties": false } }, "required": [ "settlement_agent" ], "additionalProperties": false }, "trade_date": { "type": "string", "format": "date", "description": "The forecast date when the trade takes place. Date in YYYY-MM-DD format." }, "settlement_date": { "type": "string", "format": "date", "description": "The forecast date when the settlement takes place. Date in YYYY-MM-DD format." }, "actual_settlement_date": { "type": "string", "format": "date", "description": "The date when the transfer settled, only known in `SETTLED` status. Date in YYYY-MM-DD format." }, "order_date": { "type": "string", "format": "date", "description": "Optional. Date the transfer request was received from the end user. The regulatory deadline runs from this date. Date in YYYY-MM-DD format." }, "delay_reason": { "title": "Delay reason code", "description": "Categorised reason why a securities transfer is delayed past the regulatory deadline.\n* `COUNTERPARTY_NOT_INSTRUCTING` - The counterparty has not yet instructed the transfer.\n* `COUNTERPARTY_NOT_RESPONDING` - The counterparty is not responding.\n* `COUNTERPARTY_DOES_NOT_AGREE_TO_DELIVERY_DETAILS` - The counterparty does not agree to the delivery details.\n* `COUNTERPARTY_NOT_ACCEPTING` - The counterparty is not accepting the transfer.", "type": "string", "enum": [ "COUNTERPARTY_NOT_INSTRUCTING", "COUNTERPARTY_NOT_RESPONDING", "COUNTERPARTY_DOES_NOT_AGREE_TO_DELIVERY_DETAILS", "COUNTERPARTY_NOT_ACCEPTING" ] } }, "required": [ "id", "created_at", "updated_at", "user_id", "account_id", "direction", "status", "transfer_type", "instrument_id", "instrument_id_type", "quantity", "counterparty", "settlement_reference", "trade_date", "settlement_date" ], "additionalProperties": false }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "examples": { "incoming_new": { "summary": "INCOMING - NEW", "value": { "id": "b5d0d9d0-bb8e-48b4-b2af-11df2b522353", "created_at": "2024-01-22T14:10:00.00Z", "type": "SECURITIES_TRANSFER.NEW", "object": { "id": "9637e68f-7065-4131-a072-6d57044ebd8c", "created_at": "2024-01-22T14:10:00.00Z", "updated_at": "2024-01-22T14:12:34.56Z", "direction": "INCOMING", "status": "NEW", "transfer_type": "NO_OWNER_CHANGE", "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "quantity": "10", "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e", "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4", "settlement_reference": "b82dc5985558fdr2", "counterparty": { "type": "BIC", "id": "DUMBZZ33XXX", "account_number": "1234567891", "name": "Max Mustermann" }, "settlement_counterparties": { "settlement_agent": { "identification": { "type": "BIC", "value": "FAKEZZ55XXX" }, "account": { "type": "SAFE", "value": "DAKV1234" } }, "settlement_party": { "identification": { "type": "BIC", "value": "DUMBZZ33XXX" }, "account": { "type": "SAFE", "value": "1234567891" } } }, "place_of_settlement": "DAKVDEFFXXX", "trade_date": "2024-01-22", "settlement_date": "2024-01-23", "order_date": "2024-01-20" }, "webhook_id": "cab4673a-1381-4404-aec4-982dae33a38c" } }, "incoming_settled": { "summary": "INCOMING - SETTLED", "value": { "id": "b5d0d9d0-bb8e-48b4-b2af-11df2b522353", "created_at": "2024-01-22T14:10:00.00Z", "type": "SECURITIES_TRANSFER.SETTLED", "object": { "id": "9637e68f-7065-4131-a072-6d57044ebd8c", "created_at": "2024-01-22T14:10:00.00Z", "updated_at": "2024-01-22T14:12:34.56Z", "direction": "INCOMING", "status": "SETTLED", "transfer_type": "NO_OWNER_CHANGE", "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "quantity": "10", "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e", "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4", "settlement_reference": "b82dc5985558fdr2", "counterparty": { "type": "BIC", "id": "DUMBZZ33XXX", "account_number": "1234567891", "name": "Max Mustermann" }, "settlement_counterparties": { "settlement_agent": { "identification": { "type": "BIC", "value": "FAKEZZ55XXX" }, "account": { "type": "SAFE", "value": "DAKV1234" } }, "settlement_party": { "identification": { "type": "BIC", "value": "DUMBZZ33XXX" }, "account": { "type": "SAFE", "value": "1234567891" } } }, "place_of_settlement": "DAKVDEFFXXX", "trade_date": "2024-01-22", "settlement_date": "2024-01-23", "actual_settlement_date": "2024-01-24", "order_date": "2023-12-20", "delay_reason": "COUNTERPARTY_NOT_RESPONDING" }, "webhook_id": "cab4673a-1381-4404-aec4-982dae33a38c" } }, "outgoing_new": { "summary": "OUTGOING - NEW", "value": { "id": "b5d0d9d0-bb8e-48b4-b2af-11df2b522353", "created_at": "2024-01-22T14:10:00.00Z", "type": "SECURITIES_TRANSFER.NEW", "object": { "id": "9637e68f-7065-4131-a072-6d57044ebd8c", "created_at": "2024-01-22T14:10:00.00Z", "updated_at": "2024-01-22T14:12:34.56Z", "direction": "OUTGOING", "status": "NEW", "transfer_type": "NO_OWNER_CHANGE", "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "quantity": "10", "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e", "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4", "settlement_reference": "b82dc5985558fdr2", "counterparty": { "type": "BIC", "id": "DUMBZZ33XXX", "account_number": "1234567891", "name": "Max Mustermann" }, "settlement_counterparties": { "settlement_agent": { "identification": { "type": "BIC", "value": "FAKEZZ55XXX" }, "account": { "type": "SAFE", "value": "DAKV1234" } }, "settlement_party": { "identification": { "type": "BIC", "value": "DUMBZZ33XXX" }, "account": { "type": "SAFE", "value": "1234567891" } } }, "place_of_settlement": "CEDELULLXXX", "trade_date": "2024-01-22", "settlement_date": "2024-01-23", "order_date": "2024-01-20" }, "webhook_id": "cab4673a-1381-4404-aec4-982dae33a38c" } }, "outgoing_settled": { "summary": "OUTGOING - SETTLED", "value": { "id": "b5d0d9d0-bb8e-48b4-b2af-11df2b522353", "created_at": "2024-01-22T14:10:00.00Z", "type": "SECURITIES_TRANSFER.SETTLED", "object": { "id": "9637e68f-7065-4131-a072-6d57044ebd8c", "created_at": "2024-01-22T14:10:00.00Z", "updated_at": "2024-01-22T14:12:34.56Z", "direction": "OUTGOING", "status": "SETTLED", "transfer_type": "NO_OWNER_CHANGE", "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "quantity": "10", "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e", "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4", "settlement_reference": "b82dc5985558fdr2", "counterparty": { "type": "BIC", "id": "DUMBZZ33XXX", "account_number": "1234567891", "name": "Max Mustermann" }, "settlement_counterparties": { "settlement_agent": { "identification": { "type": "BIC", "value": "FAKEZZ55XXX" }, "account": { "type": "SAFE", "value": "DAKV1234" } }, "settlement_party": { "identification": { "type": "BIC", "value": "DUMBZZ33XXX" }, "account": { "type": "SAFE", "value": "1234567891" } } }, "place_of_settlement": "CEDELULLXXX", "trade_date": "2024-01-22", "settlement_date": "2024-01-23", "actual_settlement_date": "2024-01-24", "order_date": "2023-12-20", "delay_reason": "COUNTERPARTY_NOT_RESPONDING" }, "webhook_id": "cab4673a-1381-4404-aec4-982dae33a38c" } } } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Account Transfers events": { "post": { "operationId": "account_transfer_event", "summary": "Account Transfer events", "description": "Account Transfer events", "tags": [ "Account Transfers" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Account Transfer - Callback", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type", "enum": [ "ACCOUNT_TRANSFER.NEW", "ACCOUNT_TRANSFER.PROCESSING", "ACCOUNT_TRANSFER.SETTLED", "ACCOUNT_TRANSFER.PARTIALLY_SETTLED", "ACCOUNT_TRANSFER.CANCELLED" ] }, "object": { "type": "object", "properties": { "id": { "title": "Account transfer request unique identifier.", "type": "string", "description": "Account transfer request unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "direction": { "type": "string", "description": "Direction of the account transfer\n* INCOMING - account transfer is incoming to the user.\n* OUTGOING - account transfer is outgoing from the user.", "enum": [ "INCOMING", "OUTGOING" ] }, "status": { "type": "string", "description": "Status of the account transfer\n* NEW - account transfer is created but not started processing.\n* PROCESSING - account transfer is in processing.\n* SETTLED - account transfer was successfully settled.\n* PARTIALLY_SETTLED - account transfer was partially settled, while some instrument got cancelled.\n* CANCELLED - account transfer was cancelled.", "enum": [ "NEW", "PROCESSING", "SETTLED", "PARTIALLY_SETTLED", "CANCELLED" ] }, "transfer_type": { "type": "string", "description": "Type of the account transfer\n* NO_OWNER_CHANGE - No change of ownership.", "enum": [ "NO_OWNER_CHANGE" ] }, "instruments": { "title": "Instruments", "type": "array", "description": "List of instruments positions.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "`ISIN` or other identity (depends on instrument_id_type) of the security to be transferred." }, "id_type": { "type": "string", "description": "Type of the instrument_id\n* `ISIN` - International Securities Identification Number", "enum": [ "ISIN" ] }, "quantity": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$", "description": "The quantity of instrument to move in or out." }, "quantity_settled": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$", "description": "The quantity of instruments settled." }, "status": { "type": "string", "description": "Status of the securities transfer\n* `NEW` - Securities transfer is created but not started processing.\n* `PROCESSING` - Securities transfer is in processing.\n* `SETTLED` - Securities transfer was successfully settled.\n* `CANCELLED` - Securities transfer was cancelled.", "enum": [ "NEW", "PROCESSING", "SETTLED", "CANCELLED" ] }, "transfer_id": { "type": "string", "description": "Securities transfer request unique identifier.", "format": "uuid" } }, "required": [ "id", "id_type", "quantity", "status", "transfer_id" ] } }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "settlement_reference": { "type": "string", "pattern": "^[0-9A-Za-z+?/\\-:()\\.,' ]*$", "description": "Unique identifier of the account transfer set by API consumers. Useful for API consumers to build special logic on top of it.\n*NOTE: This reference will be set and be common to all securities transfers.*" }, "counterparty": { "title": "Counterparty", "description": "Counterparty for account transfer. The `type` field determines which counterparty variant is present in the payload.", "oneOf": [ { "type": "object", "title": "Account transfer counterparty - BIC", "description": "Counterparty with BIC (Bank Identifier Code) based identification for account transfer.", "properties": { "type": { "default": "BIC", "type": "string", "description": "Type of the counterparty." }, "id": { "title": "Business Identifier Code", "type": "string", "description": "Business Identifier Code (also known as SWIFT-BIC, BIC, SWIFT ID or SWIFT code) [ISO 9362](https://en.wikipedia.org/wiki/ISO_9362).", "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$" }, "account_number": { "title": "Account Number", "description": "The account number is composed of valid Swift charset with a max length of 28 if provided. The account number helps other brokers identify the owner of the assets.", "type": "string", "pattern": "^[0-9A-Za-z+?/\\-:()\\.,' ]{0,28}$" }, "name": { "title": "Full name of the counterparty", "description": "The name is going to be split into 4 lines of 35 characters, the split is space based. This means that even if the name is exactly 140 of length, we may drop out the last parts if they don't fit into 4x35.", "type": "string", "pattern": "^[0-9A-Za-z+?/\\-:()\\.,' ]{0,140}$" } }, "required": [ "type", "id" ], "additionalProperties": false } ] }, "trade_date": { "type": "string", "format": "date", "description": "The forecast date when the trade takes place. Date in YYYY-MM-DD format. \n*NOTE: This date mirrors the preliminary date if given in request as input, each single transfer can have their own date according to market needs.*" }, "settlement_date": { "type": "string", "format": "date", "description": "The forecast date when the settlement takes place. Date in YYYY-MM-DD format. \n*NOTE: This date mirrors the preliminary date if given in request as input, each single transfer can have their own date according to market needs.*" }, "order_date": { "type": "string", "format": "date", "description": "Date the transfer request was received from the end user. The regulatory deadline runs from this date. Date in YYYY-MM-DD format." }, "delay_reason": { "title": "Delay reason code", "description": "Categorised reason why a securities transfer is delayed past the regulatory deadline.\n* `COUNTERPARTY_NOT_INSTRUCTING` - The counterparty has not yet instructed the transfer.\n* `COUNTERPARTY_NOT_RESPONDING` - The counterparty is not responding.\n* `COUNTERPARTY_DOES_NOT_AGREE_TO_DELIVERY_DETAILS` - The counterparty does not agree to the delivery details.\n* `COUNTERPARTY_NOT_ACCEPTING` - The counterparty is not accepting the transfer.", "type": "string", "enum": [ "COUNTERPARTY_NOT_INSTRUCTING", "COUNTERPARTY_NOT_RESPONDING", "COUNTERPARTY_DOES_NOT_AGREE_TO_DELIVERY_DETAILS", "COUNTERPARTY_NOT_ACCEPTING" ] } }, "required": [ "id", "created_at", "updated_at", "direction", "status", "transfer_type", "instruments", "user_id", "account_id", "settlement_reference", "counterparty" ], "additionalProperties": false }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "examples": { "incoming_new": { "summary": "INCOMING - NEW", "value": { "id": "b5d0d9d0-bb8e-48b4-b2af-11df2b522353", "created_at": "2024-01-22T14:10:00.00Z", "type": "ACCOUNT_TRANSFER.NEW", "object": { "id": "63da4452-2dd3-4414-a7ca-66c0e3e89645", "created_at": "2025-01-22T14:10:00.00Z", "updated_at": "2025-01-22T14:12:34.56Z", "direction": "INCOMING", "status": "NEW", "transfer_type": "NO_OWNER_CHANGE", "instruments": [ { "id": "US0378331005", "id_type": "ISIN", "quantity": "10", "status": "NEW", "transfer_id": "9637e68f-7065-4131-a072-6d57044ebd8c" }, { "id": "US64110L1061", "id_type": "ISIN", "quantity": "5", "status": "NEW", "transfer_id": "c2f84524-3f05-4849-909c-2998803327d3" } ], "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e", "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4", "settlement_reference": "b82dc5985558fdr2", "counterparty": { "type": "BIC", "id": "ABCDDEFFXXX", "account_number": "1234567891", "name": "Max Mustermann" }, "order_date": "2025-01-21" }, "webhook_id": "cab4673a-1381-4404-aec4-982dae33a38c" } }, "incoming_processing": { "summary": "INCOMING - PROCESSING", "value": { "id": "b5d0d9d0-bb8e-48b4-b2af-11df2b522353", "created_at": "2024-01-22T14:10:00.00Z", "type": "ACCOUNT_TRANSFER.NEW", "object": { "id": "63da4452-2dd3-4414-a7ca-66c0e3e89645", "created_at": "2025-01-22T14:10:00.00Z", "updated_at": "2025-01-22T14:12:34.56Z", "direction": "INCOMING", "status": "PROCESSING", "transfer_type": "NO_OWNER_CHANGE", "instruments": [ { "id": "US0378331005", "id_type": "ISIN", "quantity": "10", "status": "NEW", "transfer_id": "9637e68f-7065-4131-a072-6d57044ebd8c" }, { "id": "US64110L1061", "id_type": "ISIN", "quantity": "5", "status": "PROCESSING", "transfer_id": "c2f84524-3f05-4849-909c-2998803327d3" } ], "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e", "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4", "settlement_reference": "b82dc5985558fdr2", "counterparty": { "type": "BIC", "id": "ABCDDEFFXXX", "account_number": "1234567891", "name": "Max Mustermann" }, "order_date": "2025-01-21" }, "webhook_id": "cab4673a-1381-4404-aec4-982dae33a38c" } }, "incoming_settled": { "summary": "INCOMING - SETTLED", "value": { "id": "b5d0d9d0-bb8e-48b4-b2af-11df2b522353", "created_at": "2024-01-22T14:10:00.00Z", "type": "ACCOUNT_TRANSFER.NEW", "object": { "id": "63da4452-2dd3-4414-a7ca-66c0e3e89645", "created_at": "2025-01-22T14:10:00.00Z", "updated_at": "2025-01-22T14:12:34.56Z", "direction": "INCOMING", "status": "SETTLED", "transfer_type": "NO_OWNER_CHANGE", "instruments": [ { "id": "US0378331005", "id_type": "ISIN", "quantity": "10", "status": "SETTLED", "transfer_id": "9637e68f-7065-4131-a072-6d57044ebd8c" }, { "id": "US64110L1061", "id_type": "ISIN", "quantity": "5", "status": "SETTLED", "transfer_id": "c2f84524-3f05-4849-909c-2998803327d3" } ], "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e", "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4", "settlement_reference": "b82dc5985558fdr2", "counterparty": { "type": "BIC", "id": "ABCDDEFFXXX", "account_number": "1234567891", "name": "Max Mustermann" }, "order_date": "2025-01-21", "delay_reason": "COUNTERPARTY_NOT_RESPONDING" }, "webhook_id": "cab4673a-1381-4404-aec4-982dae33a38c" } }, "incoming_partially_settled": { "summary": "INCOMING - PARTIALLY_SETTLED", "value": { "id": "b5d0d9d0-bb8e-48b4-b2af-11df2b522353", "created_at": "2024-01-22T14:10:00.00Z", "type": "ACCOUNT_TRANSFER.NEW", "object": { "id": "63da4452-2dd3-4414-a7ca-66c0e3e89645", "created_at": "2025-01-22T14:10:00.00Z", "updated_at": "2025-01-22T14:12:34.56Z", "direction": "INCOMING", "status": "PARTIALLY_SETTLED", "transfer_type": "NO_OWNER_CHANGE", "instruments": [ { "id": "US0378331005", "id_type": "ISIN", "quantity": "10", "status": "SETTLED", "transfer_id": "9637e68f-7065-4131-a072-6d57044ebd8c" }, { "id": "US64110L1061", "id_type": "ISIN", "quantity": "5", "status": "CANCELLED", "transfer_id": "c2f84524-3f05-4849-909c-2998803327d3" } ], "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e", "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4", "settlement_reference": "b82dc5985558fdr2", "counterparty": { "type": "BIC", "id": "ABCDDEFFXXX", "account_number": "1234567891", "name": "Max Mustermann" }, "order_date": "2025-01-21", "delay_reason": "COUNTERPARTY_NOT_RESPONDING" }, "webhook_id": "cab4673a-1381-4404-aec4-982dae33a38c" } }, "incoming_cancelled": { "summary": "INCOMING - CANCELLED", "value": { "id": "b5d0d9d0-bb8e-48b4-b2af-11df2b522353", "created_at": "2024-01-22T14:10:00.00Z", "type": "ACCOUNT_TRANSFER.NEW", "object": { "id": "63da4452-2dd3-4414-a7ca-66c0e3e89645", "created_at": "2025-01-22T14:10:00.00Z", "updated_at": "2025-01-22T14:12:34.56Z", "direction": "INCOMING", "status": "CANCELLED", "transfer_type": "NO_OWNER_CHANGE", "instruments": [ { "id": "US0378331005", "id_type": "ISIN", "quantity": "10", "status": "CANCELLED", "transfer_id": "9637e68f-7065-4131-a072-6d57044ebd8c" }, { "id": "US64110L1061", "id_type": "ISIN", "quantity": "5", "status": "CANCELLED", "transfer_id": "c2f84524-3f05-4849-909c-2998803327d3" } ], "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e", "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4", "settlement_reference": "b82dc5985558fdr2", "counterparty": { "type": "BIC", "id": "ABCDDEFFXXX", "account_number": "1234567891", "name": "Max Mustermann" }, "order_date": "2025-01-21" }, "webhook_id": "cab4673a-1381-4404-aec4-982dae33a38c" } }, "outgoing_new": { "summary": "OUTGOING - NEW", "value": { "id": "b5d0d9d0-bb8e-48b4-b2af-11df2b522353", "created_at": "2024-01-22T14:10:00.00Z", "type": "ACCOUNT_TRANSFER.NEW", "object": { "id": "63da4452-2dd3-4414-a7ca-66c0e3e89645", "created_at": "2025-01-22T14:10:00.00Z", "updated_at": "2025-01-22T14:12:34.56Z", "direction": "OUTGOING", "status": "NEW", "transfer_type": "NO_OWNER_CHANGE", "instruments": [ { "id": "US0378331005", "id_type": "ISIN", "quantity": "10", "status": "NEW", "transfer_id": "9637e68f-7065-4131-a072-6d57044ebd8c" }, { "id": "US64110L1061", "id_type": "ISIN", "quantity": "5", "status": "NEW", "transfer_id": "c2f84524-3f05-4849-909c-2998803327d3" } ], "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e", "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4", "settlement_reference": "b82dc5985558fdr2", "counterparty": { "type": "BIC", "id": "ABCDDEFFXXX", "account_number": "1234567891", "name": "Max Mustermann" }, "order_date": "2025-01-21" }, "webhook_id": "cab4673a-1381-4404-aec4-982dae33a38c" } }, "outgoing_processing": { "summary": "OUTGOING - PROCESSING", "value": { "id": "b5d0d9d0-bb8e-48b4-b2af-11df2b522353", "created_at": "2024-01-22T14:10:00.00Z", "type": "ACCOUNT_TRANSFER.NEW", "object": { "id": "63da4452-2dd3-4414-a7ca-66c0e3e89645", "created_at": "2025-01-22T14:10:00.00Z", "updated_at": "2025-01-22T14:12:34.56Z", "direction": "OUTGOING", "status": "PROCESSING", "transfer_type": "NO_OWNER_CHANGE", "instruments": [ { "id": "US0378331005", "id_type": "ISIN", "quantity": "10", "status": "NEW", "transfer_id": "9637e68f-7065-4131-a072-6d57044ebd8c" }, { "id": "US64110L1061", "id_type": "ISIN", "quantity": "5", "status": "PROCESSING", "transfer_id": "c2f84524-3f05-4849-909c-2998803327d3" } ], "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e", "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4", "settlement_reference": "b82dc5985558fdr2", "counterparty": { "type": "BIC", "id": "ABCDDEFFXXX", "account_number": "1234567891", "name": "Max Mustermann" }, "order_date": "2025-01-21" }, "webhook_id": "cab4673a-1381-4404-aec4-982dae33a38c" } }, "outgoing_settled": { "summary": "OUTGOING - SETTLED", "value": { "id": "b5d0d9d0-bb8e-48b4-b2af-11df2b522353", "created_at": "2024-01-22T14:10:00.00Z", "type": "ACCOUNT_TRANSFER.NEW", "object": { "id": "63da4452-2dd3-4414-a7ca-66c0e3e89645", "created_at": "2025-01-22T14:10:00.00Z", "updated_at": "2025-01-22T14:12:34.56Z", "direction": "OUTGOING", "status": "SETTLED", "transfer_type": "NO_OWNER_CHANGE", "instruments": [ { "id": "US0378331005", "id_type": "ISIN", "quantity": "10", "status": "SETTLED", "transfer_id": "9637e68f-7065-4131-a072-6d57044ebd8c" }, { "id": "US64110L1061", "id_type": "ISIN", "quantity": "5", "status": "SETTLED", "transfer_id": "c2f84524-3f05-4849-909c-2998803327d3" } ], "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e", "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4", "settlement_reference": "b82dc5985558fdr2", "counterparty": { "type": "BIC", "id": "ABCDDEFFXXX", "account_number": "1234567891", "name": "Max Mustermann" }, "order_date": "2025-01-21", "delay_reason": "COUNTERPARTY_NOT_RESPONDING" }, "webhook_id": "cab4673a-1381-4404-aec4-982dae33a38c" } }, "outgoing_partially_settled": { "summary": "OUTGOING - PARTIALLY_SETTLED", "value": { "id": "b5d0d9d0-bb8e-48b4-b2af-11df2b522353", "created_at": "2024-01-22T14:10:00.00Z", "type": "ACCOUNT_TRANSFER.NEW", "object": { "id": "63da4452-2dd3-4414-a7ca-66c0e3e89645", "created_at": "2025-01-22T14:10:00.00Z", "updated_at": "2025-01-22T14:12:34.56Z", "direction": "OUTGOING", "status": "PARTIALLY_SETTLED", "transfer_type": "NO_OWNER_CHANGE", "instruments": [ { "id": "US0378331005", "id_type": "ISIN", "quantity": "10", "status": "SETTLED", "transfer_id": "9637e68f-7065-4131-a072-6d57044ebd8c" }, { "id": "US64110L1061", "id_type": "ISIN", "quantity": "5", "status": "CANCELLED", "transfer_id": "c2f84524-3f05-4849-909c-2998803327d3" } ], "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e", "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4", "settlement_reference": "b82dc5985558fdr2", "counterparty": { "type": "BIC", "id": "ABCDDEFFXXX", "account_number": "1234567891", "name": "Max Mustermann" }, "order_date": "2025-01-21", "delay_reason": "COUNTERPARTY_NOT_RESPONDING" }, "webhook_id": "cab4673a-1381-4404-aec4-982dae33a38c" } }, "outgoing_cancelled": { "summary": "OUTGOING - CANCELLED", "value": { "id": "b5d0d9d0-bb8e-48b4-b2af-11df2b522353", "created_at": "2024-01-22T14:10:00.00Z", "type": "ACCOUNT_TRANSFER.NEW", "object": { "id": "63da4452-2dd3-4414-a7ca-66c0e3e89645", "created_at": "2025-01-22T14:10:00.00Z", "updated_at": "2025-01-22T14:12:34.56Z", "direction": "OUTGOING", "status": "CANCELLED", "transfer_type": "NO_OWNER_CHANGE", "instruments": [ { "id": "US0378331005", "id_type": "ISIN", "quantity": "10", "status": "CANCELLED", "transfer_id": "9637e68f-7065-4131-a072-6d57044ebd8c" }, { "id": "US64110L1061", "id_type": "ISIN", "quantity": "5", "status": "CANCELLED", "transfer_id": "c2f84524-3f05-4849-909c-2998803327d3" } ], "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e", "account_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4", "settlement_reference": "b82dc5985558fdr2", "counterparty": { "type": "BIC", "id": "ABCDDEFFXXX", "account_number": "1234567891", "name": "Max Mustermann" }, "order_date": "2025-01-21" }, "webhook_id": "cab4673a-1381-4404-aec4-982dae33a38c" } } } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "ISA Transfers events": { "post": { "operationId": "isa_transfer_event", "summary": "ISA Transfers events", "description": "ISA Transfers events", "tags": [ "ISA Transfers" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Incoming Securities Transfers - Callback", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type", "enum": [ "ISA_TRANSFER.NEW", "ISA_TRANSFER.DISCOVERY", "ISA_TRANSFER.DISCOVERY_CONFIRMED", "ISA_TRANSFER.INSTRUCTED", "ISA_TRANSFER.PROCESSING", "ISA_TRANSFER.SETTLED" ] }, "object": { "type": "object", "properties": { "id": { "title": "ISA transfer request unique identifier.", "type": "string", "description": "ISA transfer request unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "direction": { "type": "string", "description": "Direction of the ISA transfer\n* INCOMING - Transfer is incoming to the user.\n* OUTGOING - Transfer is outgoing from the user.", "enum": [ "INCOMING", "OUTGOING" ] }, "status": { "type": "string", "description": "Status of the transfer\n* NEW - Transfer is created.\n* DISCOVERY - Discovery with the ceding provider where information about the transfer is being exchanged and reviewed. Only relevant if type ISA_EXTERNAL.\n* DISCOVERY_CONFIRMED - Discovery is completed and transfer request is accepted by the ceding provider. Only relevant if type ISA_EXTERNAL.\n* INSTRUCTED - Transfer is instructed to the ceding provider.\n* PROCESSING - Transfer instruction is confirmed by the ceding provider. Transfer is being processed. \n* SETTLED - Transfer is completed.", "enum": [ "NEW", "DISCOVERY", "DISCOVERY_CONFIRMED", "INSTRUCTED", "PROCESSING", "SETTLED" ] }, "transfer_type": { "type": "string", "description": "Type of the securities transfer\n* ISA_INTERNAL - Transfer occurs within the same ISA manager.\n* ISA_EXTERNAL - Transfer occurs across different ISA managers, via Equisoft or others.", "enum": [ "ISA_INTERNAL", "ISA_EXTERNAL" ] }, "transfer_value": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* GBP - Great British Pound", "enum": [ "GBP" ], "default": "GBP" }, "transfer_method": { "type": "string", "description": "Method of the ISA transfer\n* CASH - Cash transfer.\n\nOther methods can be supported in the future, e.g. IN_SPECIE", "enum": [ "CASH" ] }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "reference": { "type": "string", "pattern": "^[0-9A-Za-z+?/\\-:()\\.,' ]*$", "description": "Random string reference on which API clients can build logic." }, "counterparty": { "type": "object", "properties": { "account_number": { "title": "Account Number", "description": "The account number is composed of valid Swift charset with a max length of 28 if provided. The account number helps other brokers identify the owner of the assets.", "type": "string", "pattern": "^[0-9A-Za-z+?/\\-:()\\.,' ]{0,28}$" } }, "required": [ "account_number" ], "additionalProperties": false }, "transfer_date": { "type": "string", "format": "date-time", "description": "The date when end user initiated the transfer. Relevant for tax year's end reporting. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "details": { "type": "object", "properties": { "current_year_subscription": { "type": "object", "description": "Details related to the current year’s subscription being transferred.\n\nRequired if transfer_type is ISA_INTERNAL.", "properties": { "transfer_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "first_subscription_at": { "type": "string", "format": "date-time", "description": "The date of the first subscription made to the ISA in the current tax year. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)\n\n Required if transfer_type is ISA_INTERNAL." } }, "required": [ "transfer_amount" ], "additionalProperties": false } }, "required": [ "current_year_subscription" ], "additionalProperties": false } }, "required": [ "id", "created_at", "updated_at", "user_id", "account_group_id", "direction", "status", "transfer_type", "currency", "transfer_method", "reference", "transfer_date" ], "additionalProperties": false }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "example": { "id": "b5d0d9d0-bb8e-48b4-b2af-11df2b522353", "created_at": "2024-01-22T14:10:00.00Z", "type": "ISA_TRANSFER.NEW", "object": { "id": "9637e68f-7065-4131-a072-6d57044ebd8c", "created_at": "2024-01-22T14:10:00.00Z", "updated_at": "2024-01-22T14:12:34.56Z", "direction": "INCOMING", "status": "NEW", "transfer_type": "ISA_INTERNAL", "user_id": "7e9a0529-d289-4f4a-ae01-c2cd013d582e", "account_group_id": "d396b7c3-aa67-488a-8e39-4a1a7cbeb9f4", "reference": "b82dc5985558fdr2", "transfer_value": "10000.00", "currency": "GBP", "transfer_method": "CASH", "counterparty": { "account_number": "1234567891" }, "details": { "current_year_subscription": { "transfer_amount": "2000.00", "first_subscription_at": "2024-01-15T10:00:00.00Z" } }, "transfer_date": "2024-01-22T14:10:00.00Z" }, "webhook_id": "cab4673a-1381-4404-aec4-982dae33a38c" } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Credit Funding events": { "post": { "operationId": "credit_funding_event", "summary": "Credit Funding events", "description": "Webhook callback payload for credit funding events. Delivered when an incoming SEPA Credit Transfer transitions to `CREDIT_FUNDING.CONFIRMED` or `CREDIT_FUNDING.CANCELLED`.", "tags": [ "Credit Fundings" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Credit Funding - Callback", "type": "object", "description": "Webhook callback payload for credit funding events (`CREDIT_FUNDING.CONFIRMED`, `CREDIT_FUNDING.CANCELLED`).", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type", "enum": [ "CREDIT_FUNDING.CONFIRMED", "CREDIT_FUNDING.CANCELLED" ], "default": "CREDIT_FUNDING.CONFIRMED" }, "object": { "type": "object", "description": "Represents an incoming SEPA Credit Transfer received by Upvest and credited to an account group. Contains counterparty identification and remittance details from the sender's bank.", "properties": { "id": { "title": "Credit Funding request unique identifier", "type": "string", "description": "Credit Funding request unique identifier", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "status": { "type": "string", "description": "Status of the credit funding\n* CONFIRMED - Credit Funding was confirmed.\n* CANCELLED - Credit Funding was cancelled.", "enum": [ "CONFIRMED", "CANCELLED" ] }, "remittance_information": { "type": "string", "description": "Payment reference the one that was used by the end user for the corresponding SEPA Credit Transfer" }, "counterparty": { "type": "object", "properties": { "identification": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the counterparty" } }, "required": [ "name" ] }, "account": { "type": "object", "properties": { "identification": { "type": "object", "properties": { "iban": { "title": "International Bank Account Number (IBAN)", "type": "string", "description": "International Bank Account Number [IBAN](https://en.wikipedia.org/wiki/International_Bank_Account_Number).", "pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,26}$" } }, "required": [ "iban" ] } }, "required": [ "identification" ] } }, "required": [ "identification", "account" ] }, "virtual_bank_account_id": { "title": "Virtual bank account request unique identifier.", "type": "string", "description": "Virtual bank account request unique identifier.", "format": "uuid" }, "purpose_code": { "type": "string", "maxLength": 4, "description": "Purpose of the payment based on *ExternalPurpose1Code* from [ISO 20022](https://www.iso20022.org/catalogue-messages/additional-content-messages/external-code-sets)." } }, "required": [ "id", "created_at", "account_group_id", "cash_amount", "currency", "remittance_information", "counterparty" ], "additionalProperties": false }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "example": { "id": "8962b496-8d42-4560-bfab-10490dd1a721", "created_at": "2021-07-21T14:10:00.00Z", "type": "CREDIT_FUNDING.CONFIRMED", "object": { "id": "1ab4fef9-a097-4c6f-9345-647025d5fde6", "created_at": "2020-08-24T14:15:22Z", "account_group_id": "1ea60f56-b67b-61fc-829a-0242ac130003", "cash_amount": "200.00", "currency": "EUR", "status": "CONFIRMED", "remittance_information": "CF123456789", "counterparty": { "identification": { "name": "Max Musterman" }, "account": { "identification": { "iban": "DE02100500000054540402" } } }, "virtual_bank_account_id": "ab8f9b19-6a31-48d3-b201-4dee92f3da0d", "purpose_code": "OTHR" }, "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6" } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Withdrawals events": { "post": { "operationId": "withdrawal_event", "summary": "Withdrawals events", "description": "Webhook callback payload for cash withdrawal lifecycle events. Delivered when a withdrawal transitions to `WITHDRAWAL.NEW`, `WITHDRAWAL.PROCESSING`, `WITHDRAWAL.CONFIRMED`, or `WITHDRAWAL.CANCELLED`.", "tags": [ "Withdrawals" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Withdrawals - Callback", "type": "object", "description": "Webhook callback payload for cash withdrawal lifecycle events (`WITHDRAWAL.NEW`, `WITHDRAWAL.PROCESSING`, `WITHDRAWAL.CONFIRMED`, `WITHDRAWAL.CANCELLED`).", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type", "enum": [ "WITHDRAWAL.NEW", "WITHDRAWAL.PROCESSING", "WITHDRAWAL.CONFIRMED", "WITHDRAWAL.CANCELLED" ] }, "object": { "title": "Payments - Withdrawal", "type": "object", "description": "Represents a cash withdrawal from an account group to a registered reference bank account. Withdrawals transition through `NEW` → `PROCESSING` → `CONFIRMED` or `CANCELLED` as they are processed.", "additionalProperties": false, "properties": { "id": { "title": "Cash withdrawal unique identifier", "type": "string", "description": "Cash withdrawal unique identifier", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "reference_account_id": { "title": "Reference account unique identifier.", "type": "string", "description": "Reference account unique identifier.", "format": "uuid" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "user_id": { "allOf": [ { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" } ], "description": "The ID of the user. For business-initiated withdrawals, this field will be absent.", "deprecated": true }, "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "remittance_information": { "type": "string", "maxLength": 140, "pattern": "^[0-9A-Za-z+?/\\-:()\\.,';_ ]{0,140}$", "description": "Payment reference the end user will see in their bank statement for the corresponding credit transfer booking (“Verwendungszweck”). We recommend that you keep this info concise and avoid special characters or non-standardised formatting. See the ([Cash balance withdrawal guide](/documentation/guides/payments/cash_balances/cash_withdrawal))." }, "taxes": { "type": "array", "items": { "title": "Tax", "type": "object", "description": "Tax deducted as part of a payment (e.g. a withdrawal). Contains the tax type and the deducted amount in the specified currency.", "properties": { "amount": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "type": { "type": "string", "description": "Type of the tax.\n* TOTAL - Total taxes", "enum": [ "TOTAL" ], "default": "TOTAL" } }, "required": [ "type", "amount", "currency" ] } }, "status": { "type": "string", "description": "Status of the withdrawal\n* NEW - Withdrawal is created but not started processing.\n* PROCESSING - Withdrawal is in processing.\n* CONFIRMED - Withdrawal was successfully sent to the bank for processing.\n* CANCELLED - Withdrawal was cancelled. **Note**: In rare instances, a bank may reject a withdrawal after it has been confirmed. \nFor more information, see the [Potential cancellation after confirmation](/documentation/guides/payments/cash_balances/cash_withdrawal#potential-cancellation-after-confirmation) section of the guide.", "enum": [ "NEW", "PROCESSING", "CONFIRMED", "CANCELLED" ] }, "cancellation_reason": { "title": "Cancellation reason code for withdrawal", "description": "Reason the withdrawal was cancelled. The field is present in case the withdrawal has a status of CANCELLED.\n* CANCELLED_BY_BANK - The payment was not completed by your bank. Please check your account details or contact support.\n* CANCELLED_BY_UPVEST - The payment was cancelled. Contact support for details.\n* CANCELLED_BY_CLIENT - The payment was cancelled at your request.\n* OTHER - Reason not available (applies to historical data only).", "type": "string", "enum": [ "CANCELLED_BY_BANK", "CANCELLED_BY_UPVEST", "CANCELLED_BY_CLIENT", "OTHER" ] }, "purpose_code": { "type": "string", "maxLength": 4, "description": "Purpose of the payment based on *ExternalPurpose1Code* from [ISO 20022](https://www.iso20022.org/catalogue-messages/additional-content-messages/external-code-sets)." } }, "required": [ "id", "reference_account_id", "account_group_id", "amount", "currency", "created_at", "updated_at", "remittance_information" ] }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "example": { "id": "8962b496-8d42-4560-bfab-10490dd1a721", "created_at": "2021-07-21T14:10:00.00Z", "type": "WITHDRAWAL.NEW", "object": { "id": "6ffa6b16-2380-4e7a-88b2-ae625c8eef99", "created_at": "2020-08-24T14:15:22Z", "updated_at": "2020-08-24T14:15:22Z", "reference_account_id": "295378ec-036e-4f3f-ae5c-2be85c93e837", "account_group_id": "ac1c39e9-2101-46b8-a624-d10a9e351b6c", "user_id": "b668282b-cdf3-439a-bda2-3f3c9f655bb7", "amount": "200.00", "currency": "EUR", "remittance_information": "Withdrawal", "taxes": [ { "type": "TOTAL", "amount": "38.00", "currency": "EUR" } ], "status": "NEW" }, "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6" } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Cash Balance Transfers events": { "post": { "operationId": "cash_balance_transfer_event", "summary": "Cash Balance Transfers events", "description": "Webhook callback payload for cash balance transfer lifecycle events. Delivered when a transfer transitions to `CASH_BALANCE_TRANSFER.ISSUED`, `CASH_BALANCE_TRANSFER.CONFIRMED`, or `CASH_BALANCE_TRANSFER.CANCELLED`.", "tags": [ "Cash Balance Transfers" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Cash Balance Transfer - Callback", "type": "object", "description": "Webhook callback payload for cash balance transfer lifecycle events (`CASH_BALANCE_TRANSFER.ISSUED`, `CASH_BALANCE_TRANSFER.CONFIRMED`, `CASH_BALANCE_TRANSFER.CANCELLED`).", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type", "enum": [ "CASH_BALANCE_TRANSFER.ISSUED", "CASH_BALANCE_TRANSFER.CONFIRMED", "CASH_BALANCE_TRANSFER.CANCELLED" ] }, "object": { "title": "Payments - Cash Balance Transfer", "type": "object", "description": "Represents an internal cash balance transfer between two account groups belonging to the same user and tenant. Only settled cash in the same currency can be transferred.", "additionalProperties": false, "properties": { "id": { "title": "Cash balance transfer unique identifier", "type": "string", "description": "Cash balance transfer unique identifier", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "source_account_group_id": { "allOf": [ { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } ], "description": "The account group the cash is transferred from. Must differ from `target_account_group_id` and belong to the same user and tenant. Allowed account group types are `PERSONAL`, `CHILD`, and `BUSINESS`, and the source and target account groups must be of the same type." }, "target_account_group_id": { "allOf": [ { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } ], "description": "The account group the cash is transferred to. Must differ from `source_account_group_id` and belong to the same user and tenant. Allowed account group types are `PERSONAL`, `CHILD`, and `BUSINESS`, and the source and target account groups must be of the same type." }, "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "status": { "type": "string", "description": "Status of the cash balance transfer.\n* ISSUED - Transfer has been created and the cash movement is in progress.\n* CONFIRMED - Cash was successfully moved from the source to the target account group.\n* CANCELLED - Transfer was cancelled and no cash was moved.", "enum": [ "ISSUED", "CONFIRMED", "CANCELLED" ] }, "cancellation_reason": { "type": "string", "nullable": true, "description": "Reason the transfer was cancelled. Present only when `status` is `CANCELLED`, otherwise `null`." } }, "required": [ "id", "source_account_group_id", "target_account_group_id", "amount", "currency", "status", "created_at", "updated_at" ] }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "example": { "id": "8962b496-8d42-4560-bfab-10490dd1a721", "created_at": "2026-06-25T14:15:23Z", "type": "CASH_BALANCE_TRANSFER.CONFIRMED", "object": { "id": "b3f6a0c2-1d7e-4a3b-9f21-0c2d4e6f8a10", "created_at": "2026-06-25T14:15:22Z", "updated_at": "2026-06-25T14:15:23Z", "source_account_group_id": "2596db3b-0d03-4651-9eda-970910479dfb", "target_account_group_id": "e56c14b3-8370-4c04-bc67-7092f7ec113c", "amount": "200.00", "currency": "EUR", "status": "CONFIRMED", "cancellation_reason": null }, "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6" } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Virtual Bank Accounts events": { "post": { "operationId": "virtual_bank_account_event", "summary": "Virtual Bank Accounts events", "description": "Webhook callback payload for virtual bank account creation events (`VIRTUAL_BANK_ACCOUNT.CREATED`).", "tags": [ "Virtual Bank Accounts" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Virtual Bank Account - Callback", "type": "object", "description": "Webhook callback payload for virtual bank account creation events (`VIRTUAL_BANK_ACCOUNT.CREATED`).", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type", "enum": [ "VIRTUAL_BANK_ACCOUNT.CREATED" ] }, "object": { "type": "object", "description": "Represents a virtual bank account assigned to an account group. Provides an IBAN and BIC that end users can use to send SEPA Credit Transfers directly to their investment account.", "properties": { "id": { "title": "Virtual bank account request unique identifier.", "type": "string", "description": "Virtual bank account request unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "name": { "type": "string", "description": "Name of the virtual bank account" }, "owner": { "type": "object", "description": "Owner of the virtual bank account", "properties": { "name": { "type": "string", "description": "Name of the owner of the virtual bank account" } }, "required": [ "name" ], "additionalProperties": false }, "identification": { "type": "object", "description": "Identification details", "properties": { "swift": { "type": "object", "description": "SWIFT details", "properties": { "iban": { "title": "International Bank Account Number (IBAN)", "type": "string", "description": "International Bank Account Number [IBAN](https://en.wikipedia.org/wiki/International_Bank_Account_Number).", "pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,26}$" }, "bic": { "title": "Business Identifier Code", "type": "string", "description": "Business Identifier Code (also known as SWIFT-BIC, BIC, SWIFT ID or SWIFT code) [ISO 9362](https://en.wikipedia.org/wiki/ISO_9362).", "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$" } }, "required": [ "iban", "bic" ], "additionalProperties": false } }, "additionalProperties": false } }, "required": [ "id", "created_at", "account_group_id", "owner", "identification" ], "additionalProperties": false }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "example": { "id": "8962b496-8d42-4560-bfab-10490dd1a721", "created_at": "2021-07-21T14:10:00.00Z", "type": "VIRTUAL_BANK_ACCOUNT.CREATED", "object": { "id": "22913092-0484-42e9-9273-9ffd6dfd0b13", "created_at": "2021-07-21T14:10:00.00Z", "account_group_id": "d1354aad-6da7-4da7-aaa1-e00ebfd3240d", "name": "Max's Virtual Bank Account", "owner": { "name": "Max Musterman" }, "identification": { "swift": { "iban": "DE89000000000000000000", "bic": "ABCDEXXX" } } }, "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6" } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Portfolio orders events": { "post": { "operationId": "portfolio_order_event", "summary": "Portfolios orders events", "description": "Fires when a portfolio order transitions to a new status (`PORTFOLIO_ORDER.NEW`, `PORTFOLIO_ORDER.PROCESSING`, `PORTFOLIO_ORDER.FILLED`, `PORTFOLIO_ORDER.SETTLED`, `PORTFOLIO_ORDER.CANCELLED`).", "tags": [ "Portfolios" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Portfolios Orders - Callback", "type": "object", "description": "Webhook callback payload for portfolio order lifecycle events (`PORTFOLIO_ORDER.NEW`, `PORTFOLIO_ORDER.PROCESSING`, `PORTFOLIO_ORDER.FILLED`, `PORTFOLIO_ORDER.SETTLED`, `PORTFOLIO_ORDER.CANCELLED`).", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type", "enum": [ "PORTFOLIO_ORDER.NEW", "PORTFOLIO_ORDER.PROCESSING", "PORTFOLIO_ORDER.FILLED", "PORTFOLIO_ORDER.SETTLED", "PORTFOLIO_ORDER.CANCELLED" ] }, "object": { "title": "Portfolios order", "type": "object", "description": "Represents a portfolio order — a BUY or SELL instruction that invests or withdraws a cash amount distributed across all instruments in the account's current allocation.", "properties": { "id": { "title": "Portfolios order unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio order.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "allocation_id": { "title": "Portfolio allocation unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio allocation.", "format": "uuid" }, "cash_amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "status": { "type": "string", "description": "Execution status of the Portfolio Order.\n* NEW - \n* PROCESSING - \n* FILLED - \n* SETTLED - \n* CANCELLED - ", "enum": [ "NEW", "PROCESSING", "FILLED", "SETTLED", "CANCELLED" ] }, "type": { "type": "string", "description": "Type of the Portfolio Order.\n* BUY - \n* SELL - \n* REBALANCING - ", "enum": [ "BUY", "SELL", "REBALANCING" ] }, "post_tax": { "type": "boolean", "description": "Cash amount is post-tax value", "default": false }, "orders": { "type": "array", "description": "Orders associated with this portfolio order", "items": { "title": "Portfolios order", "type": "object", "description": "An individual instrument order within a portfolio order, representing the BUY or SELL of a single instrument.", "properties": { "id": { "title": "Order unique identifier", "type": "string", "description": "Unique identifier for an order. Universally Unique Identifier (UUID).", "format": "uuid" }, "side": { "type": "string", "description": "Side of the portfolio order.\n* BUY - \n* SELL - ", "enum": [ "BUY", "SELL" ] }, "status": { "type": "string", "description": "The execution status of the order.\n* NEW — the order has been received and validated, awaiting routing.\n* PROCESSING — the order is being routed for execution.\n* FILLED — the order has been fully executed.\n* CANCELLED — the order was cancelled before being fully executed.", "enum": [ "NEW", "PROCESSING", "FILLED", "CANCELLED" ] } }, "required": [ "id", "side", "status" ], "additionalProperties": false } }, "client_reference": { "title": "An ID provided by the client", "type": "string", "description": "A reference string provided by the client to correlate the portfolio order with a record in the client's own system." }, "initiation_flow": { "title": "Initiation flow used during order creation", "description": "What triggered the order creation .\n* API - \n* SAVINGS_PLAN - ", "type": "string", "enum": [ "API", "SAVINGS_PLAN" ] }, "cancellation_reason": { "title": "Cancellation reason code", "description": "Explains the reason why the order was cancelled .\n* ACCOUNT_IS_EMPTY - \n* CANCELLED_BY_CLIENT - \n* CANCELLED_BY_UPVEST - \n* PORTFOLIO_IS_BALANCED - \n* SELL_LIMIT_EXCEEDED - ", "type": "string", "enum": [ "ACCOUNT_IS_EMPTY", "CANCELLED_BY_CLIENT", "CANCELLED_BY_UPVEST", "PORTFOLIO_IS_BALANCED", "SELL_LIMIT_EXCEEDED" ] }, "cancellation_details": { "type": "string" } }, "required": [ "id", "created_at", "updated_at", "account_id", "cash_amount", "currency", "status", "post_tax", "client_reference", "initiation_flow", "orders" ], "additionalProperties": false }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "example": { "id": "54b8d84f-5bd0-4e43-bf0f-164388cb4c23", "created_at": "2021-07-21T14:10:00.00Z", "type": "PORTFOLIO_ORDER.NEW", "object": { "id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c", "created_at": "2021-07-21T14:10:00.000Z", "updated_at": "2021-07-21T14:10:00.000Z", "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3", "allocation_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3", "cash_amount": "1000", "currency": "EUR", "status": "PROCESSING", "type": "SELL", "post_tax": false, "client_reference": "", "initiation_flow": "API", "orders": [ { "id": "e7aecb80-5e84-4bf7-984b-b39ab77eb0a8", "side": "SELL", "status": "NEW" }, { "id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c", "side": "SELL", "status": "PROCESSING" }, { "id": "d8a85120-2941-4ed6-8d57-e80401a4779c", "side": "SELL", "status": "FILLED" } ] }, "webhook_id": "cd2e4183-4e62-4e0f-981b-44b594d14610" } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Portfolio rebalancing execution orders events": { "post": { "operationId": "portfolio_rebalancing_execution_order_event", "summary": "Portfolio rebalancing execution orders events", "description": "Portfolio rebalancing execution orders events", "tags": [ "Portfolios Rebalancing" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Portfolio Rebalancing Execution Order - Callback", "type": "object", "description": "Webhook callback payload for rebalancing execution order lifecycle events (`REBALANCING_EXECUTION_ORDER.NEW`, `REBALANCING_EXECUTION_ORDER.PROCESSING`, `REBALANCING_EXECUTION_ORDER.FILLED`, `REBALANCING_EXECUTION_ORDER.CANCELLED`).", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type", "enum": [ "REBALANCING_EXECUTION_ORDER.NEW", "REBALANCING_EXECUTION_ORDER.PROCESSING", "REBALANCING_EXECUTION_ORDER.CANCELLED", "REBALANCING_EXECUTION_ORDER.FILLED" ] }, "object": { "title": "Portfolios rebalancing execution order", "type": "object", "description": "An individual account-level order within a rebalancing execution. Each entry corresponds to a single account being rebalanced and has its own status lifecycle.", "properties": { "id": { "title": "Rebalancing execution order unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a rebalancing execution order.", "format": "uuid" }, "execution_id": { "title": "Portfolio rebalancing execution unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio rebalancing execution.", "format": "uuid" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "portfolio_order_id": { "oneOf": [ { "title": "Portfolios order unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio order.", "format": "uuid" }, { "type": "null" } ] }, "status": { "type": "string", "description": "Status of the Rebalancing Execution Order.\n* NEW - \n* PROCESSING - \n* FILLED - \n* CANCELLED - ", "enum": [ "NEW", "PROCESSING", "FILLED", "CANCELLED" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "cancellation_reason": { "type": "string", "description": "Reason for Rebalancing Execution Order Cancellation. The field is present in case the Order has a status of CANCELLED.\n* ACCOUNT_IS_EMPTY - \n* ACCOUNT_NOT_FOUND - \n* CANCELLED_BY_CLIENT - \n* CANCELLED_BY_UPVEST - \n* CONFIGURATION_IS_MISSING - \n* INVALID_ACCOUNT_TYPE - \n* PORTFOLIO_IS_BALANCED - \n* UNKNOWN - ", "enum": [ "ACCOUNT_IS_EMPTY", "ACCOUNT_NOT_FOUND", "CANCELLED_BY_CLIENT", "CANCELLED_BY_UPVEST", "CONFIGURATION_IS_MISSING", "INVALID_ACCOUNT_TYPE", "PORTFOLIO_IS_BALANCED", "UNKNOWN" ] }, "cancellation_details": { "type": "string" } }, "required": [ "id", "execution_id", "account_id", "portfolio_order_id", "status", "created_at", "updated_at" ], "additionalProperties": false }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "example": { "id": "54b8d84f-5bd0-4e43-bf0f-164388cb4c23", "created_at": "2021-07-21T14:10:00.00Z", "type": "REBALANCING_EXECUTION_ORDER.NEW", "object": { "id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c", "execution_id": "760abce7-e6b5-440b-bdf3-88e35ed6417a", "created_at": "2021-07-21T14:10:00.000Z", "updated_at": "2021-07-21T14:10:00.000Z", "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3", "portfolio_order_id": "4f2f5db9-ef4e-4dbf-80a1-bffc71985d6c", "status": "PROCESSING" }, "webhook_id": "cd2e4183-4e62-4e0f-981b-44b594d14610" } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Portfolio allocations events": { "post": { "operationId": "portfolio_allocation_event", "summary": "Portfolios allocations events", "description": "Fires when a portfolio allocation is created or updated (`PORTFOLIO_ALLOCATION.CREATED`, `PORTFOLIO_ALLOCATION.CHANGED`).", "tags": [ "Portfolios" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Portfolios Orders - Callback", "type": "object", "description": "Webhook callback payload for portfolio allocation events (`PORTFOLIO_ALLOCATION.CREATED`, `PORTFOLIO_ALLOCATION.CHANGED`).", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type", "enum": [ "PORTFOLIO_ALLOCATION.CREATED", "PORTFOLIO_ALLOCATION.CHANGED" ] }, "object": { "title": "Portfolios allocation", "type": "object", "description": "Defines a named set of instrument weights for a portfolio. The `allocation` array specifies each instrument (by ISIN or Upvest UUID) and its target weight percentage. Weights must sum to 100.", "properties": { "id": { "title": "Portfolio allocation unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio allocation.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "name": { "description": "Allocation name", "type": "string" }, "allocation": { "description": "List of portfolios allocations", "type": "array", "items": { "type": "object", "properties": { "instrument_id": { "oneOf": [ { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, { "title": "Unique identifier", "description": "UPVEST instrument identifier", "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$" } ] }, "instrument_id_type": { "description": "The type of the ID used in the request.\n* ISIN - International Securities Identification Number\n* UPVEST - UPVEST's unique instrument identifier", "enum": [ "ISIN", "UPVEST" ], "default": "ISIN", "type": "string" }, "weight": { "description": "Instrument allocation weight", "type": "string", "pattern": "^(100|[0-9]{1,2}(\\.[0-9]{1,5})?)$" } }, "required": [ "instrument_id", "instrument_id_type", "weight" ], "additionalProperties": false } } }, "required": [ "id", "created_at", "updated_at", "name", "allocation" ], "additionalProperties": false }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "example": { "id": "54b8d84f-5bd0-4e43-bf0f-164388cb4c23", "created_at": "2021-07-21T14:10:00.00Z", "type": "PORTFOLIO_ALLOCATION.CREATED", "object": { "id": "436244bb-4afd-4002-b53b-b1d7a3bca032", "created_at": "2021-07-21T14:10:00.00Z", "updated_at": "2021-07-21T14:10:00.00Z", "name": "Allocation 1", "allocation": [ { "instrument_id": "IE00B0M62Q58", "instrument_id_type": "ISIN", "weight": "0.7" }, { "instrument_id": "US0378331005", "instrument_id_type": "ISIN", "weight": "0.3" } ] }, "webhook_id": "cd2e4183-4e62-4e0f-981b-44b594d14610" } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Savings plan execution events": { "post": { "operationId": "savings_plan_execution_event", "summary": "Savings plan execution events", "description": "Fires when a savings plan execution changes status (`SAVINGS_PLAN_EXECUTION.NEW`, `SAVINGS_PLAN_EXECUTION.PROCESSING`, `SAVINGS_PLAN_EXECUTION.FILLED`, `SAVINGS_PLAN_EXECUTION.SETTLED`, `SAVINGS_PLAN_EXECUTION.CANCELLED`, `SAVINGS_PLAN_EXECUTION.REMINDER`, `SAVINGS_PLAN_EXECUTION.DATA_CHANGED`).", "tags": [ "Savings Plans" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Savings Plan Executions - Callback", "type": "object", "description": "Webhook callback payload for savings plan execution events (`SAVINGS_PLAN_EXECUTION.NEW`, `SAVINGS_PLAN_EXECUTION.PROCESSING`, `SAVINGS_PLAN_EXECUTION.FILLED`, `SAVINGS_PLAN_EXECUTION.SETTLED`, `SAVINGS_PLAN_EXECUTION.CANCELLED`, `SAVINGS_PLAN_EXECUTION.REMINDER`, `SAVINGS_PLAN_EXECUTION.DATA_CHANGED`).", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type", "enum": [ "SAVINGS_PLAN_EXECUTION.NEW", "SAVINGS_PLAN_EXECUTION.PROCESSING", "SAVINGS_PLAN_EXECUTION.FILLED", "SAVINGS_PLAN_EXECUTION.SETTLED", "SAVINGS_PLAN_EXECUTION.CANCELLED", "SAVINGS_PLAN_EXECUTION.REMINDER", "SAVINGS_PLAN_EXECUTION.DATA_CHANGED" ] }, "object": { "title": "Savings plan execution", "anyOf": [ { "title": "Savings plan execution (instrument)", "type": "object", "description": "Represents a single execution of an `INSTRUMENT`-type savings plan, recording the order placed, the execution date, and the resulting status.", "properties": { "id": { "title": "Savings plan execution unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a savings plan execution.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "savings_plan_id": { "title": "Savings plan unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a savings plan.", "format": "uuid" }, "order_id": { "title": "Order unique identifier (Portfolio order or Instrument order)", "description": "Order unique identifier (Portfolio order or Instrument order)", "oneOf": [ { "title": "Portfolios order unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio order.", "format": "uuid" }, { "title": "Order", "type": "object", "description": "Represents an investment order placed by an end user or on their behalf. An order transitions through states (`NEW` → `PROCESSING` → `FILLED` or `CANCELLED`) as it is routed and executed.", "properties": { "id": { "title": "Order unique identifier", "type": "string", "description": "Unique identifier for an order. Universally Unique Identifier (UUID).", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "type": "string", "format": "uuid", "description": "The ID of the user. Either user ID or business ID must be specified." }, "business_id": { "type": "string", "format": "uuid", "description": "The ID of the business. Either user ID or business ID must be specified." }, "account_id": { "type": "string", "format": "uuid", "description": "The ID of the account that owns the order" }, "cash_amount": { "allOf": [ { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, { "description": "Cash amount for a nominal order, not required if a share quantity is specified." } ] }, "currency": { "allOf": [ { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound\n* USD - US Dollar", "enum": [ "EUR", "GBP", "USD" ] }, { "description": "The currency for the order." } ] }, "side": { "type": "string", "description": "Side of the order.\n* BUY — purchases the specified instrument.\n* SELL — disposes of the specified instrument.", "enum": [ "BUY", "SELL" ] }, "instrument_id": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, "instrument_id_type": { "description": "The type of the ID used in the request.\n* ISIN - ", "enum": [ "ISIN" ], "default": "ISIN", "type": "string" }, "order_type": { "type": "string", "description": "Type of the order.\n* MARKET — executes immediately at the best available market price.\n* LIMIT — executes only at or better than the specified `limit_price`.\n* STOP — triggers when the market price reaches `stop_price`, then executes at the prevailing market price.", "enum": [ "MARKET", "LIMIT", "STOP" ] }, "quantity": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "Quantity of securities for the order. Only required if the cash amount is not specified." } ] }, "user_instrument_fit_acknowledgement": { "type": "boolean", "description": "Only applicable if the user has failed the instrument fit check for the instrument type being ordered. True if the user has acknowledged their willingness to trade." }, "limit_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The limit price for orders of the type 'limit'." } ] }, "stop_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The stop price for orders of the type 'stop'." } ] }, "expiry_date": { "allOf": [ { "title": "Expiry date", "type": "string", "description": "Order expiration date in YYYY-MM-DD format. Only applicable to `LIMIT` and `STOP` orders — the order will not execute after this date. Defaults to order creation date plus 359 days.", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, { "description": "The order expiration date (last day the order can trade) in the YYYY-MM-DD format. The expiry date can only be set for LIMIT and STOP orders. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339. The default value is order creation date + 359 days" } ] }, "status": { "type": "string", "description": "The execution status of the order.\n* NEW — the order has been received and validated, awaiting routing.\n* PROCESSING — the order is being routed for execution.\n* FILLED — the order has been fully executed.\n* CANCELLED — the order was cancelled before being fully executed.", "enum": [ "NEW", "PROCESSING", "FILLED", "CANCELLED" ] }, "fee": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "cancellation_reason": { "type": "string", "description": "Reason for order cancellation. Present only when `status` is `CANCELLED`.\n* CANCELLED_BY_CLIENT — cancelled at the end user's or client's request via the API.\n* CANCELLED_BY_UPVEST_OPERATIONS — cancelled by Upvest operations.\n* CANCELLED_BY_TRADING_PARTNER — cancelled by the executing partner.\n* CANCELLED_BY_UPVEST_PLATFORM — cancelled automatically by the Upvest platform.", "enum": [ "CANCELLED_BY_CLIENT", "CANCELLED_BY_UPVEST_OPERATIONS", "CANCELLED_BY_TRADING_PARTNER", "CANCELLED_BY_UPVEST_PLATFORM" ] }, "initiation_flow": { "type": "string", "description": "Identifies what triggered the order.\n* API — initiated directly via the client API.\n* PORTFOLIO — initiated by a portfolio rebalancing flow.\n* CASH_DIVIDEND_REINVESTMENT — initiated as part of dividend reinvestment.\n* PORTFOLIO_REBALANCING — initiated by an automated rebalancing.\n* SELL_TO_COVER_FEES — initiated automatically to cover outstanding fees.\n* SELL_TO_COVER_TAXES — initiated automatically to cover tax obligations.\n* ACCOUNT_LIQUIDATION — initiated as part of an account liquidation.\n* UPVEST_OPERATIONS — initiated by Upvest operations.\n* SAVINGS_PLAN — initiated by a savings plan execution.\n* CLIENT_OPERATIONS — initiated by client operations.", "enum": [ "API", "PORTFOLIO", "CASH_DIVIDEND_REINVESTMENT", "PORTFOLIO_REBALANCING", "SELL_TO_COVER_FEES", "SELL_TO_COVER_TAXES", "ACCOUNT_LIQUIDATION", "UPVEST_OPERATIONS", "SAVINGS_PLAN", "CLIENT_OPERATIONS" ] }, "execution_flow": { "type": "string", "description": "Execution flow for order processing. Defaults to `STRAIGHT_THROUGH` if not specified.\n* STRAIGHT_THROUGH — the order is routed and executed directly without manual intervention.\n* BLOCK — the order is bundled with other orders for block execution.", "enum": [ "STRAIGHT_THROUGH", "BLOCK" ] }, "executions": { "type": "array", "description": "Order executions associated with this order", "items": { "title": "Order execution", "type": "object", "description": "Represents a single execution (trade fill) within an order. An order may have multiple executions if it is partially filled across several trades.", "properties": { "id": { "title": "Order execution unique identifier", "type": "string", "format": "uuid" }, "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "share_quantity": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "price": { "type": "string", "description": "Price of an instrument for a trade execution provided as a decimal string.", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,4})?$" }, "transaction_time": { "type": "string", "format": "date-time", "description": "Timestamp of when the trade was executed at the market. [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) date-time format." }, "taxes": { "type": "array", "description": "Taxes deducted as part of this execution.", "items": { "title": "Tax", "type": "object", "description": "Tax deducted as part of an order execution. Contains the tax type and the deducted amount.", "properties": { "type": { "type": "string", "description": "Tax type\n* TOTAL - ", "default": "TOTAL", "enum": [ "TOTAL" ] }, "amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" } }, "required": [ "type", "amount" ] } }, "order_id": { "title": "Order unique identifier", "type": "string", "description": "Unique identifier for an order. Universally Unique Identifier (UUID).", "format": "uuid" }, "status": { "type": "string", "description": "Status of the execution.\n* FILLED — the execution has been filled.\n* SETTLED — the execution has settled and securities and cash have been exchanged.\n* CANCELLED — the execution was cancelled before settlement.", "enum": [ "FILLED", "SETTLED", "CANCELLED" ] }, "side": { "type": "string", "description": "Side of the execution.\n* BUY — a buy execution.\n* SELL — a sell execution.", "enum": [ "BUY", "SELL" ] }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound\n* USD - US Dollar", "enum": [ "EUR", "GBP", "USD" ] }, "settlement_date": { "allOf": [ { "title": "Settlement date", "type": "string", "description": "Trade settlement date in YYYY-MM-DD format. The date on which securities and cash are exchanged following execution.", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, { "description": "Order execution settlement date in the YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339" } ] }, "venue_id": { "type": "string", "format": "uuid", "description": "The ID of the venue" } }, "required": [ "id", "cash_amount", "share_quantity", "price", "transaction_time", "taxes", "order_id", "status", "side", "currency", "venue_id" ], "additionalProperties": false } }, "client_reference": { "type": "string", "description": "Immutable reference to the API flow that initiated the order. For client initiated API flows, this is a client provided ID. For internal initiations, it is set to the ID of the related object.", "maxLength": 100 }, "fee_configuration": { "type": "array", "description": "Fee configuration applied to this order. Determines how the order fee is calculated.", "items": { "title": "Fee", "description": "A fee applied to an order. Either a fixed absolute cash fee (`absolute_fee_configuration_item`) or a reference to a predefined transaction fee model.", "oneOf": [ { "title": "Absolute Fee", "type": "object", "description": "A fixed cash fee applied to an order, specified as an absolute amount in a given currency.", "properties": { "type": { "title": "Fee type", "description": "Fee type\n* TRANSACTION_FEE_BUY - \n* TRANSACTION_FEE_SELL - ", "type": "string", "enum": [ "TRANSACTION_FEE_BUY", "TRANSACTION_FEE_SELL" ] }, "value_type": { "type": "string", "default": "ABSOLUTE", "description": "The value type must be “ABSOLUTE”." }, "charge_method": { "title": "Fee charge method", "type": "string", "description": "Indicates whether the fee will be charged by client or by other methods.\n* CHARGED_BY_CLIENT - \n* COLLECTED_BY_UPVEST - ", "enum": [ "CHARGED_BY_CLIENT", "COLLECTED_BY_UPVEST" ] }, "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound\n* USD - US Dollar", "enum": [ "EUR", "GBP", "USD" ] } }, "required": [ "type", "value_type", "charge_method", "cash_amount", "currency" ], "additionalProperties": false }, { "title": "Transaction Fee Model", "type": "object", "description": "A fee configuration that references a predefined transaction fee model by its ID, rather than specifying a fee amount directly.", "properties": { "type": { "title": "Fee type", "description": "Fee type\n* TRANSACTION_FEE_BUY - \n* TRANSACTION_FEE_SELL - ", "type": "string", "enum": [ "TRANSACTION_FEE_BUY", "TRANSACTION_FEE_SELL" ] }, "transaction_fee_model_id": { "type": "string", "format": "uuid", "description": "The ID of the transaction fee model." } }, "required": [ "type", "transaction_fee_model_id" ], "additionalProperties": false } ] } }, "decision_maker_id": { "type": "string", "description": "ID of the user behind the decision to place an order. Required only if different from the user_id. (e.g. child account order placed by a guardian)" } }, "required": [ "id", "created_at", "updated_at", "account_id", "cash_amount", "currency", "side", "instrument_id", "instrument_id_type", "order_type", "quantity", "status", "fee", "initiation_flow", "executions" ], "additionalProperties": false }, { "type": "null" } ] }, "cash_amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "status": { "type": "string", "description": "Status of a Savings Plan Execution. \n* NEW - \n* PROCESSING - \n* FILLED - \n* SETTLED - \n* CANCELLED - ", "enum": [ "NEW", "PROCESSING", "FILLED", "SETTLED", "CANCELLED" ] }, "type": { "type": "string", "default": "INSTRUMENT", "description": "The type of savings plan must be \"INSTRUMENT\"." }, "execution_date": { "type": "string", "description": "Date of a savings plan execution in YYYY-MM-DD format.", "pattern": "^[12]\\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "instrument_id": { "title": "Instrument unique identifier", "description": "Instrument unique identifier.", "oneOf": [ { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, { "title": "German securities identification code", "type": "string", "description": "German securities identification code known as [Wertpapierkennnummer](https://en.wikipedia.org/wiki/Wertpapierkennnummer).", "pattern": "^[A-HJ-NP-Z0-9]{6}$" } ] }, "instrument_id_type": { "type": "string", "description": "The type of the ID used in the request.\n* ISIN - International Securities Identification Number\n* WKN - German securities identification code", "enum": [ "ISIN", "WKN" ], "default": "ISIN" }, "fee_configuration": { "title": "Savings plan fee configuration, only for instrument", "type": "array", "description": "Fee configuration for instrument-type savings plan executions. Specifies the transaction fee model to apply to each buy order placed on execution.", "items": { "type": "object", "properties": { "type": { "title": "Fee type", "description": "Fee type\n* TRANSACTION_FEE_BUY -", "type": "string", "enum": [ "TRANSACTION_FEE_BUY" ] }, "transaction_fee_model_id": { "title": "Fee model unique identifier.", "type": "string", "description": "Universally Unique Identifier (UUID) of the transaction fee model.", "format": "uuid" } }, "required": [ "type", "transaction_fee_model_id" ], "additionalProperties": false } }, "cancellation_reason": { "title": "Cancellation reason code for savings plan execution", "description": "Explains the reason why the savings plan execution was cancelled .\n* CANCELLED_BY_CLIENT: The savings plan execution was cancelled by the client.\n* CANCELLED_BY_UPVEST: The savings plan execution was cancelled by Upvest.", "type": "string", "enum": [ "CANCELLED_BY_CLIENT", "CANCELLED_BY_UPVEST" ] }, "cancellation_details": { "title": "Cancellation details for savings plan execution", "description": "Human-readable description providing additional context about why the savings plan execution was cancelled.", "type": "string" } }, "required": [ "id", "user_id", "account_id", "savings_plan_id", "order_id", "cash_amount", "currency", "status", "type", "execution_date", "created_at", "updated_at" ], "additionalProperties": false }, { "title": "Savings plan execution (portfolio)", "type": "object", "description": "Represents a single execution of a `PORTFOLIO`-type savings plan, recording the portfolio order placed, the execution date, and the resulting status.", "properties": { "id": { "title": "Savings plan execution unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a savings plan execution.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "savings_plan_id": { "title": "Savings plan unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a savings plan.", "format": "uuid" }, "order_id": { "title": "Order unique identifier (Portfolio order or Instrument order)", "description": "Order unique identifier (Portfolio order or Instrument order)", "oneOf": [ { "title": "Portfolios order unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio order.", "format": "uuid" }, { "title": "Order", "type": "object", "description": "Represents an investment order placed by an end user or on their behalf. An order transitions through states (`NEW` → `PROCESSING` → `FILLED` or `CANCELLED`) as it is routed and executed.", "properties": { "id": { "title": "Order unique identifier", "type": "string", "description": "Unique identifier for an order. Universally Unique Identifier (UUID).", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "type": "string", "format": "uuid", "description": "The ID of the user. Either user ID or business ID must be specified." }, "business_id": { "type": "string", "format": "uuid", "description": "The ID of the business. Either user ID or business ID must be specified." }, "account_id": { "type": "string", "format": "uuid", "description": "The ID of the account that owns the order" }, "cash_amount": { "allOf": [ { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, { "description": "Cash amount for a nominal order, not required if a share quantity is specified." } ] }, "currency": { "allOf": [ { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound\n* USD - US Dollar", "enum": [ "EUR", "GBP", "USD" ] }, { "description": "The currency for the order." } ] }, "side": { "type": "string", "description": "Side of the order.\n* BUY — purchases the specified instrument.\n* SELL — disposes of the specified instrument.", "enum": [ "BUY", "SELL" ] }, "instrument_id": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, "instrument_id_type": { "description": "The type of the ID used in the request.\n* ISIN - ", "enum": [ "ISIN" ], "default": "ISIN", "type": "string" }, "order_type": { "type": "string", "description": "Type of the order.\n* MARKET — executes immediately at the best available market price.\n* LIMIT — executes only at or better than the specified `limit_price`.\n* STOP — triggers when the market price reaches `stop_price`, then executes at the prevailing market price.", "enum": [ "MARKET", "LIMIT", "STOP" ] }, "quantity": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "Quantity of securities for the order. Only required if the cash amount is not specified." } ] }, "user_instrument_fit_acknowledgement": { "type": "boolean", "description": "Only applicable if the user has failed the instrument fit check for the instrument type being ordered. True if the user has acknowledged their willingness to trade." }, "limit_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The limit price for orders of the type 'limit'." } ] }, "stop_price": { "allOf": [ { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, { "description": "The stop price for orders of the type 'stop'." } ] }, "expiry_date": { "allOf": [ { "title": "Expiry date", "type": "string", "description": "Order expiration date in YYYY-MM-DD format. Only applicable to `LIMIT` and `STOP` orders — the order will not execute after this date. Defaults to order creation date plus 359 days.", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, { "description": "The order expiration date (last day the order can trade) in the YYYY-MM-DD format. The expiry date can only be set for LIMIT and STOP orders. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339. The default value is order creation date + 359 days" } ] }, "status": { "type": "string", "description": "The execution status of the order.\n* NEW — the order has been received and validated, awaiting routing.\n* PROCESSING — the order is being routed for execution.\n* FILLED — the order has been fully executed.\n* CANCELLED — the order was cancelled before being fully executed.", "enum": [ "NEW", "PROCESSING", "FILLED", "CANCELLED" ] }, "fee": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "cancellation_reason": { "type": "string", "description": "Reason for order cancellation. Present only when `status` is `CANCELLED`.\n* CANCELLED_BY_CLIENT — cancelled at the end user's or client's request via the API.\n* CANCELLED_BY_UPVEST_OPERATIONS — cancelled by Upvest operations.\n* CANCELLED_BY_TRADING_PARTNER — cancelled by the executing partner.\n* CANCELLED_BY_UPVEST_PLATFORM — cancelled automatically by the Upvest platform.", "enum": [ "CANCELLED_BY_CLIENT", "CANCELLED_BY_UPVEST_OPERATIONS", "CANCELLED_BY_TRADING_PARTNER", "CANCELLED_BY_UPVEST_PLATFORM" ] }, "initiation_flow": { "type": "string", "description": "Identifies what triggered the order.\n* API — initiated directly via the client API.\n* PORTFOLIO — initiated by a portfolio rebalancing flow.\n* CASH_DIVIDEND_REINVESTMENT — initiated as part of dividend reinvestment.\n* PORTFOLIO_REBALANCING — initiated by an automated rebalancing.\n* SELL_TO_COVER_FEES — initiated automatically to cover outstanding fees.\n* SELL_TO_COVER_TAXES — initiated automatically to cover tax obligations.\n* ACCOUNT_LIQUIDATION — initiated as part of an account liquidation.\n* UPVEST_OPERATIONS — initiated by Upvest operations.\n* SAVINGS_PLAN — initiated by a savings plan execution.\n* CLIENT_OPERATIONS — initiated by client operations.", "enum": [ "API", "PORTFOLIO", "CASH_DIVIDEND_REINVESTMENT", "PORTFOLIO_REBALANCING", "SELL_TO_COVER_FEES", "SELL_TO_COVER_TAXES", "ACCOUNT_LIQUIDATION", "UPVEST_OPERATIONS", "SAVINGS_PLAN", "CLIENT_OPERATIONS" ] }, "execution_flow": { "type": "string", "description": "Execution flow for order processing. Defaults to `STRAIGHT_THROUGH` if not specified.\n* STRAIGHT_THROUGH — the order is routed and executed directly without manual intervention.\n* BLOCK — the order is bundled with other orders for block execution.", "enum": [ "STRAIGHT_THROUGH", "BLOCK" ] }, "executions": { "type": "array", "description": "Order executions associated with this order", "items": { "title": "Order execution", "type": "object", "description": "Represents a single execution (trade fill) within an order. An order may have multiple executions if it is partially filled across several trades.", "properties": { "id": { "title": "Order execution unique identifier", "type": "string", "format": "uuid" }, "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "share_quantity": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "price": { "type": "string", "description": "Price of an instrument for a trade execution provided as a decimal string.", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,4})?$" }, "transaction_time": { "type": "string", "format": "date-time", "description": "Timestamp of when the trade was executed at the market. [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) date-time format." }, "taxes": { "type": "array", "description": "Taxes deducted as part of this execution.", "items": { "title": "Tax", "type": "object", "description": "Tax deducted as part of an order execution. Contains the tax type and the deducted amount.", "properties": { "type": { "type": "string", "description": "Tax type\n* TOTAL - ", "default": "TOTAL", "enum": [ "TOTAL" ] }, "amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" } }, "required": [ "type", "amount" ] } }, "order_id": { "title": "Order unique identifier", "type": "string", "description": "Unique identifier for an order. Universally Unique Identifier (UUID).", "format": "uuid" }, "status": { "type": "string", "description": "Status of the execution.\n* FILLED — the execution has been filled.\n* SETTLED — the execution has settled and securities and cash have been exchanged.\n* CANCELLED — the execution was cancelled before settlement.", "enum": [ "FILLED", "SETTLED", "CANCELLED" ] }, "side": { "type": "string", "description": "Side of the execution.\n* BUY — a buy execution.\n* SELL — a sell execution.", "enum": [ "BUY", "SELL" ] }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound\n* USD - US Dollar", "enum": [ "EUR", "GBP", "USD" ] }, "settlement_date": { "allOf": [ { "title": "Settlement date", "type": "string", "description": "Trade settlement date in YYYY-MM-DD format. The date on which securities and cash are exchanged following execution.", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, { "description": "Order execution settlement date in the YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339" } ] }, "venue_id": { "type": "string", "format": "uuid", "description": "The ID of the venue" } }, "required": [ "id", "cash_amount", "share_quantity", "price", "transaction_time", "taxes", "order_id", "status", "side", "currency", "venue_id" ], "additionalProperties": false } }, "client_reference": { "type": "string", "description": "Immutable reference to the API flow that initiated the order. For client initiated API flows, this is a client provided ID. For internal initiations, it is set to the ID of the related object.", "maxLength": 100 }, "fee_configuration": { "type": "array", "description": "Fee configuration applied to this order. Determines how the order fee is calculated.", "items": { "title": "Fee", "description": "A fee applied to an order. Either a fixed absolute cash fee (`absolute_fee_configuration_item`) or a reference to a predefined transaction fee model.", "oneOf": [ { "title": "Absolute Fee", "type": "object", "description": "A fixed cash fee applied to an order, specified as an absolute amount in a given currency.", "properties": { "type": { "title": "Fee type", "description": "Fee type\n* TRANSACTION_FEE_BUY - \n* TRANSACTION_FEE_SELL - ", "type": "string", "enum": [ "TRANSACTION_FEE_BUY", "TRANSACTION_FEE_SELL" ] }, "value_type": { "type": "string", "default": "ABSOLUTE", "description": "The value type must be “ABSOLUTE”." }, "charge_method": { "title": "Fee charge method", "type": "string", "description": "Indicates whether the fee will be charged by client or by other methods.\n* CHARGED_BY_CLIENT - \n* COLLECTED_BY_UPVEST - ", "enum": [ "CHARGED_BY_CLIENT", "COLLECTED_BY_UPVEST" ] }, "cash_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound\n* USD - US Dollar", "enum": [ "EUR", "GBP", "USD" ] } }, "required": [ "type", "value_type", "charge_method", "cash_amount", "currency" ], "additionalProperties": false }, { "title": "Transaction Fee Model", "type": "object", "description": "A fee configuration that references a predefined transaction fee model by its ID, rather than specifying a fee amount directly.", "properties": { "type": { "title": "Fee type", "description": "Fee type\n* TRANSACTION_FEE_BUY - \n* TRANSACTION_FEE_SELL - ", "type": "string", "enum": [ "TRANSACTION_FEE_BUY", "TRANSACTION_FEE_SELL" ] }, "transaction_fee_model_id": { "type": "string", "format": "uuid", "description": "The ID of the transaction fee model." } }, "required": [ "type", "transaction_fee_model_id" ], "additionalProperties": false } ] } }, "decision_maker_id": { "type": "string", "description": "ID of the user behind the decision to place an order. Required only if different from the user_id. (e.g. child account order placed by a guardian)" } }, "required": [ "id", "created_at", "updated_at", "account_id", "cash_amount", "currency", "side", "instrument_id", "instrument_id_type", "order_type", "quantity", "status", "fee", "initiation_flow", "executions" ], "additionalProperties": false }, { "type": "null" } ] }, "cash_amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "status": { "type": "string", "description": "Status of a Savings Plan Execution. \n* NEW - \n* PROCESSING - \n* FILLED - \n* SETTLED - \n* CANCELLED - ", "enum": [ "NEW", "PROCESSING", "FILLED", "SETTLED", "CANCELLED" ] }, "type": { "type": "string", "default": "PORTFOLIO", "description": "The type of savings plan must be \"PORTFOLIO\"." }, "execution_date": { "type": "string", "description": "Date of a savings plan execution in YYYY-MM-DD format.", "pattern": "^[12]\\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "instrument_id": { "title": "Instrument unique identifier", "description": "Instrument unique identifier.", "oneOf": [ { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, { "title": "German securities identification code", "type": "string", "description": "German securities identification code known as [Wertpapierkennnummer](https://en.wikipedia.org/wiki/Wertpapierkennnummer).", "pattern": "^[A-HJ-NP-Z0-9]{6}$" } ] }, "instrument_id_type": { "type": "string", "description": "The type of the ID used in the request.\n* ISIN - International Securities Identification Number\n* WKN - German securities identification code", "enum": [ "ISIN", "WKN" ], "default": "ISIN" }, "cancellation_reason": { "title": "Cancellation reason code for savings plan execution", "description": "Explains the reason why the savings plan execution was cancelled .\n* CANCELLED_BY_CLIENT: The savings plan execution was cancelled by the client.\n* CANCELLED_BY_UPVEST: The savings plan execution was cancelled by Upvest.", "type": "string", "enum": [ "CANCELLED_BY_CLIENT", "CANCELLED_BY_UPVEST" ] }, "cancellation_details": { "title": "Cancellation details for savings plan execution", "description": "Human-readable description providing additional context about why the savings plan execution was cancelled.", "type": "string" } }, "required": [ "id", "user_id", "account_id", "savings_plan_id", "order_id", "cash_amount", "currency", "status", "type", "execution_date", "created_at", "updated_at" ], "additionalProperties": false } ] }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "examples": { "instrument": { "summary": "instrument", "value": { "id": "54b8d84f-5bd0-4e43-bf0f-164388cb4c23", "created_at": "2023-07-21T10:00:00.00Z", "type": "SAVINGS_PLAN_EXECUTION.NEW", "object": { "id": "fc34d28e-38f5-49d2-92f6-82acb79098f4", "created_at": "2023-07-21T14:10:00.00Z", "updated_at": "2023-07-21T15:10:00.00Z", "user_id": "4b9732bd-7496-4913-8a5f-6360479d7fed", "account_id": "00ef0be8-d564-43af-b3c7-11b7a2188030", "savings_plan_id": "c31083c1-1cd3-405f-95d1-f49a37f0e032", "order_id": null, "cash_amount": "100", "currency": "EUR", "status": "NEW", "type": "INSTRUMENT", "instrument_id": "DE0007664005", "instrument_id_type": "ISIN", "execution_date": "2023-07-23", "fee_configuration": [ { "type": "TRANSACTION_FEE_BUY", "transaction_fee_model_id": "3ae9403c-1611-46eb-84ee-e06a02bcfd08" } ] }, "webhook_id": "cd2e4183-4e62-4e0f-981b-44b594d14610" } }, "portfolio": { "summary": "portfolio", "value": { "id": "54b8d84f-5bd0-4e43-bf0f-164388cb4c23", "created_at": "2023-07-21T10:00:00.00Z", "type": "SAVINGS_PLAN_EXECUTION.NEW", "object": { "id": "fc34d28e-38f5-49d2-92f6-82acb79098f4", "created_at": "2023-07-21T14:10:00.00Z", "updated_at": "2023-07-21T15:10:00.00Z", "user_id": "4b9732bd-7496-4913-8a5f-6360479d7fed", "account_id": "00ef0be8-d564-43af-b3c7-11b7a2188030", "savings_plan_id": "c31083c1-1cd3-405f-95d1-f49a37f0e032", "order_id": null, "cash_amount": "100", "currency": "EUR", "status": "NEW", "type": "PORTFOLIO", "execution_date": "2023-07-23" }, "webhook_id": "cd2e4183-4e62-4e0f-981b-44b594d14610" } } } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Savings plan events": { "post": { "operationId": "savings_plan_event", "summary": "Savings plan events", "description": "Fires when a savings plan is created or cancelled (`SAVINGS_PLAN.CREATED`, `SAVINGS_PLAN.CANCELLED`).", "tags": [ "Savings Plans" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Savings Plan - Callback", "type": "object", "description": "Webhook callback payload for savings plan lifecycle events (`SAVINGS_PLAN.CREATED`, `SAVINGS_PLAN.CANCELLED`).", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type", "enum": [ "SAVINGS_PLAN.CREATED", "SAVINGS_PLAN.CANCELLED" ] }, "object": { "title": "Event savings plan request", "anyOf": [ { "title": "Savings plan (instrument)", "type": "object", "description": "Represents an `INSTRUMENT`-type savings plan — a recurring investment that automatically buys a fixed cash amount of a specified instrument on a defined schedule.", "properties": { "id": { "title": "Savings plan unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a savings plan.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "name": { "type": "string", "description": "Savings plan name" }, "type": { "type": "string", "description": "Type of the Savings plan.\n* PORTFOLIO - \n* INSTRUMENT - ", "enum": [ "PORTFOLIO", "INSTRUMENT" ] }, "instrument_id": { "title": "Instrument unique identifier", "description": "Instrument unique identifier.", "oneOf": [ { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, { "title": "German securities identification code", "type": "string", "description": "German securities identification code known as [Wertpapierkennnummer](https://en.wikipedia.org/wiki/Wertpapierkennnummer).", "pattern": "^[A-HJ-NP-Z0-9]{6}$" } ] }, "instrument_id_type": { "type": "string", "description": "The type of the ID used in the request.\n* ISIN - International Securities Identification Number\n* WKN - German securities identification code", "enum": [ "ISIN", "WKN" ], "default": "ISIN" }, "cash_amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "start_date": { "type": "string", "description": "First date of the savings plan execution in YYYY-MM-DD format.", "pattern": "^[12]\\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "period": { "type": "string", "description": "Unit of time. \n* WEEK - \n* MONTH - \n* YEAR - ", "enum": [ "WEEK", "MONTH", "YEAR" ] }, "interval": { "description": "Number of periods between executions", "type": "integer", "default": 1, "minimum": 1, "maximum": 1000 }, "status": { "type": "string", "description": "Status of a Savings Plan. \n* ACTIVE - \n* CANCELLED - ", "enum": [ "ACTIVE", "CANCELLED" ] }, "fee_configuration": { "title": "Savings plan fee configuration, only for instrument", "type": "array", "description": "Fee configuration for instrument-type savings plan executions. Specifies the transaction fee model to apply to each buy order placed on execution.", "items": { "type": "object", "properties": { "type": { "title": "Fee type", "description": "Fee type\n* TRANSACTION_FEE_BUY -", "type": "string", "enum": [ "TRANSACTION_FEE_BUY" ] }, "transaction_fee_model_id": { "title": "Fee model unique identifier.", "type": "string", "description": "Universally Unique Identifier (UUID) of the transaction fee model.", "format": "uuid" } }, "required": [ "type", "transaction_fee_model_id" ], "additionalProperties": false } }, "cancellation_reason": { "title": "Cancellation reason code for savings plan", "description": "Explains the reason why the savings plan was cancelled .\n* CANCELLED_BY_CLIENT: The savings plan was cancelled by the client.\n* CANCELLED_BY_UPVEST: The savings plan was cancelled by Upvest.", "type": "string", "enum": [ "CANCELLED_BY_CLIENT", "CANCELLED_BY_UPVEST" ] }, "cancellation_details": { "description": "Additional details about the cancellation", "type": "string" } }, "required": [ "id", "user_id", "account_id", "type", "cash_amount", "currency", "start_date", "period", "interval", "created_at", "updated_at" ], "additionalProperties": false }, { "title": "Savings plan (portfolio)", "type": "object", "description": "Represents a `PORTFOLIO`-type savings plan — a recurring investment that automatically distributes a fixed cash amount across the account's portfolio allocation on a defined schedule.", "properties": { "id": { "title": "Savings plan unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a savings plan.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "name": { "type": "string", "description": "Savings plan name" }, "type": { "type": "string", "description": "Type of the Savings plan.\n* PORTFOLIO - \n* INSTRUMENT - ", "enum": [ "PORTFOLIO", "INSTRUMENT" ] }, "instrument_id": { "title": "Instrument unique identifier", "description": "Instrument unique identifier.", "oneOf": [ { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, { "title": "German securities identification code", "type": "string", "description": "German securities identification code known as [Wertpapierkennnummer](https://en.wikipedia.org/wiki/Wertpapierkennnummer).", "pattern": "^[A-HJ-NP-Z0-9]{6}$" } ] }, "instrument_id_type": { "type": "string", "description": "The type of the ID used in the request.\n* ISIN - International Securities Identification Number\n* WKN - German securities identification code", "enum": [ "ISIN", "WKN" ], "default": "ISIN" }, "cash_amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "start_date": { "type": "string", "description": "First date of the savings plan execution in YYYY-MM-DD format.", "pattern": "^[12]\\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "period": { "type": "string", "description": "Unit of time. \n* WEEK - \n* MONTH - \n* YEAR - ", "enum": [ "WEEK", "MONTH", "YEAR" ] }, "interval": { "description": "Number of periods between executions", "type": "integer", "default": 1, "minimum": 1, "maximum": 1000 }, "status": { "type": "string", "description": "Status of a Savings Plan. \n* ACTIVE - \n* CANCELLED - ", "enum": [ "ACTIVE", "CANCELLED" ] }, "cancellation_reason": { "title": "Cancellation reason code for savings plan", "description": "Explains the reason why the savings plan was cancelled .\n* CANCELLED_BY_CLIENT: The savings plan was cancelled by the client.\n* CANCELLED_BY_UPVEST: The savings plan was cancelled by Upvest.", "type": "string", "enum": [ "CANCELLED_BY_CLIENT", "CANCELLED_BY_UPVEST" ] }, "cancellation_details": { "description": "Additional details about the cancellation", "type": "string" } }, "required": [ "id", "user_id", "account_id", "type", "cash_amount", "currency", "start_date", "period", "interval", "created_at", "updated_at" ], "additionalProperties": false } ] }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "examples": { "instrument": { "summary": "instrument", "value": { "id": "54b8d84f-5bd0-4e43-bf0f-164388cb4c23", "created_at": "2023-07-21T10:00:00.00Z", "type": "SAVINGS_PLAN.CREATED", "object": { "id": "fc34d28e-38f5-49d2-92f6-82acb79098f4", "created_at": "2023-07-21T14:10:00.00Z", "updated_at": "2023-07-21T15:10:00.00Z", "user_id": "4b9732bd-7496-4913-8a5f-6360479d7fed", "account_id": "00ef0be8-d564-43af-b3c7-11b7a2188030", "name": "Instrument savings plan", "type": "INSTRUMENT", "instrument_id": "DE0007664005", "instrument_id_type": "ISIN", "cash_amount": "100.00", "currency": "EUR", "start_date": "2023-07-24", "period": "WEEK", "interval": 1, "status": "ACTIVE", "fee_configuration": [ { "type": "TRANSACTION_FEE_BUY", "transaction_fee_model_id": "3ae9403c-1611-46eb-84ee-e06a02bcfd08" } ], "cancellation_reason": "CANCELLED_BY_CLIENT", "cancellation_details": "User requested cancellation" }, "webhook_id": "cd2e4183-4e62-4e0f-981b-44b594d14610" } }, "portfolio": { "summary": "portfolio", "value": { "id": "54b8d84f-5bd0-4e43-bf0f-164388cb4c23", "created_at": "2023-07-21T10:00:00.00Z", "type": "SAVINGS_PLAN.CREATED", "object": { "id": "fc34d28e-38f5-49d2-92f6-82acb79098f4", "created_at": "2023-07-21T14:10:00.00Z", "updated_at": "2023-07-21T15:10:00.00Z", "user_id": "4b9732bd-7496-4913-8a5f-6360479d7fed", "account_id": "00ef0be8-d564-43af-b3c7-11b7a2188030", "name": "Portfolio savings plan", "type": "PORTFOLIO", "cash_amount": "100.00", "currency": "EUR", "start_date": "2023-07-24", "period": "WEEK", "interval": 1, "status": "ACTIVE", "cancellation_reason": "CANCELLED_BY_CLIENT", "cancellation_details": "User requested cancellation" }, "webhook_id": "cd2e4183-4e62-4e0f-981b-44b594d14610" } } } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Account valuation events": { "post": { "operationId": "account_valuation_event", "summary": "Account valuation events", "description": "Account valuation events", "tags": [ "Valuations" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Account Valuation - Callback", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type", "enum": [ "ACCOUNT_VALUATION.CREATED" ] }, "object": { "title": "Account Valuation", "type": "object", "properties": { "id": { "title": "Account valuation unique identifier", "description": "Account valuation unique identifier.", "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "total_security_value": { "title": "Total security value", "description": "Entity representing the monetary value by amount and currency.", "type": "object", "properties": { "amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] } }, "required": [ "amount", "currency" ], "additionalProperties": false }, "price_quality": { "type": "string", "description": "The requested price quality.\n* EOD - End of day prices\n* HIGHEST_AVAILABLE - The most recent available prices", "enum": [ "EOD", "HIGHEST_AVAILABLE" ] }, "security_positions": { "type": "array", "description": "Positions associated with this account valuation.", "items": { "title": "Account valuation security position", "type": "object", "properties": { "instrument": { "title": "Instrument", "description": "Entity representing the financial instrument.", "type": "object", "properties": { "uuid": { "description": "String representing the instrument internal identifier.", "type": "string", "format": "uuid" }, "isin": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" } }, "required": [ "uuid" ], "additionalProperties": false }, "quantity": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,10})?$" }, { "description": "Total quantity of the instrument (10 decimal places)." } ] }, "value": { "nullable": true, "allOf": [ { "title": "Security position value", "description": "Entity representing the monetary value by amount and currency, and the time of the price used.", "type": "object", "properties": { "amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "price_time": { "type": "string", "format": "date-time", "description": "The date and time of the price used for the calculation. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" } }, "required": [ "amount", "currency", "price_time" ], "additionalProperties": false }, { "nullable": true } ] }, "weight": { "description": "Total weight of the instrument (10 decimal places).", "oneOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,10})?$" }, { "type": "null" } ] }, "price_quality": { "type": "string", "description": "The price quality used for the calculation of the value of the position.\n* EOD - end of day price\n* REALTIME - realtime price\n* DELAYED - delayed price\n* NA - no available price", "enum": [ "EOD", "REALTIME", "DELAYED", "NA" ] } }, "required": [ "instrument", "quantity", "value", "weight" ], "additionalProperties": false } }, "valuation_time": { "type": "string", "format": "date-time", "description": "Date and time as of which the value was calculated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" } }, "required": [ "id", "account_id", "created_at", "updated_at", "valuation_time", "total_security_value", "price_quality", "security_positions" ], "additionalProperties": false }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "example": { "id": "8962b496-8d42-4560-bfab-10490dd1a721", "created_at": "2023-01-10T00:15:32Z", "type": "ACCOUNT_VALUATION.CREATED", "object": { "id": "404b170a-9042-11ed-9a51-2eabd0c03f8a", "created_at": "2023-01-10T00:15:22Z", "updated_at": "2023-01-10T00:15:22Z", "valuation_time": "2023-01-10T00:15:22Z", "account_id": "51cdc0cc-9042-11ed-b017-2eabd0c03f8a", "price_quality": "EOD", "total_security_value": { "amount": "142.29", "currency": "EUR" }, "security_positions": [ { "instrument": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "isin": "DE0007664005" }, "value": { "amount": "104.81", "currency": "EUR", "price_time": "2023-01-09T09:20:00Z" }, "quantity": "0.65", "weight": "0.736595" }, { "instrument": { "uuid": "48b798b7-3a62-4f30-8307-ee94d35b21b7", "isin": "FR0010524777" }, "value": { "amount": "37.48", "currency": "EUR", "price_time": "2023-01-09T09:20:00Z" }, "quantity": "1.00", "weight": "0.263405" } ] }, "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6" } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Intraday account valuation events": { "post": { "operationId": "intraday_account_valuation_event", "summary": "Intraday account valuation events", "description": "Intraday account valuation events", "tags": [ "Valuations" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Intraday Account Valuation - Callback", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type", "enum": [ "INTRADAY_ACCOUNT_VALUATION.CREATED" ] }, "object": { "title": "Account Valuation", "type": "object", "properties": { "id": { "title": "Account valuation unique identifier", "description": "Account valuation unique identifier.", "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "total_security_value": { "title": "Total security value", "description": "Entity representing the monetary value by amount and currency.", "type": "object", "properties": { "amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] } }, "required": [ "amount", "currency" ], "additionalProperties": false }, "price_quality": { "type": "string", "description": "The requested price quality.\n* EOD - End of day prices\n* HIGHEST_AVAILABLE - The most recent available prices", "enum": [ "EOD", "HIGHEST_AVAILABLE" ] }, "security_positions": { "type": "array", "description": "Positions associated with this account valuation.", "items": { "title": "Account valuation security position", "type": "object", "properties": { "instrument": { "title": "Instrument", "description": "Entity representing the financial instrument.", "type": "object", "properties": { "uuid": { "description": "String representing the instrument internal identifier.", "type": "string", "format": "uuid" }, "isin": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" } }, "required": [ "uuid" ], "additionalProperties": false }, "quantity": { "allOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,10})?$" }, { "description": "Total quantity of the instrument (10 decimal places)." } ] }, "value": { "nullable": true, "allOf": [ { "title": "Security position value", "description": "Entity representing the monetary value by amount and currency, and the time of the price used.", "type": "object", "properties": { "amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "price_time": { "type": "string", "format": "date-time", "description": "The date and time of the price used for the calculation. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" } }, "required": [ "amount", "currency", "price_time" ], "additionalProperties": false }, { "nullable": true } ] }, "weight": { "description": "Total weight of the instrument (10 decimal places).", "oneOf": [ { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,10})?$" }, { "type": "null" } ] }, "price_quality": { "type": "string", "description": "The price quality used for the calculation of the value of the position.\n* EOD - end of day price\n* REALTIME - realtime price\n* DELAYED - delayed price\n* NA - no available price", "enum": [ "EOD", "REALTIME", "DELAYED", "NA" ] } }, "required": [ "instrument", "quantity", "value", "weight" ], "additionalProperties": false } }, "valuation_time": { "type": "string", "format": "date-time", "description": "Date and time as of which the value was calculated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" } }, "required": [ "id", "account_id", "created_at", "updated_at", "valuation_time", "total_security_value", "price_quality", "security_positions" ], "additionalProperties": false }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "example": { "id": "8962b496-8d42-4560-bfab-10490dd1a722", "created_at": "2023-01-10T14:15:32Z", "type": "INTRADAY_ACCOUNT_VALUATION.CREATED", "object": { "id": "404b170a-9042-11ed-9a51-2eabd0c03f8b", "created_at": "2023-01-10T14:15:22Z", "updated_at": "2023-01-10T14:15:22Z", "valuation_time": "2023-01-10T14:15:22Z", "account_id": "51cdc0cc-9042-11ed-b017-2eabd0c03f8a", "price_quality": "EOD", "total_security_value": { "amount": "142.29", "currency": "EUR" }, "security_positions": [ { "instrument": { "uuid": "123e4567-e89b-12d3-a456-426614174000", "isin": "DE0007664005" }, "value": { "amount": "104.81", "currency": "EUR", "price_time": "2023-01-09T09:20:00Z" }, "quantity": "0.65", "weight": "0.736595" }, { "instrument": { "uuid": "48b798b7-3a62-4f30-8307-ee94d35b21b7", "isin": "FR0010524777" }, "value": { "amount": "37.48", "currency": "EUR", "price_time": "2023-01-09T09:20:00Z" }, "quantity": "1.00", "weight": "0.263405" } ] }, "webhook_id": "9df39835-be87-4243-9018-f2500b39cee7" } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Account liquidation events": { "post": { "operationId": "account_liquidation_event", "summary": "Account liquidation events", "description": "Fires when an account liquidation changes status (`ACCOUNT_LIQUIDATION.NEW`, `ACCOUNT_LIQUIDATION.PROCESSING`, `ACCOUNT_LIQUIDATION.FILLED`, `ACCOUNT_LIQUIDATION.CANCELLED`, `ACCOUNT_LIQUIDATION.SETTLED`).", "tags": [ "Liquidations" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Accounts - Callback", "type": "object", "description": "Webhook callback payload for account liquidation lifecycle events (`ACCOUNT_LIQUIDATION.NEW`, `ACCOUNT_LIQUIDATION.PROCESSING`, `ACCOUNT_LIQUIDATION.FILLED`, `ACCOUNT_LIQUIDATION.CANCELLED`, `ACCOUNT_LIQUIDATION.SETTLED`).", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type", "enum": [ "ACCOUNT_LIQUIDATION.NEW", "ACCOUNT_LIQUIDATION.PROCESSING", "ACCOUNT_LIQUIDATION.FILLED", "ACCOUNT_LIQUIDATION.CANCELLED", "ACCOUNT_LIQUIDATION.SETTLED" ] }, "object": { "title": "Account liquidation", "type": "object", "description": "Represents an account liquidation — a request to sell all investment positions in an account and convert the proceeds to cash. Contains references to each individual sell order.", "properties": { "id": { "title": "Account liquidation unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of an account liquidation.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "user_id": { "description": "ID of the user who owns the account. Exactly one of user_id or business_id will be set; the other will be null.", "oneOf": [ { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" }, { "type": "null" } ] }, "business_id": { "description": "ID of the business that owns the account. Exactly one of user_id or business_id will be set; the other will be null.", "oneOf": [ { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" }, { "type": "null" } ] }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "cash_amount": { "type": "string", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - British Pound", "enum": [ "EUR", "GBP" ] }, "status": { "type": "string", "description": "Execution status of the Account liquidation.\n* NEW - \n* PROCESSING - \n* FILLED - \n* CANCELLED - \n* SETTLED - ", "enum": [ "NEW", "PROCESSING", "FILLED", "CANCELLED", "SETTLED" ] }, "orders": { "type": "array", "description": "Position liquidation orders associated with this account liquidation", "items": { "title": "Account liquidation", "type": "object", "description": "An individual sell order within an account liquidation, corresponding to the sale of a single position held in the account.", "properties": { "id": { "title": "Account liquidation order unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of an account liquidation order.", "format": "uuid" }, "side": { "type": "string", "description": "Side of the order.\n* SELL - ", "default": "SELL" }, "status": { "type": "string", "description": "Execution status of the Account liquidation order.\n* NEW - \n* PROCESSING - \n* FILLED - \n* CANCELLED - ", "enum": [ "NEW", "PROCESSING", "FILLED", "CANCELLED" ] } }, "required": [ "id", "side", "status" ], "additionalProperties": false } }, "fee_collection_id": { "description": "Identifier of the fee collection associated with this liquidation. Null when no fee applies. See the Fees API to retrieve fee details.", "oneOf": [ { "type": "null" }, { "title": "Fee collection unique identifier.", "type": "string", "description": "Fee collection unique identifier.", "format": "uuid" } ] } }, "required": [ "id", "created_at", "updated_at", "account_id", "cash_amount", "currency", "status", "orders", "fee_collection_id" ], "additionalProperties": false }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "example": { "id": "56510309-d9de-4730-9b5b-4a0ed047f3a9", "created_at": "2021-07-21T14:10:00.00Z", "type": "ACCOUNT_LIQUIDATION.NEW", "object": { "id": "b2f541dc-a27b-4d5a-b970-41812b0892b9", "created_at": "2021-07-21T14:10:00.000Z", "updated_at": "2021-07-21T14:10:00.000Z", "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3", "user_id": "81dfb00e-9be6-4617-8994-dfd0407f34df", "cash_amount": "1000", "currency": "EUR", "status": "NEW", "orders": [], "fee_collection_id": null }, "webhook_id": "b838bde5-b6df-4f1f-bfc4-71d3fb01d430" } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Account returns events": { "post": { "operationId": "account_returns_event", "summary": "Account returns event", "description": "Account returns event", "tags": [ "Returns" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Account Returns - Callback", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type", "enum": [ "ACCOUNT_RETURNS.CREATED" ], "default": "ACCOUNT_RETURNS.CREATED" }, "object": { "title": "Account Returns", "type": "object", "properties": { "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "date": { "type": "string", "format": "date-time", "description": "Date when returns were calculated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "twr": { "title": "", "type": "object", "properties": { "daily": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "cumulative": { "type": "string", "pattern": "^-?[0-9]{0,63}(\\.[0-9]{1,27})?$" }, "cumulative_start_date": { "type": "string", "format": "date-time", "description": "Date when the cumulative time-weighted returns calculation starts." } } } }, "required": [ "account_id", "date", "twr" ], "additionalProperties": false }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "example": { "id": "399dc0a7-f4cb-42a4-9513-496df030381e", "created_at": "2023-09-02T05:15:00Z", "type": "ACCOUNT_RETURNS.CREATED", "object": { "account_id": "bbe9e784-e009-4cb6-a07c-24831897327b", "date": "2023-09-01", "twr": { "daily": "0.0132434142", "cumulative": "0.0324353234", "cumulative_start_date": "2023-08-01" } }, "webhook_id": "435719ac-c064-4c7a-a8b9-6db9446965de" } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Virtual cash increase events": { "post": { "operationId": "virtual_cash_increase_event", "summary": "Virtual cash increase events", "description": "Virtual cash increase events", "tags": [ "Virtual Cash Balances" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Virtual Cash Balance - Virtual Cash Increase - Callback", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type", "enum": [ "VIRTUAL_CASH_INCREASE.ISSUED", "VIRTUAL_CASH_INCREASE.CONFIRMED", "VIRTUAL_CASH_INCREASE.CANCELLED" ] }, "object": { "title": "Virtual Cash Balance - Virtual Cash Increase", "type": "object", "additionalProperties": false, "properties": { "id": { "title": "Virtual cash unique identifier", "type": "string", "description": "Virtual cash unique identifier", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling\n* USD - The United States dollar", "enum": [ "EUR", "GBP", "USD" ] }, "status": { "type": "string", "description": "Status of the virtual cash\n* ISSUED - Virtual cash increase is created.\n* CONFIRMED - Virtual cash increase was successfully processed.\n* CANCELLED - Virtual cash increase was cancelled.", "enum": [ "ISSUED", "CONFIRMED", "CANCELLED" ] } }, "required": [ "id", "account_group_id", "amount", "currency", "status", "created_at", "updated_at" ] }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "example": { "id": "8962b496-8d42-4560-bfab-10490dd1a721", "created_at": "2021-07-21T14:10:00.00Z", "type": "VIRTUAL_CASH_INCREASE.ISSUED", "object": { "id": "6ffa6b16-2380-4e7a-88b2-ae625c8eef99", "created_at": "2020-08-24T14:15:22Z", "updated_at": "2020-08-24T14:15:22Z", "account_group_id": "ac1c39e9-2101-46b8-a624-d10a9e351b6c", "amount": "200.00", "currency": "EUR", "status": "ISSUED" }, "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6" } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Virtual cash decrease events": { "post": { "operationId": "virtual_cash_decrease_event", "summary": "Virtual cash decrease events", "description": "Virtual cash decrease events", "tags": [ "Virtual Cash Balances" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Virtual Cash Balance - Virtual Cash Decrease - Callback", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type", "enum": [ "VIRTUAL_CASH_DECREASE.ISSUED", "VIRTUAL_CASH_DECREASE.CONFIRMED", "VIRTUAL_CASH_DECREASE.QUEUED", "VIRTUAL_CASH_DECREASE.CANCELLED" ] }, "object": { "title": "Virtual Cash Balance - Virtual Cash Decrease", "type": "object", "additionalProperties": false, "properties": { "id": { "title": "Virtual cash unique identifier", "type": "string", "description": "Virtual cash unique identifier", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling\n* USD - The United States dollar", "enum": [ "EUR", "GBP", "USD" ] }, "status": { "type": "string", "description": "Status of the virtual cash\n* ISSUED - Virtual cash decrease is created.\n* CONFIRMED - Virtual cash decrease was successfully processed.\n* QUEUED - Virtual cash decrease was queued.\n* CANCELLED - Virtual cash decrease was cancelled.", "enum": [ "ISSUED", "CONFIRMED", "QUEUED", "CANCELLED" ] } }, "required": [ "id", "account_group_id", "amount", "currency", "status", "created_at", "updated_at" ] }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "example": { "id": "8962b496-8d42-4560-bfab-10490dd1a721", "created_at": "2021-07-21T14:10:00.00Z", "type": "VIRTUAL_CASH_DECREASE.ISSUED", "object": { "id": "6ffa6b16-2380-4e7a-88b2-ae625c8eef99", "created_at": "2020-08-24T14:15:22Z", "updated_at": "2020-08-24T14:15:22Z", "account_group_id": "ac1c39e9-2101-46b8-a624-d10a9e351b6c", "amount": "200.00", "currency": "EUR", "status": "ISSUED" }, "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6" } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Fee collection events": { "post": { "operationId": "fee_collection_event", "summary": "Fee collection events", "description": "Fee collection events", "tags": [ "Fees" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Fee Collection - Callback", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type", "enum": [ "FEE_COLLECTION.CREATED", "FEE_COLLECTION.FINALISED", "FEE_COLLECTION.CANCELLED" ] }, "object": { "title": "Fee Collection", "type": "object", "properties": { "id": { "title": "Fee collection unique identifier.", "type": "string", "description": "Fee collection unique identifier.", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "account_group_id": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" }, "type": { "type": "string", "description": "Type of the fee collection\n* SERVICE_FEE - Service fee intake in a pre-defined cadence (e.g. monthly)\n* SERVICE_FEE_LIQUIDATION - Service fee intake as a result of a Portfolio liquidation", "enum": [ "SERVICE_FEE", "SERVICE_FEE_LIQUIDATION" ] }, "collection_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "processed_amount": { "type": "object", "properties": { "cash_balance": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "sell_to_cover": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "total_residual_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" } } }, "sell_to_cover_orders": { "type": "array", "items": { "title": "Sell to cover order details", "type": "object", "properties": { "id": { "title": "Sell to cover order id used to cover fee amount.", "type": "string", "description": "Sell to cover order id used to cover fee amount.", "format": "uuid" }, "residual_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" } }, "required": [ "id", "residual_amount" ], "additionalProperties": false } }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "status": { "type": "string", "description": "Status of the fee collection\n* PROCESSING - Fee collection is in progress.\n* FINALISED - Fees have been collected from the account and the funds has been transferred to the client.\n* CANCELLED - Fee collection has been cancelled.", "enum": [ "PROCESSING", "FINALISED", "CANCELLED" ] }, "period_start": { "type": "string", "format": "date", "description": "Start date of the fee collection period in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339" }, "period_end": { "type": "string", "format": "date", "description": "End date of the fee collection period in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339" }, "calculation_breakdown": { "type": "array", "description": "Breakdown of the fee collection by fee model and subperiod. Populated only for fee collections created from daily fee model calculations.", "items": { "title": "Fee Calculation Breakdown Item", "type": "object", "properties": { "fee_model_id": { "title": "Fee model unique identifier.", "type": "string", "description": "Fee model unique identifier.", "format": "uuid" }, "subperiod_start": { "type": "string", "format": "date", "description": "Start date of the fee subperiod in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339" }, "subperiod_end": { "type": "string", "format": "date", "description": "End date of the fee subperiod in YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339" }, "subtotal_amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" }, "components": { "type": "array", "description": "Individual fee components contributing to the subtotal.", "items": { "title": "Fee Breakdown Component", "type": "object", "properties": { "type": { "type": "string", "description": "Type of the fee component\n* TRANSACTION_LUMP_SUM - Lump sum transaction fee\n* PLATFORM - Platform fee\n* SERVICE - Service fee (client portfolio)\n* VAT - Value-added tax", "enum": [ "TRANSACTION_LUMP_SUM", "PLATFORM", "SERVICE", "VAT" ] }, "amount": { "type": "string", "pattern": "^[0-9]{1,9}(\\.[0-9]{2})?$" } }, "required": [ "type", "amount" ], "additionalProperties": false } } }, "required": [ "fee_model_id", "subperiod_start", "subperiod_end", "subtotal_amount", "components" ], "additionalProperties": false } }, "replaced_collection_id": { "title": "Fee collection unique identifier.", "type": "string", "description": "Fee collection unique identifier.", "format": "uuid" } }, "required": [ "id", "account_id", "account_group_id", "type", "collection_amount", "processed_amount", "currency", "status", "period_start", "period_end", "created_at", "updated_at" ], "additionalProperties": false }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "examples": { "CREATED": { "summary": "CREATED", "value": { "id": "38fc59d0-fc42-46ef-9512-824773219b2e", "created_at": "2023-08-19T13:06:57.820371265Z", "type": "FEE_COLLECTION.CREATED", "webhook_id": "1b097e06-8a14-4181-b72a-de0972a3c57b", "object": { "account_group_id": "999f7566-2ca3-4007-b99d-e501be8c7222", "account_id": "689f7566-2ca3-4007-b99d-e501be8c7783", "collection_amount": "12.41", "created_at": "2022-11-30T14:16:22Z", "currency": "EUR", "id": "d77e6924-9bb7-4db0-addc-404442258f4b", "period_start": "2022-11-01", "period_end": "2022-11-30", "processed_amount": { "cash_balance": "0", "sell_to_cover": "0" }, "status": "PROCESSING", "type": "SERVICE_FEE", "updated_at": "2022-11-30T14:16:22Z" } } }, "FINALISED": { "summary": "FINALISED", "value": { "id": "38fc59d0-fc42-46ef-9512-824773219b2e", "created_at": "2023-08-19T13:06:57.820371265Z", "type": "FEE_COLLECTION.FINALISED", "webhook_id": "1b097e06-8a14-4181-b72a-de0972a3c57b", "object": { "account_group_id": "999f7566-2ca3-4007-b99d-e501be8c7222", "account_id": "689f7566-2ca3-4007-b99d-e501be8c7783", "collection_amount": "12.41", "created_at": "2022-11-30T14:16:22Z", "currency": "EUR", "id": "d77e6924-9bb7-4db0-addc-404442258f4b", "period_start": "2022-11-01", "period_end": "2022-11-30", "processed_amount": { "cash_balance": "0", "sell_to_cover": "0", "total_residual_amount": "0.12" }, "sell_to_cover_orders": [ { "id": "1d0e329b-9c01-4dde-9883-5638d6319925", "residual_amount": "0.00" }, { "id": "8317dc2a-4073-437b-b27d-2c52f1e4c8b2", "residual_amount": "0.12" } ], "calculation_breakdown": [ { "fee_model_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "subperiod_start": "2022-11-01", "subperiod_end": "2022-11-30", "subtotal_amount": "12.41", "components": [ { "type": "SERVICE", "amount": "10.00" }, { "type": "PLATFORM", "amount": "2.41" } ] } ], "status": "FINALISED", "type": "SERVICE_FEE", "updated_at": "2022-11-30T14:16:22Z" } } } } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } }, "Corporate Action Events": { "post": { "operationId": "corporate_action_event", "summary": "Corporate Action Events", "description": "Notifies tenants of corporate actions impacting securities holdings across \nall accounts within the organization. This webhook sends updates for dividends, \nstock splits, mergers, tender offers, and other events affecting positions at \nthe organizational level.\n", "tags": [ "Corporate Actions" ], "requestBody": { "content": { "application/json": { "schema": { "title": "Webhook - Corporate Action Notification", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event unique identifier" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)" }, "type": { "type": "string", "description": "Event type", "enum": [ "CORPORATE_ACTION.UPDATED" ] }, "object": { "title": "Corporate Action", "description": "Object representing corporate action and its related processing status", "type": "object", "additionalProperties": false, "properties": { "id": { "title": "Corporate action unique identifier.", "type": "string", "description": "Unique internal identifier assigned to a corporate action by Upvest.", "format": "uuid" }, "corporate_action_reference": { "title": "Corporate action reference", "description": "Reference assigned by the account servicer to unambiguously identify a corporate action event.", "type": "string" }, "instrument": { "title": "Instrument", "description": "Entity representing the financial instrument.", "type": "object", "properties": { "uuid": { "description": "Unique internal identifier assigned to an instrument by Upvest.", "type": "string", "format": "uuid" }, "isin": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, "name": { "description": "Name of the instrument.", "type": "string" } } }, "iso_type": { "title": "ISO type of corporate action", "description": "The identifier of a corporate action type [ISO Code](https://www.iso20022.org/15022/uhb/mt564-5-field-22f.htm)", "pattern": "^[A-Z]{4}$", "type": "string" }, "name": { "description": "Name of the corporate action type", "type": "string" }, "currency_denomination": { "title": "Currency Of Denomination", "description": "Currency in which a financial instrument is currently denominated. [ISO](https://www.iso20022.org/15022/uhb/mt564-24-field-11a.htm).", "type": "string", "enum": [ "UNSPECIFIED", "EUR", "USD", "GBP", "SEK", "JPY", "CHF", "CNY", "AUD", "CAD", "HKD", "NOK", "NZD", "AED", "AFN", "ALL", "AMD", "ARS", "AZN", "BAM", "BDT", "BGN", "BHD", "BND", "BOB", "BRL", "BYR", "BZD", "CLP", "COP", "CRC", "CSD", "CZK", "DKK", "DOP", "DZD", "EEK", "EGP", "ETB", "GEL", "GTQ", "HNL", "HRK", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD", "KES", "KGS", "KHR", "KRW", "KWD", "KZT", "LAK", "LBP", "LKR", "LTL", "LVL", "LYD", "MAD", "MKD", "MNT", "MOP", "MVR", "MXN", "MYR", "NIO", "NPR", "OMR", "PAB", "PEN", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SGD", "SYP", "THB", "TJS", "TMT", "TND", "TRY", "TTD", "TWD", "UAH", "UYU", "UZS", "VEF", "VND", "XOF", "YER", "ZAR", "ZWL" ], "default": "UNSPECIFIED" }, "mandatory_voluntary_indicator": { "title": "Mandatory-Voluntary indicator", "description": "Indicates whether a corporate action is mandatory, voluntary or choosable.", "type": "string", "enum": [ "UNSPECIFIED", "MANDATORY", "VOLUNTARY", "CHOOSABLE" ], "default": "UNSPECIFIED" }, "announcement_status": { "title": "Announcement status", "description": "Indicates the completeness of the announcement of a corporate action [ISO](https://www.iso20022.org/15022/uhb/mt564-7-field-25d.htm).", "type": "string", "enum": [ "UNSPECIFIED", "COMPLETE", "COMPLETE_UNCONFIRMED", "WITH_ENTITLEMENT", "PRELIMINARY_ANNOUNCEMENT_CONFIRMED", "PRELIMINARY_ANNOUNCEMENT_UNCONFIRMED" ], "default": "UNSPECIFIED" }, "function_of_message": { "title": "Function of message", "description": "The function of the message is specified in this field. More details under [ISO definitions](https://www.iso20022.org/15022/uhb/mt564-4-field-23g.htm).", "type": "string", "enum": [ "UNSPECIFIED", "ADDITIONAL_BUSINESS_PROCESS", "CANCELLATION_ADVICE", "NEW", "ELIGIBLE_BALANCE_NOTIFICATION", "REPLACEMENT", "REMINDER", "WITHDRAWAL" ], "default": "UNSPECIFIED" }, "announcement_date": { "title": "Announcement date", "description": "Date on which a company announces a corporate event. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)", "type": "string", "format": "date" }, "ex_date": { "title": "Ex-Date", "description": "The date up to which a particular share is eligible for the upcoming corporate action. If buyers purchase a share on the ex-date, they are not entitled to participate in the upcoming corporate action; but the seller still would be. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)", "type": "string", "format": "date" }, "record_date": { "title": "Record date", "description": "Date on which the issuer reviews its records to determine its authorised shareholders. The authorised shareholders are those who are affected by the respective corporate action. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)", "type": "string", "format": "date" }, "buyer_protection_deadline": { "title": "Buyer protection deadline", "description": "Deadline by which an entitled holder needs to advise their counterparty to a transaction of their election for a corporate action event, also known as Election to Counterparty Market Deadline. Only shown if known. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)", "type": "string", "format": "date-time" }, "effective_date": { "title": "Effective date", "description": "Date at which an event is officially effective from the issuer's perspective (e.g. merger closes, stock split is applied, name change or de-listing becomes effective). Typically present for events that have no ex-date. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)", "type": "string", "format": "date" }, "nominal_coupon_rate": { "title": "Nominal coupon rate", "description": "The bond's fixed annual interest rate (coupon), as a percentage. For example, \"2.5\" means 2.5%. Present only for interest payments on bonds (when iso_type is INTR).", "type": "string" }, "options": { "type": "array", "items": { "title": "Option", "description": "Corporate action option.", "type": "object", "properties": { "option_number": { "description": "Number to identify the available options for corporate actions.", "type": "string" }, "option_type": { "title": "Option type", "description": "Type of option based on [ISO CAOP](https://www.iso20022.org/15022/uhb/mt564-57-field-22f.htm).", "type": "string", "enum": [ "UNSPECIFIED", "ABSTAIN", "VOTE_AGAINST_MANAGEMENT", "BENEFICIAL_OWNER_BREAKDOWN_REQUEST", "BONUS_SHARE_PLAN", "BUY_UP", "CASH_AND_SECURITIES", "CASH", "CONSENT_AND_EXCHANGE", "CONSENT_DENIED", "CONSENT_GRANTED", "CONSENT_AND_TENDER", "EXERCISE", "LAPSE", "VOTE_WITH_MANAGEMENT", "RETAIN", "NO_ACTION", "NON_QUALIFIED_INVESTOR", "PROPOSED_RATE", "OTHER", "OVERSUBSCRIBE", "PROXY_CARD", "UNKNOWN_PROCEEDS", "QUALIFIED_INVESTOR", "SECURITIES_OPTION", "SELL_ENTITLEMENT", "SPLIT_INSTRUCTION" ], "default": "UNSPECIFIED" }, "option_details": { "title": "Option Details", "description": "Details of the corporate action option.", "type": "object", "properties": { "default_option": { "description": "Indicates whether the option is the default option.", "type": "string", "enum": [ "TRUE", "FALSE" ] }, "market_deadline": { "title": "Market deadline", "description": "Issuer or issuer's agent deadline to respond, including an election instruction to an outstanding offer or privilege. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)", "type": "string", "format": "date" }, "client_deadline": { "title": "Client deadline", "description": "Client deadline to respond to an outstanding offer or privilege. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)", "type": "string", "format": "date" }, "action_period_start": { "description": "Start of the period during which the specified option, or all options of the event, remains valid, for example, offer period.", "type": "string", "format": "date" }, "action_period_end": { "description": "End of the period during which the specified option, or all options of the event, remains valid, for example, offer period.", "type": "string", "format": "date" }, "minimum_quantity": { "description": "Minimum quantity of financial instrument that can be instructed.", "type": "string" }, "minimum_multiple_quantity": { "description": "Minimum of multiple financial instruments that can be instructed.", "type": "string" } } }, "movements": { "type": "array", "items": { "title": "Movement", "description": "Movement information for corporate action option.", "type": "object", "properties": { "movement_type": { "title": "Movement type", "description": "Type of the movement.", "type": "string", "enum": [ "UNSPECIFIED", "CASH", "SECURITIES_OPTION" ], "default": "UNSPECIFIED" }, "movement_details": { "title": "Movement details", "description": "Details of the movement.", "type": "object", "properties": { "credit_debit_factor": { "description": "Indicates whether the movement is a credit or a debit. DEPRECATED: Use credit_debit_indicator instead.", "type": "string", "enum": [ "UNSPECIFIED", "CREDIT", "DEBIT" ], "default": "UNSPECIFIED", "deprecated": true }, "credit_debit_indicator": { "description": "Indicates whether the movement is a credit or a debit.", "type": "string", "enum": [ "UNSPECIFIED", "CREDIT", "DEBIT" ], "default": "UNSPECIFIED" }, "instrument": { "title": "Instrument", "description": "Entity representing the financial instrument.", "type": "object", "properties": { "uuid": { "description": "Unique internal identifier assigned to an instrument by Upvest.", "type": "string", "format": "uuid" }, "isin": { "title": "International securities identification number", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).", "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, "name": { "description": "Name of the instrument.", "type": "string" } } }, "ratio": { "title": "Ratio", "description": "The ratio is the numerical comparison between instruments and can be calculated in two different ways: \n* ADEX = Additional for Existing Securities. Example: You hold 10 units and the ratio is 1/5. 40 additional units are added. \n* NEWO = New to Old. Example: You hold 1000 units and the ratio is 3/11. 1000 old units are removed and 3666.6 are added.", "type": "object", "properties": { "debit_factor": { "description": "Amount to be decreased.", "type": "string" }, "credit_factor": { "description": "Amount to be increased.", "type": "string" } } }, "payment_date": { "title": "Payment date", "description": "Date on which the movement is due to take place (cash and/or securities). [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)", "type": "string", "format": "date" }, "value_date": { "title": "Value date", "description": "Date when calculating economic benefit for a cash amount (cash movements only). [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)", "type": "string", "format": "date" }, "gross_dividend": { "description": "String value, which represents a monetary amount. Amount of the cash dividend per equity before deductions or allowances.", "type": "string" }, "offer_price_received": { "description": "String value that represents a monetary amount. Generic cash price that the holder of the underlying security receives per product.", "type": "string" }, "withholding_tax": { "title": "Withholding Tax rate", "description": "Withholding tax rate.", "type": "string" }, "actual_payment_rate": { "title": "Actual payment rate", "description": "The gross interest rate applied to this payment, as a percentage. For example, \"2.5\" means 2.5%. Present only on cash movements for interest payments (when iso_type is INTR).", "type": "string" }, "currency": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling", "enum": [ "EUR", "GBP" ] }, "rounding_indicator": { "title": "Indicator for the rounding approach for the disposition of fractions.", "type": "string", "description": "Indicator for the rounding approach for the disposition of fractions.\n* UNSPECIFIED - The characteristics of the disposition of fractions are not specified.\n* BUYU - Buy securities up to the next whole number.\n* CINL - Receive cash instead of fractions.\n* DIST - Accept distribution of fractions in the form of securities.\n* RDDN - Rounds down the entitlement to the last full unit/minimum nominal quantity, fractions are discarded.\n* RDUP - Round up to the next full unit/minimum nominal quantity at no cost.\n* STAN - If the fraction is greater than or equal to 0.5 of the resulting security, round up, otherwise round down as specified in the respective RDUP and RDDN codes.\n* UKWN - The characteristics of the disposition of fractions are unknown. DEPRECATED: Use UNSPECIFIED instead.", "enum": [ "UNSPECIFIED", "BUYU", "CINL", "DIST", "RDDN", "RDUP", "STAN", "UKWN" ], "default": "UNSPECIFIED" } } } } }, "minItems": 1, "description": "Movements in corporate action option." } } }, "minItems": 1, "description": "Available corporate action options." }, "additional_text": { "title": "Additional text", "description": "Provides additional information or specifies in more detail the content of a message.", "type": "string" }, "website_address": { "title": "Website address", "description": "Provides the web address published for the event, if present.", "type": "string" }, "name_change": { "title": "Name change", "description": "Provides the new name of a company following a name change (when iso_type is CHAN).", "type": "string" } }, "required": [ "id", "corporate_action_reference", "iso_type", "instrument" ] }, "webhook_id": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "required": [ "id", "created_at", "type", "object", "webhook_id" ], "additionalProperties": false }, "example": { "id": "d0cb44d6-d61f-4272-b0f5-a8c7349b8b9a", "created_at": "2024-09-05T12:03:43.201937702Z", "type": "CORPORATE_ACTION.UPDATED", "object": { "id": "b96b1ee7-d491-43eb-b5e4-4833af9c9c2f", "corporate_action_reference": "DEDVCA0000000000", "instrument": { "uuid": "48b798b7-3a62-4f30-8307-ee94d35b21b7", "isin": "FR0010524777", "name": "Lyxor MSCI New Energy ESG Filtered (DR) ETF" }, "name": "CASH_DIVIDEND", "iso_type": "DVCA", "currency_denomination": "EUR", "mandatory_voluntary_indicator": "MANDATORY", "announcement_status": "PRELIMINARY_ANNOUNCEMENT_CONFIRMED", "function_of_message": "NEW", "announcement_date": "2023-11-09", "ex_date": "2023-12-04", "record_date": "2023-12-05", "effective_date": "2023-12-10", "options": [ { "option_number": "001", "option_type": "CASH", "option_details": { "default_option": "TRUE" }, "movements": [ { "movement_type": "CASH", "movement_details": { "credit_debit_indicator": "CREDIT", "payment_date": "2023-12-10", "gross_dividend": "0.54", "withholding_tax": "0.30", "currency": "EUR" } } ] } ] }, "webhook_id": "dbebe0ac-a407-4d43-a404-b8fe846eb691" } } } }, "responses": { "200": { "description": "Request has been processed successfully." } } } } }, "components": { "securitySchemes": { "oauth-client-credentials": { "type": "oauth2", "flows": { "clientCredentials": { "tokenUrl": "https://sandbox.upvest.co/auth/token", "scopes": { "accounts:read": "Read accounts and account groups", "accounts:admin": "Create/update/delete accounts and account groups", "webhooks:admin": "Create/update/delete webhooks", "webhooks:read": "Read webhooks", "files:read": "Read files metadata", "orders:admin": "Create/update/delete orders", "orders:read": "Read orders", "users:admin": "Create/update/delete users", "users:read": "Read users", "checks:admin": "Create checks", "checks:read": "Read checks", "positions:read": "Read positions", "positions_performance:read": "Read positions performance", "reference_accounts:admin": "Create/update/delete reference accounts", "reference_accounts:read": "Read reference accounts", "mandates:admin": "Create/update/delete mandates", "mandates:read": "Read mandates", "payments:admin": "Payins and withdrawal operations", "payments:read": "Payins and withdrawal read operations", "topups:admin": "Top-ups operations", "topups:read": "Top-ups read operations", "cash_balance_transfers:admin": "Cash balance transfer operations", "cash_balance_transfers:read": "Cash balance transfer read operations", "credit_fundings:read": "Credit Fundings read operations", "securities_transfers:read": "Securities Transfers read transfers", "securities_transfers:admin": "Securities Transfers operations", "isa_transfers:admin": "ISA Transfers operations", "reports:read": "Read reports", "reports:admin": "Create reports", "taxes:read": "Read tax residencies", "taxes:admin": "Modify tax residencies and tax exemptions", "transactions:read": "Read cash and securities transactions", "instruments:read": "Read instruments", "fees:admin": "Create and read fee operations", "fees:read": "Read fee operations", "transaction_fees:admin": "Create and read transaction fee operations", "transaction_fees:read": "Read transaction fee operations", "portfolios:read": "Read portfolios", "portfolios:admin": "Modify portfolios", "valuations:read": "Read valuations", "account_liquidations:read": "Read accounts liquidations", "account_liquidations:admin": "Trigger/read/cancel accounts liquidations", "account_returns:read": "Read accounts returns", "virtual_cash_balances:admin": "Virtual cash balances", "savings_plans:read": "Read savings plans", "savings_plans:admin": "Create/read savings plans", "prices:read": "Read instrument prices,", "tests:admin": "Testing related operations", "account_transfers:read": "Account Transfers read transfers", "account_transfers:admin": "Account Transfers operations", "businesses:admin": "Create/update/delete businesses,", "businesses:read": "Read businesses,", "roles:admin": "Create/update/deactivate roles", "roles:read": "Read roles", "corporate_actions:admin": "Create/update/delete corporate action instructions" } } } } }, "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "parameters": { "apiVersion": { "name": "upvest-api-version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ], "default": "1", "example": "1" }, "description": "Upvest API version (Note: Do not include quotation marks)" }, "authorization": { "name": "Authorization", "in": "header", "description": "Bearer (access) token from the OAuth flow with correct scopes.\nhttps://datatracker.ietf.org/doc/html/rfc6750\n", "required": true, "schema": { "type": "string", "pattern": "^Bearer [a-zA-Z0-9\\-\\._~+/]*=*", "example": "Bearer c2VjcmV0Cg==" } }, "clientID": { "name": "upvest-client-id", "in": "header", "description": "Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).", "required": true, "schema": { "type": "string", "format": "uuid", "example": "363f3305-7ab0-4e82-a158-f9d382ad08b6" } }, "signature": { "name": "signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header" }, "signatureInput": { "name": "signature-input", "in": "header", "required": true, "schema": { "type": "string" }, "description": "https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he" }, "idempotencyKey": { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$", "example": "ccb07f42-4104-44ad-8e1f-c660bb7b269c" }, "description": "A UUID to be used as an idempotency key. This prevents a duplicate request from being replayed.\nhttps://docs.upvest.co/documentation/concepts/api_concepts/idempotency\n" }, "limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 100, "minimum": 1, "maximum": 1000 }, "allowEmptyValue": true, "description": "Use the `limit` argument to specify the maximum number of items returned." }, "offset": { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "format": "int32" }, "allowEmptyValue": true, "description": "Use the `offset` argument to specify where in the list of results to start when returning items for a particular query." }, "order": { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order." }, "order_asc": { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC" ], "default": "ASC" }, "description": "Sort order of the result list if the `sort` parameter is specified. By default, only ASC for ascending sort." }, "folder": { "name": "folder", "in": "path", "description": "Folder containing the file. Must match the pattern `^[a-z0-9-_\\.]{1,32}$`.", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-_\\.]{1,32}$", "example": "booking_references" } }, "fileName": { "name": "file_name", "in": "path", "description": "Name of the file to retrieve. Must match the pattern `^[a-z0-9-_\\.]{1,255}$`.", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-_\\.]{1,255}$", "example": "list.txt" } }, "webhookID": { "name": "webhook_id", "in": "path", "description": "The unique identifier of the webhook subscription. Universally Unique Identifier (UUID).", "required": true, "schema": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, "userID": { "name": "user_id", "in": "path", "required": true, "description": "The unique identifier of the user. Universally Unique Identifier (UUID).", "schema": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" } }, "businessID": { "name": "business_id", "in": "path", "required": true, "description": "The unique identifier of the business. Universally Unique Identifier (UUID).", "schema": { "type": "string", "description": "Unique identifier for the business.", "format": "uuid" } }, "roleID": { "name": "role_id", "in": "path", "required": true, "description": "The unique identifier of the role. Universally Unique Identifier (UUID).", "schema": { "type": "string", "description": "Unique identifier for the role.", "format": "uuid" } }, "userIDOptional": { "name": "user_id", "in": "query", "required": false, "description": "Filters results by user ID. Universally Unique Identifier (UUID).", "schema": { "title": "User unique identifier.", "type": "string", "description": "Unique identifier of the user, as a UUID.", "format": "uuid" } }, "entityIDOptional": { "name": "entity_id", "in": "query", "required": false, "description": "Filters results by entity ID. Universally Unique Identifier (UUID).", "schema": { "title": "Entity unique identifier.", "type": "string", "description": "Unique identifier of the entity a role is attached to.", "format": "uuid" } }, "identifierID": { "name": "identifier_id", "in": "path", "required": true, "description": "The unique identifier of the user identifier document. Universally Unique Identifier (UUID).", "schema": { "title": "Unique identifier for the user's national ID.", "type": "string", "description": "Unique identifier of the user identifier resource, as a UUID.", "format": "uuid" } }, "feeCollectionID": { "name": "fee_collection_id", "in": "path", "required": true, "description": "The unique identifier of the fee collection. Universally Unique Identifier (UUID).", "schema": { "title": "Fee collection unique identifier.", "type": "string", "description": "Fee collection unique identifier.", "format": "uuid" } }, "accountID": { "name": "account_id", "in": "path", "required": true, "description": "The unique identifier of the account. Universally Unique Identifier (UUID).", "schema": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" } }, "accountGroupID": { "name": "account_group_id", "in": "path", "required": true, "description": "The unique identifier of the account group. Universally Unique Identifier (UUID).", "schema": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } }, "accountGroupIDOptional": { "name": "account_group_id", "in": "query", "required": false, "description": "Filters results by account group ID. Universally Unique Identifier (UUID).", "schema": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } }, "accountIDOptional": { "name": "account_id", "in": "query", "required": false, "description": "Filters results by account ID. Universally Unique Identifier (UUID).", "schema": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" } }, "dateCreatedFrom": { "name": "date_created_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "title": "Date in YYYY-MM-DD format. RFC 3339, section 5.6" }, "description": "Filters results to those created at or after this timestamp. [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) date-time format (e.g. `2024-01-01`).", "example": "2022-10-14T10:10:10Z" }, "dateCreatedTo": { "name": "date_created_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "title": "Date in YYYY-MM-DD format. RFC 3339, section 5.6" }, "description": "Filters results to those created at or before this timestamp. [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) date-time format (e.g. `2024-12-31T23:59:59Z`).", "example": "2022-10-14T10:10:10Z" }, "status": { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "NEW", "PROCESSING", "FILLED", "CANCELLED" ], "default": "FILLED" }, "description": "The execution status of the order.\n* NEW - \n* PROCESSING - \n* FILLED - \n* CANCELLED - " }, "securitiesTransferStatusOptional": { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "NEW", "PROCESSING", "CLIENT_RESOLUTION_REQUIRED", "CANCELLED", "SETTLED" ] }, "description": "Status of the securities transfer \n* NEW - Securities transfer is created but not started processing. \n* PROCESSING - Securities transfer is in processing. \n* SETTLED - Securities transfer was successfully settled. \n* CANCELLED - Securities transfer was cancelled. \n* CLIENT_RESOLUTION_REQUIRED - Securities transfer requires client resolution" }, "securitiesTransferStatusFilter": { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "NEW", "PROCESSING", "CANCELLED", "SETTLED" ] }, "description": "Status of the securities transfer \n* NEW - Securities transfer is created but not started processing. \n* PROCESSING - Securities transfer is in processing. \n* SETTLED - Securities transfer was successfully settled. \n* CANCELLED - Securities transfer was cancelled." }, "referenceAccountID": { "name": "reference_account_id", "in": "path", "required": true, "description": "The unique identifier of the reference (external bank) account. Universally Unique Identifier (UUID).", "schema": { "title": "Reference account unique identifier.", "type": "string", "description": "Reference account unique identifier.", "format": "uuid" } }, "mandateID": { "name": "mandate_id", "in": "path", "required": true, "description": "The unique identifier of the direct debit mandate. Universally Unique Identifier (UUID).", "schema": { "title": "Direct Debit Mandate unique identifier.", "type": "string", "description": "Direct Debit Mandate unique identifier.", "format": "uuid" } }, "directDebitID": { "name": "direct_debit_id", "in": "path", "required": true, "description": "The unique identifier of the direct debit. Universally Unique Identifier (UUID).", "schema": { "title": "Direct debit funding request unique identifier", "type": "string", "description": "Direct debit funding request unique identifier", "format": "uuid" } }, "topupID": { "name": "topup_id", "in": "path", "required": true, "description": "The unique identifier of the top-up. Universally Unique Identifier (UUID).", "schema": { "title": "Top up request unique identifier.", "type": "string", "description": "Top up request unique identifier.", "format": "uuid" } }, "creditFundingID": { "name": "credit_funding_id", "in": "path", "required": true, "description": "The unique identifier of the credit funding. Universally Unique Identifier (UUID).", "schema": { "title": "Credit Funding request unique identifier", "type": "string", "description": "Credit Funding request unique identifier", "format": "uuid" } }, "virtualBankAccountID": { "name": "virtual_bank_account_id", "in": "path", "required": true, "description": "The unique identifier of the virtual bank account. Universally Unique Identifier (UUID).", "schema": { "title": "Virtual bank account request unique identifier.", "type": "string", "description": "Virtual bank account request unique identifier.", "format": "uuid" } }, "checkID": { "name": "check_id", "in": "path", "required": true, "description": "The unique identifier of the user check. Universally Unique Identifier (UUID).", "schema": { "title": "User Check unique identifier", "type": "string", "description": "User Check unique identifier.", "format": "uuid" } }, "instrumentID": { "name": "instrument_id", "in": "path", "required": true, "description": "The unique identifier of the instrument, provided as either an `isin:` URN or a `uuid:` URN.", "schema": { "title": "Instrument unique identifier", "description": "Instrument unique identifier.", "oneOf": [ { "title": "International securities identification number with 'isin:' URN namespace", "type": "string", "description": "International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number), prefixed with a 'isin:' [URN scheme](https://datatracker.ietf.org/doc/html/rfc8141).", "pattern": "^(urn:)?isin:[A-Z]{2}[A-Z0-9]{9}[0-9]$" }, { "title": "Universally Unique IDentifier (UUID) with 'uuid:' URN scheme", "type": "string", "description": "Universally Unique IDentifier (UUID) with 'uuid:' URN namespace, defined by [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122).", "pattern": "^(urn:)?uuid:[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-5][0-9a-fA-F]{3}-?[089abAB][0-9a-fA-F]{3}-?[0-9a-fA-F]{12}$" } ] } }, "preorderID": { "name": "preorder_id", "description": "The unique identifier of the preorder. Universally Unique Identifier (UUID).", "in": "path", "required": true, "schema": { "title": "Preorder unique identifier", "type": "string", "format": "uuid", "description": "The ID of the preorder" } }, "orderID": { "name": "order_id", "description": "The unique identifier of the order. Universally Unique Identifier (UUID).", "in": "path", "required": true, "schema": { "title": "Order unique identifier", "type": "string", "description": "Unique identifier for an order. Universally Unique Identifier (UUID).", "format": "uuid" } }, "executionID": { "name": "execution_id", "description": "The unique identifier of the order execution. Universally Unique Identifier (UUID).", "in": "path", "required": true, "schema": { "title": "Order execution unique identifier", "type": "string", "description": "Unique identifier for an order execution. Universally Unique Identifier (UUID).", "format": "uuid" } }, "reportID": { "name": "report_id", "in": "path", "required": true, "description": "The unique identifier of the report. Universally Unique Identifier (UUID).", "schema": { "title": "Report unique identifier.", "type": "string", "description": "Report unique identifier.", "format": "uuid" } }, "withdrawalID": { "name": "withdrawal_id", "in": "path", "required": true, "description": "The unique identifier of the cash withdrawal. Universally Unique Identifier (UUID).", "schema": { "title": "Cash withdrawal unique identifier", "type": "string", "description": "Cash withdrawal unique identifier", "format": "uuid" } }, "cashBalanceTransferID": { "name": "cash_balance_transfer_id", "in": "path", "required": true, "description": "The unique identifier of the cash balance transfer. Universally Unique Identifier (UUID).", "schema": { "title": "Cash balance transfer unique identifier", "type": "string", "description": "Cash balance transfer unique identifier", "format": "uuid" } }, "allocationID": { "name": "allocation_id", "in": "path", "required": true, "description": "The unique identifier of the portfolio allocation. Universally Unique Identifier (UUID).", "schema": { "title": "Portfolio allocation unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio allocation.", "format": "uuid" } }, "portfolioExecutionID": { "name": "portfolio_execution_id", "in": "path", "required": true, "description": "The unique identifier of the portfolio rebalancing execution. Universally Unique Identifier (UUID).", "schema": { "title": "Portfolio rebalancing execution unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio rebalancing execution.", "format": "uuid" } }, "portfolioOrderID": { "name": "portfolio_order_id", "in": "path", "required": true, "description": "The unique identifier of the portfolio order. Universally Unique Identifier (UUID).", "schema": { "title": "Portfolios order unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a portfolio order.", "format": "uuid" } }, "accountLiquidationID": { "name": "account_liquidation_id", "in": "path", "required": true, "description": "The unique identifier of the account liquidation. Universally Unique Identifier (UUID).", "schema": { "title": "Account liquidation unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of an account liquidation.", "format": "uuid" } }, "virtualCashDecreaseID": { "name": "virtual_cash_decrease_id", "in": "path", "required": true, "description": "The unique identifier of the virtual cash decrease. Universally Unique Identifier (UUID).", "schema": { "title": "Virtual cash unique identifier", "type": "string", "description": "Virtual cash unique identifier", "format": "uuid" } }, "savingsPlanID": { "name": "savings_plan_id", "in": "path", "required": true, "description": "The unique identifier of the savings plan. Universally Unique Identifier (UUID).", "schema": { "title": "Savings plan unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a savings plan.", "format": "uuid" } }, "savingsPlanExecutionID": { "name": "savings_plan_execution_id", "in": "path", "required": true, "description": "The unique identifier of the savings plan execution. Universally Unique Identifier (UUID).", "schema": { "title": "Savings plan execution unique identifier", "type": "string", "description": "Universally Unique Identifier (UUID) of a savings plan execution.", "format": "uuid" } }, "venueID": { "name": "venue_id", "in": "path", "required": true, "description": "The unique identifier of the trading venue. Universally Unique Identifier (UUID).", "schema": { "title": "Venue unique identifier.", "type": "string", "description": "Venue unique identifier.", "format": "uuid" } }, "currency": { "name": "currency", "in": "path", "required": true, "description": "The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) alphabetic currency code identifying the cash balance (e.g. `EUR`).", "schema": { "type": "string", "description": "Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.\n* EUR - Euro\n* GBP - Pound Sterling\n* USD - The United States dollar", "enum": [ "EUR", "GBP", "USD" ] } }, "taxExemptionID": { "name": "tax_exemption_id", "description": "The unique identifier of the tax exemption. Universally Unique Identifier (UUID).", "in": "path", "required": true, "schema": { "title": "Tax Exemption Unique Identifier", "type": "string", "description": "Tax Exemption Unique Identifier", "format": "uuid" } }, "taxWrapperID": { "name": "tax_wrapper_id", "description": "The unique identifier of the tax wrapper. Universally Unique Identifier (UUID).", "in": "path", "required": true, "schema": { "title": "Tax Wrapper Unique Identifier", "type": "string", "description": "Tax wrapper unique identifier", "format": "uuid" } }, "bonusPermissionID": { "name": "permission_id", "description": "Bonus permission unique identifier.", "in": "path", "required": true, "schema": { "title": "Bonus Permission Unique Identifier", "type": "string", "description": "Bonus permission unique identifier", "format": "uuid" } }, "productConfigurationID": { "name": "product_configuration_id", "description": "Product configuration unique identifier.", "in": "path", "required": true, "schema": { "title": "Product Configuration Unique Identifier", "type": "string", "description": "Product configuration unique identifier.", "format": "uuid" } }, "pensionDeTransferID": { "name": "transfer_id", "description": "Pension transfer unique identifier.", "in": "path", "required": true, "schema": { "title": "Pension transfer unique identifier.", "type": "string", "description": "Pension transfer unique identifier.", "format": "uuid" } }, "securitiesTransferID": { "name": "securities_transfer_id", "in": "path", "required": true, "description": "The unique identifier of the securities transfer. Universally Unique Identifier (UUID).", "schema": { "title": "Securities transfer request unique identifier.", "type": "string", "description": "Securities transfer request unique identifier.", "format": "uuid" } }, "accountTransferID": { "name": "account_transfer_id", "in": "path", "required": true, "description": "The unique identifier of the account transfer. Universally Unique Identifier (UUID).", "schema": { "title": "Account transfer request unique identifier.", "type": "string", "description": "Account transfer request unique identifier.", "format": "uuid" } }, "transactionFeeModelID": { "name": "transaction_fee_model_id", "in": "path", "description": "The unique identifier of the transaction fee model. Universally Unique Identifier (UUID).", "required": true, "schema": { "title": "Fee model unique identifier.", "type": "string", "description": "Universally Unique Identifier (UUID) of the transaction fee model.", "format": "uuid" } } }, "responses": { "WebhookNoContentResponse": { "description": "Request has been processed successfully." }, "ResponseNoContent": { "description": "Request has been processed successfully.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } } }, "ResponseAccepted": { "description": "The request has been successfully accepted and will be processed asynchronously.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } } }, "ResponseSingleError": { "description": "Shared error response to be used for all errors returned from the API.\n\nWe follow the generic parts of RFC 7807 \"Problem Details for HTTP APIs\"\nhttps://datatracker.ietf.org/doc/html/rfc7807", "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false } } } }, "ResponseError400": { "description": "Bad Request. The incoming request had a malformed parameter/object.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 400, "type": "bad_request" } } } }, "ResponseError401": { "description": "Unauthorized. The caller has not been authenticated.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 401, "type": "unauthorized" } } } }, "ResponseError403": { "description": "Forbidden. The caller has been authenticated but is not allowed to take the requested action.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 403, "type": "forbidden" } } } }, "ResponseError404": { "description": "Not Found. The requested resource could not be found.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 404, "type": "not_found" } } } }, "ResponseError405": { "description": "Method Not Allowed. The requested method is not allowed on the requested resource.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 405, "type": "method_not_allowed" } } } }, "ResponseError406": { "description": "Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. \"Accept\" header defined unsupported value.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 406, "type": "not_acceptable" } } } }, "ResponseError409": { "description": "Conflict. An operation is not available for the current state of the resource.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 409, "type": "conflict" } } } }, "ResponseError422": { "description": "Unprocessable Entity. The syntax of request is correct but server can't process it due a semantic error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 422, "type": "unprocessable_entity" } } } }, "ResponseError429": { "description": "Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 429, "type": "too_many_requests" } } } }, "ResponseError500": { "description": "Internal Server Error. The service encountered an unexpected error.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 500, "type": "internal_server_error" } } } }, "ResponseError503": { "description": "Service Unavailable. The service handling for this request cannot be reached at this time.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 503, "type": "method_not_allowed" } } } }, "ResponseError504": { "description": "Gateway Timeout. The service gateway has reached its internal timeout.", "headers": { "upvest-request-id": { "required": true, "schema": { "type": "string", "format": "uuid", "example": "169ae4c7-ebd7-4041-94da-25369653eba7" } } }, "content": { "application/problem+json": { "schema": { "title": "Error", "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "URL to a document describing the error condition." }, "status": { "type": "integer", "description": "Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers." }, "title": { "type": "string", "description": "A short, human-readable title for the general error type; the title should not change for given types." }, "detail": { "type": "string", "description": "A human-readable description of the specific error." }, "instance": { "type": "string", "description": "This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response." }, "request_id": { "type": "string", "description": "Correlation ID for the original request." } }, "required": [ "type", "status" ], "additionalProperties": false }, "example": { "status": 504, "type": "gateway_timeout" } } } } } } }