{ "openapi": "3.0.3", "info": { "title": "Upvest Investment API", "version": "1.99.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": "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", "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": "Tenant Client ID", "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": 86400, "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": "Tenant Client ID", "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": "Files folder name", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-_\\.]{1,32}$", "example": "booking_references" } }, { "name": "file_name", "in": "path", "description": "Filename", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-_\\.]{1,255}$", "example": "list.txt" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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": "Tenant Client ID", "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", "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": [ "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", "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": [ "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", "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": [ "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": "Webhook identifier", "required": true, "schema": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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", "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": [ "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", "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": [ "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", "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": [ "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": "Webhook identifier", "required": true, "schema": { "title": "Webhook ID", "type": "string", "description": "Webhook unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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": "Tenant Client ID", "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 the list of all users.", "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": "", "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": { "oneOf": [ { "anyOf": [ { "title": "Users (BYOL) - List", "type": "array", "minItems": 1, "items": { "title": "User (BYOL)", "type": "object", "properties": { "id": { "title": "User unique identifier.", "type": "string", "description": "User 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)" }, "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." }, "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" ] }, "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" } }, "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", "properties": { "id": { "title": "User unique identifier.", "type": "string", "description": "User 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)" }, "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." }, "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", "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" } }, "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", "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" }, "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", "salutation": "SALUTATION_MALE", "title": "PROF_DR", "birth_date": "1970-10-01", "birth_city": "Berlin", "birth_country": "DE", "birth_name": "Schmidt", "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" } ] } }, "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", "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", "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", "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", "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", "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", "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.", "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", "anyOf": [ { "title": "User (BYOL) - Create - Request", "type": "object", "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." }, "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" } }, "required": [ "first_name", "last_name", "birth_date", "nationalities", "address" ], "additionalProperties": false }, { "title": "User (TOL) - Create - Request", "type": "object", "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", "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" } }, "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", "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" } } }, "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" } } }, "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", "anyOf": [ { "title": "User (BYOL)", "type": "object", "properties": { "id": { "title": "User unique identifier.", "type": "string", "description": "User 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)" }, "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." }, "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" ] }, "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" } }, "required": [ "id", "created_at", "updated_at", "first_name", "last_name", "birth_date", "nationalities", "address", "status" ], "additionalProperties": false }, { "title": "User (TOL)", "type": "object", "properties": { "id": { "title": "User unique identifier.", "type": "string", "description": "User 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)" }, "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." }, "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", "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" } }, "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", "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" }, "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", "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", "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", "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", "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, "schema": { "title": "User unique identifier.", "type": "string", "description": "User unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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 specified by ID.", "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", "anyOf": [ { "title": "User (BYOL)", "type": "object", "properties": { "id": { "title": "User unique identifier.", "type": "string", "description": "User 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)" }, "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." }, "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" ] }, "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" } }, "required": [ "id", "created_at", "updated_at", "first_name", "last_name", "birth_date", "nationalities", "address", "status" ], "additionalProperties": false }, { "title": "User (TOL)", "type": "object", "properties": { "id": { "title": "User unique identifier.", "type": "string", "description": "User 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)" }, "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." }, "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", "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" } }, "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", "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" }, "status": "ACTIVE" } }, "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", "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", "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 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", "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", "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, "schema": { "title": "User unique identifier.", "type": "string", "description": "User unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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", "anyOf": [ { "title": "User (BYOL) - Data Change Request", "type": "object", "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": "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" } }, "minProperties": 1, "additionalProperties": false }, { "title": "User (TOL) - Data Change Request", "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" } }, "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", "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" } } } } } }, "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, "schema": { "title": "User unique identifier.", "type": "string", "description": "User unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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" ] } ], "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": "", "properties": { "data": { "type": "array", "items": { "title": "User Check", "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": "User unique identifier.", "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)", "enum": [ "VIDEO_ID", "IN_PERSON_ID", "ELECTRONIC_ID", "LIVENESS_PHOTO_ID", "QUALIFIED_ELECTRONIC_SIGNATURE_WITH_TX", "TWO_PLUS_TWO_VERIFICATION" ] }, "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": "User unique identifier.", "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": "User unique identifier.", "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", "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": "Compliance 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": "User unique identifier.", "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": "User unique identifier.", "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" } ] } } } }, "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", "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)", "enum": [ "VIDEO_ID", "IN_PERSON_ID", "ELECTRONIC_ID", "LIVENESS_PHOTO_ID", "QUALIFIED_ELECTRONIC_SIGNATURE_WITH_TX", "TWO_PLUS_TWO_VERIFICATION" ] }, "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", "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 } ] }, "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" } } } } } }, "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", "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, "schema": { "title": "User unique identifier.", "type": "string", "description": "User unique identifier.", "format": "uuid" } }, { "name": "check_id", "in": "path", "required": true, "schema": { "title": "User Check unique identifier", "type": "string", "description": "User Check unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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", "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": "User unique identifier.", "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)", "enum": [ "VIDEO_ID", "IN_PERSON_ID", "ELECTRONIC_ID", "LIVENESS_PHOTO_ID", "QUALIFIED_ELECTRONIC_SIGNATURE_WITH_TX", "TWO_PLUS_TWO_VERIFICATION" ] }, "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": "User unique identifier.", "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": "User unique identifier.", "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", "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": "Compliance 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": "User unique identifier.", "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": "User unique identifier.", "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" } } } } } }, "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, "schema": { "title": "User unique identifier.", "type": "string", "description": "User unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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", "properties": { "data": { "type": "array", "items": { "title": "Identifier", "type": "object", "properties": { "id": { "title": "Unique identifier for the user's national ID.", "type": "string", "description": "Unique identifier for the user's national ID.", "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": "User unique identifier.", "format": "uuid" }, "identifier_standard": { "type": "string", "maxLength": 6, "description": "Identifier standard abbreviation. If it's not provided, issuing country's corresponding 1st Priority Identifier Standard will be used by default. See [guide here](/documentation/guides/users/identifiers)" }, "identifier": { "type": "string", "maxLength": 30, "minLength": 0, "description": "Identifier value. See [guide here](/documentation/guides/users/identifiers)" }, "type": { "type": "string", "description": "Identifier type.\n* NATIONAL_ID - \n* PASSPORT - ", "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. More information can be found in the [guides](https://docs.upvest.co/documentation/guides/users/identifiers).", "tags": [ "User Identifiers" ], "security": [ { "oauth-client-credentials": [ "users:admin" ] } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Identifier - Create - Request", "type": "object", "properties": { "type": { "type": "string", "description": "Identifier type.\n* NATIONAL_ID - \n* PASSPORT - ", "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. See [guide here](/documentation/guides/users/identifiers)" }, "identifier_standard": { "type": "string", "maxLength": 6, "description": "Identifier standard abbreviation. If it's not provided, issuing country's corresponding 1st Priority Identifier Standard will be used by default. See [guide here](/documentation/guides/users/identifiers)" } }, "required": [ "type", "issuing_country", "identifier" ], "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" } } } } } }, "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", "properties": { "id": { "title": "Unique identifier for the user's national ID.", "type": "string", "description": "Unique identifier for the user's national ID.", "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": "User unique identifier.", "format": "uuid" }, "identifier_standard": { "type": "string", "maxLength": 6, "description": "Identifier standard abbreviation. If it's not provided, issuing country's corresponding 1st Priority Identifier Standard will be used by default. See [guide here](/documentation/guides/users/identifiers)" }, "identifier": { "type": "string", "maxLength": 30, "minLength": 0, "description": "Identifier value. See [guide here](/documentation/guides/users/identifiers)" }, "type": { "type": "string", "description": "Identifier type.\n* NATIONAL_ID - \n* PASSPORT - ", "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, "schema": { "title": "User unique identifier.", "type": "string", "description": "User unique identifier.", "format": "uuid" } }, { "name": "identifier_id", "in": "path", "required": true, "schema": { "title": "Unique identifier for the user's national ID.", "type": "string", "description": "Unique identifier for the user's national ID.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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", "properties": { "id": { "title": "Unique identifier for the user's national ID.", "type": "string", "description": "Unique identifier for the user's national ID.", "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": "User unique identifier.", "format": "uuid" }, "identifier_standard": { "type": "string", "maxLength": 6, "description": "Identifier standard abbreviation. If it's not provided, issuing country's corresponding 1st Priority Identifier Standard will be used by default. See [guide here](/documentation/guides/users/identifiers)" }, "identifier": { "type": "string", "maxLength": 30, "minLength": 0, "description": "Identifier value. See [guide here](/documentation/guides/users/identifiers)" }, "type": { "type": "string", "description": "Identifier type.\n* NATIONAL_ID - \n* PASSPORT - ", "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", "properties": { "identifier": { "type": "string", "maxLength": 30, "minLength": 0, "description": "Identifier value. See [guide here](/documentation/guides/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", "properties": { "id": { "title": "Unique identifier for the user's national ID.", "type": "string", "description": "Unique identifier for the user's national ID.", "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": "User unique identifier.", "format": "uuid" }, "identifier_standard": { "type": "string", "maxLength": 6, "description": "Identifier standard abbreviation. If it's not provided, issuing country's corresponding 1st Priority Identifier Standard will be used by default. See [guide here](/documentation/guides/users/identifiers)" }, "identifier": { "type": "string", "maxLength": 30, "minLength": 0, "description": "Identifier value. See [guide here](/documentation/guides/users/identifiers)" }, "type": { "type": "string", "description": "Identifier type.\n* NATIONAL_ID - \n* PASSPORT - ", "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, "schema": { "title": "User unique identifier.", "type": "string", "description": "User unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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", "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 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": "User unique identifier.", "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, "schema": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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": "User unique identifier.", "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, "schema": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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 - Great British Pound", "enum": [ "EUR", "GBP" ] }, "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, "schema": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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 - Great British Pound", "enum": [ "EUR", "GBP" ] }, "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": "0", "available_for_trading": "" } ] } } } }, "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, "schema": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } }, { "name": "currency", "in": "path", "required": true, "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 - Great British Pound", "enum": [ "EUR", "GBP" ] } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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 - Great British Pound", "enum": [ "EUR", "GBP" ] }, "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, "schema": { "title": "User unique identifier.", "type": "string", "description": "User unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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", "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", "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": "User unique identifier.", "format": "uuid" }, "type": { "type": "string", "description": "Relation type\n* OWNER - ", "enum": [ "OWNER" ], "default": "OWNER" } } } }, "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, "schema": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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": "User unique identifier.", "format": "uuid" }, "type": { "type": "string", "description": "Relation type\n* OWNER - ", "enum": [ "OWNER" ], "default": "OWNER" } } } }, "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": "User unique identifier.", "format": "uuid" }, "type": { "type": "string", "description": "Relation type\n* OWNER - ", "enum": [ "OWNER" ], "default": "OWNER" } } } }, "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, "schema": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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})?$" }, "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", "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", "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, "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, "schema": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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})?$" }, "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", "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", "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", "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", "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", "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, "schema": { "title": "User unique identifier.", "type": "string", "description": "User unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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", "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", "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": "User unique identifier.", "format": "uuid" }, "account_owner": { "type": "string", "maxLength": 140, "description": "First and last name of the reference account owner" }, "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", "user_id", "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": "Tenant Client ID", "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 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", "properties": { "user_id": { "title": "User unique identifier.", "type": "string", "description": "User unique identifier.", "format": "uuid" }, "account_owner": { "type": "string", "maxLength": 140, "description": "First and last name of the reference account owner" }, "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", "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" } } } } } }, "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", "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": "User unique identifier.", "format": "uuid" }, "account_owner": { "type": "string", "maxLength": 140, "description": "First and last name of the reference account owner" }, "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", "user_id", "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" } } } } } }, "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, "schema": { "title": "Reference account unique identifier.", "type": "string", "description": "Reference account unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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", "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": "User unique identifier.", "format": "uuid" }, "account_owner": { "type": "string", "maxLength": 140, "description": "First and last name of the reference account owner" }, "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", "user_id", "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, "schema": { "title": "User unique identifier.", "type": "string", "description": "User unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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": "List mandates", "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", "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", "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": "User unique identifier.", "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", "user_id", "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" } } } } } } }, "/payments/mandates": { "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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", "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", "properties": { "user_id": { "title": "User unique identifier.", "type": "string", "description": "User unique identifier.", "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 }, "example": { "user_id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be202", "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", "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": "User unique identifier.", "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", "user_id", "iban", "bic", "creditor_name", "creditor_id", "creditor_address", "type", "confirmed_at" ], "additionalProperties": false }, "example": { "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" } } } } } } }, "/payments/mandates/{mandate_id}": { "parameters": [ { "name": "mandate_id", "in": "path", "required": true, "schema": { "title": "Direct Debit Mandate unique identifier.", "type": "string", "description": "Direct Debit Mandate unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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", "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", "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": "User unique identifier.", "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", "user_id", "iban", "bic", "creditor_name", "creditor_id", "creditor_address", "type", "confirmed_at" ], "additionalProperties": false }, "example": { "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" } } } }, "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": "Delete mandate", "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, "schema": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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": "List direct debits", "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", "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": "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": { "title": "User unique identifier.", "type": "string", "description": "User unique identifier.", "format": "uuid" }, "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" ] }, "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", "user_id", "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": "Tenant Client ID", "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", "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", "properties": { "user_id": { "title": "User unique identifier.", "type": "string", "description": "User unique identifier.", "format": "uuid" }, "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": [ "user_id", "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", "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": { "title": "User unique identifier.", "type": "string", "description": "User unique identifier.", "format": "uuid" }, "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" ] }, "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", "user_id", "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, "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": "Tenant Client ID", "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": "Retrieve a direct debit", "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", "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": { "title": "User unique identifier.", "type": "string", "description": "User unique identifier.", "format": "uuid" }, "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" ] }, "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", "user_id", "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", "remittance_information": "payment for green energy portfolio", "status": "NEW", "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, "schema": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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", "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": "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": "Tenant Client ID", "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": "Triggers the creation of a top-up payment.", "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", "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", "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, "schema": { "title": "Top up request unique identifier.", "type": "string", "description": "Top up request unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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", "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, "schema": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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": "Retrieve funding details", "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", "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, "schema": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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": "List credit fundings", "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", "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": "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, "schema": { "title": "Credit Funding request unique identifier", "type": "string", "description": "Credit Funding request unique identifier", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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": "Retrieve a credit funding", "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", "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": "Tenant Client ID", "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", "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", "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": { "title": "User unique identifier.", "type": "string", "description": "User 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", "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 more](/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", "user_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", "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": { "title": "User unique identifier.", "type": "string", "description": "User 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", "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 more](/documentation/guides/payments/cash_balances/cash_withdrawal))." }, "taxes": { "type": "array", "items": { "title": "Tax", "type": "object", "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 processed.\n* CANCELLED - Withdrawal was cancelled.", "enum": [ "NEW", "PROCESSING", "CONFIRMED", "CANCELLED" ] }, "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", "user_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, "schema": { "title": "Cash withdrawal unique identifier", "type": "string", "description": "Cash withdrawal unique identifier", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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": "Retrieve withdrawal", "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", "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": { "title": "User unique identifier.", "type": "string", "description": "User 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", "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 more](/documentation/guides/payments/cash_balances/cash_withdrawal))." }, "taxes": { "type": "array", "items": { "title": "Tax", "type": "object", "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 processed.\n* CANCELLED - Withdrawal was cancelled.", "enum": [ "NEW", "PROCESSING", "CONFIRMED", "CANCELLED" ] }, "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", "user_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": "CONFIRMED", "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, "schema": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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": "List withdrawals", "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", "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", "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": { "title": "User unique identifier.", "type": "string", "description": "User 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", "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 more](/documentation/guides/payments/cash_balances/cash_withdrawal))." }, "taxes": { "type": "array", "items": { "title": "Tax", "type": "object", "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 processed.\n* CANCELLED - Withdrawal was cancelled.", "enum": [ "NEW", "PROCESSING", "CONFIRMED", "CANCELLED" ] }, "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", "user_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" } } } } } } }, "/account_groups/{account_group_id}/payments/virtual_bank_accounts": { "parameters": [ { "name": "account_group_id", "in": "path", "required": true, "schema": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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", "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": "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": "Tenant Client ID", "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": "Triggers the creation of a virtual bank 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", "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", "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, "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": "Tenant Client ID", "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", "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": "Tenant Client ID", "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": "User unique identifier.", "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": "User unique identifier.", "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": "User unique identifier.", "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": "Tenant Client ID", "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": "User unique identifier.", "format": "uuid" }, "type": { "type": "string", "description": "Relation type\n* OWNER - ", "enum": [ "OWNER" ], "default": "OWNER" } } } }, "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": "User 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": "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": "User unique identifier.", "format": "uuid" }, "type": { "type": "string", "description": "Relation type\n* OWNER - ", "enum": [ "OWNER" ], "default": "OWNER" } } } }, "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, "schema": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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 list of all orders for the account specified by its ID.", "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, "schema": { "title": "Account group unique identifier.", "type": "string", "description": "Account group unique identifier.", "format": "uuid" } }, { "name": "user_id", "in": "query", "required": false, "schema": { "title": "User unique identifier.", "type": "string", "description": "User unique identifier.", "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": "date range from", "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": "date range to", "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", "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", "properties": { "id": { "title": "Order 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)" }, "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", "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": "Type of the order.\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. 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", "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. [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 - \n* PROCESSING - \n* FILLED - \n* CANCELLED - ", "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. The field is present in case the Order has a status of CANCELLED.\n* CANCELLED_BY_CLIENT - \n* CANCELLED_BY_UPVEST_OPERATIONS - \n* CANCELLED_BY_TRADING_PARTNER - \n* CANCELLED_BY_UPVEST_PLATFORM - ", "enum": [ "CANCELLED_BY_CLIENT", "CANCELLED_BY_UPVEST_OPERATIONS", "CANCELLED_BY_TRADING_PARTNER", "CANCELLED_BY_UPVEST_PLATFORM" ] }, "initiation_flow": { "type": "string", "description": "Initiation flow used during order creation, i.e. what triggered the order.\n* API - \n* PORTFOLIO - \n* CASH_DIVIDEND_REINVESTMENT - \n* PORTFOLIO_REBALANCING - \n* SELL_TO_COVER_FEES - \n* SELL_TO_COVER_TAXES - \n* ACCOUNT_LIQUIDATION - \n* UPVEST_OPERATIONS - \n* SAVINGS_PLAN - ", "enum": [ "API", "PORTFOLIO", "CASH_DIVIDEND_REINVESTMENT", "PORTFOLIO_REBALANCING", "SELL_TO_COVER_FEES", "SELL_TO_COVER_TAXES", "ACCOUNT_LIQUIDATION", "UPVEST_OPERATIONS", "SAVINGS_PLAN" ] }, "execution_flow": { "type": "string", "description": "Execution flow that the order processing goes through. If no value is specified, the default value is assumed - `STRAIGHT_THROUGH`.\n* STRAIGHT_THROUGH - \n* BLOCK - ", "enum": [ "STRAIGHT_THROUGH", "BLOCK" ] }, "executions": { "type": "array", "description": "Order executions associated with this order", "items": { "title": "Order execution", "type": "object", "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", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,4})?$" }, "transaction_time": { "type": "string", "format": "date-time" }, "taxes": { "type": "array", "items": { "title": "Tax", "type": "object", "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", "format": "uuid" }, "status": { "type": "string", "description": "Execution status of the Execution.\n* FILLED - \n* SETTLED - \n* CANCELLED - ", "enum": [ "FILLED", "SETTLED", "CANCELLED" ] }, "side": { "type": "string", "description": "Side of the execution.\n* BUY - \n* SELL - ", "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", "enum": [ "EUR", "GBP" ] }, "settlement_date": { "allOf": [ { "title": "Settlement date", "type": "string", "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", "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 - ", "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", "enum": [ "EUR", "GBP" ] } }, "required": [ "type", "value_type", "charge_method", "cash_amount", "currency" ], "additionalProperties": false }, { "title": "Transaction Fee Model", "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 } ] } }, "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": "Tenant Client ID", "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": "List transaction fee models.", "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": "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": "Transaction Fee Models - 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 Configuration", "type": "object", "properties": { "id": { "title": "Fee model unique identifier.", "type": "string", "description": "Fee model 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)" }, "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 whether the fee will be charged by client or by other methods.\n* CHARGED_BY_CLIENT - ", "enum": [ "CHARGED_BY_CLIENT" ] }, "value_type": { "title": "Value Type", "type": "string", "description": "The value type of the transaction fee model.\n* ABSOLUTE - \n* RELATIVE - ", "enum": [ "ABSOLUTE", "RELATIVE" ] }, "application_type": { "title": "Application Type", "type": "string", "description": "The application type of the transaction fee model.\n* VOLUME - ", "enum": [ "VOLUME" ] }, "base_amount_scope": { "title": "Base Amount Scope", "type": "string", "description": "The base amount scope of the transaction fee model.\n* ORDER - ", "enum": [ "ORDER" ] }, "tiers": { "description": "The tiers of the transaction fee model.", "type": "array", "items": { "title": "Fee Tier", "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": "The unique identifier for the fee tier.", "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": "The unique identifier for the fee tier.", "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": "Create a transaction fee model.", "tags": [ "Transaction Fees Models" ], "security": [ { "oauth-client-credentials": [ "transaction_fees:admin" ] } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Fee configuration - Create - Request", "type": "object", "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 whether the fee will be charged by client or by other methods.\n* CHARGED_BY_CLIENT - ", "enum": [ "CHARGED_BY_CLIENT" ] }, "value_type": { "title": "Value Type", "type": "string", "description": "The value type of the transaction fee model.\n* ABSOLUTE - \n* RELATIVE - ", "enum": [ "ABSOLUTE", "RELATIVE" ] }, "application_type": { "title": "Application Type", "type": "string", "description": "The application type of the transaction fee model.\n* VOLUME - ", "enum": [ "VOLUME" ] }, "base_amount_scope": { "title": "Base Amount Scope", "type": "string", "description": "The base amount scope of the transaction fee model.\n* ORDER - ", "enum": [ "ORDER" ] }, "tiers": { "description": "The tiers of the transaction fee model.", "type": "array", "items": { "title": "Fee Tier", "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": "The unique identifier for the fee tier.", "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": "The unique identifier for the fee tier.", "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": "transaction fee buy - new year promotion", "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", "min_fee_amount": "5", "max_fee_amount": "15" }, { "tier_id": "1", "base_amount_from": "2000", "fee_bps": "200", "min_fee_amount": "15", "max_fee_amount": "100" }, { "tier_id": "2", "base_amount_from": "4000", "fee_bps": "300", "min_fee_amount": "100", "max_fee_amount": "200" } ] } } } } } }, "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": { "id": { "title": "Fee model unique identifier.", "type": "string", "description": "Fee model 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)" }, "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 whether the fee will be charged by client or by other methods.\n* CHARGED_BY_CLIENT - ", "enum": [ "CHARGED_BY_CLIENT" ] }, "value_type": { "title": "Value Type", "type": "string", "description": "The value type of the transaction fee model.\n* ABSOLUTE - \n* RELATIVE - ", "enum": [ "ABSOLUTE", "RELATIVE" ] }, "application_type": { "title": "Application Type", "type": "string", "description": "The application type of the transaction fee model.\n* VOLUME - ", "enum": [ "VOLUME" ] }, "base_amount_scope": { "title": "Base Amount Scope", "type": "string", "description": "The base amount scope of the transaction fee model.\n* ORDER - ", "enum": [ "ORDER" ] }, "tiers": { "description": "The tiers of the transaction fee model.", "type": "array", "items": { "title": "Fee Tier", "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": "The unique identifier for the fee tier.", "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": "The unique identifier for the fee tier.", "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": "transaction fee buy - new year promotion", "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", "min_fee_amount": "5", "max_fee_amount": "15" }, { "tier_id": "1", "base_amount_from": "2000", "fee_bps": "200", "min_fee_amount": "15", "max_fee_amount": "100" }, { "tier_id": "2", "base_amount_from": "4000", "fee_bps": "300", "min_fee_amount": "100", "max_fee_amount": "200" } ] } } } } } }, "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": "Transaction Fee Model ID", "required": true, "schema": { "title": "Fee model unique identifier.", "type": "string", "description": "Fee model unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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": "Get transaction fee model.", "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", "properties": { "id": { "title": "Fee model unique identifier.", "type": "string", "description": "Fee model 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)" }, "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 whether the fee will be charged by client or by other methods.\n* CHARGED_BY_CLIENT - ", "enum": [ "CHARGED_BY_CLIENT" ] }, "value_type": { "title": "Value Type", "type": "string", "description": "The value type of the transaction fee model.\n* ABSOLUTE - \n* RELATIVE - ", "enum": [ "ABSOLUTE", "RELATIVE" ] }, "application_type": { "title": "Application Type", "type": "string", "description": "The application type of the transaction fee model.\n* VOLUME - ", "enum": [ "VOLUME" ] }, "base_amount_scope": { "title": "Base Amount Scope", "type": "string", "description": "The base amount scope of the transaction fee model.\n* ORDER - ", "enum": [ "ORDER" ] }, "tiers": { "description": "The tiers of the transaction fee model.", "type": "array", "items": { "title": "Fee Tier", "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": "The unique identifier for the fee tier.", "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": "The unique identifier for the fee tier.", "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": "Tenant Client ID", "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, "schema": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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": "Tenant Client ID", "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 - Great British Pound", "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)", "enum": [ "TRANSACTION_LUMP_SUM", "PLATFORM", "SERVICE" ] }, "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 - Great British Pound", "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 - Great British Pound", "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)", "enum": [ "TRANSACTION_LUMP_SUM", "PLATFORM", "SERVICE" ] }, "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, "schema": { "title": "Fee collection unique identifier.", "type": "string", "description": "Fee collection unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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 - Great British Pound", "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)", "enum": [ "TRANSACTION_LUMP_SUM", "PLATFORM", "SERVICE" ] }, "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": "Tenant Client ID", "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": "User unique identifier.", "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": "", "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": "Tenant Client ID", "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": "User unique identifier.", "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": "User unique identifier.", "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, "schema": { "title": "User unique identifier.", "type": "string", "description": "User unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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": "User unique identifier.", "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": "Tenant Client ID", "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": "", "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": "Tenant Client ID", "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": "Tenant Client ID", "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, "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": "Tenant Client ID", "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, "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": "Tenant Client ID", "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, "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": "Tenant Client ID", "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, "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, "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": "Tenant Client ID", "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, "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": "Tenant Client ID", "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. After the creation request for the order is accepted, further processing takes place asynchronously.", "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", "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", "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": "Type of the order.\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. 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", "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. [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 that the order processing goes through. If no value is specified, the default value is assumed - `STRAIGHT_THROUGH`.\n* STRAIGHT_THROUGH - \n* BLOCK - ", "enum": [ "STRAIGHT_THROUGH", "BLOCK" ] }, "fee_configuration": { "type": "array", "description": "fee configuration", "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 - ", "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", "enum": [ "EUR", "GBP" ] } }, "required": [ "type", "value_type", "charge_method", "cash_amount", "currency" ], "additionalProperties": false }, { "title": "Transaction Fee Model", "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 } ] } }, "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", "properties": { "id": { "title": "Order 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)" }, "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", "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": "Type of the order.\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. 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", "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. [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 - \n* PROCESSING - \n* FILLED - \n* CANCELLED - ", "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. The field is present in case the Order has a status of CANCELLED.\n* CANCELLED_BY_CLIENT - \n* CANCELLED_BY_UPVEST_OPERATIONS - \n* CANCELLED_BY_TRADING_PARTNER - \n* CANCELLED_BY_UPVEST_PLATFORM - ", "enum": [ "CANCELLED_BY_CLIENT", "CANCELLED_BY_UPVEST_OPERATIONS", "CANCELLED_BY_TRADING_PARTNER", "CANCELLED_BY_UPVEST_PLATFORM" ] }, "initiation_flow": { "type": "string", "description": "Initiation flow used during order creation, i.e. what triggered the order.\n* API - \n* PORTFOLIO - \n* CASH_DIVIDEND_REINVESTMENT - \n* PORTFOLIO_REBALANCING - \n* SELL_TO_COVER_FEES - \n* SELL_TO_COVER_TAXES - \n* ACCOUNT_LIQUIDATION - \n* UPVEST_OPERATIONS - \n* SAVINGS_PLAN - ", "enum": [ "API", "PORTFOLIO", "CASH_DIVIDEND_REINVESTMENT", "PORTFOLIO_REBALANCING", "SELL_TO_COVER_FEES", "SELL_TO_COVER_TAXES", "ACCOUNT_LIQUIDATION", "UPVEST_OPERATIONS", "SAVINGS_PLAN" ] }, "execution_flow": { "type": "string", "description": "Execution flow that the order processing goes through. If no value is specified, the default value is assumed - `STRAIGHT_THROUGH`.\n* STRAIGHT_THROUGH - \n* BLOCK - ", "enum": [ "STRAIGHT_THROUGH", "BLOCK" ] }, "executions": { "type": "array", "description": "Order executions associated with this order", "items": { "title": "Order execution", "type": "object", "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", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,4})?$" }, "transaction_time": { "type": "string", "format": "date-time" }, "taxes": { "type": "array", "items": { "title": "Tax", "type": "object", "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", "format": "uuid" }, "status": { "type": "string", "description": "Execution status of the Execution.\n* FILLED - \n* SETTLED - \n* CANCELLED - ", "enum": [ "FILLED", "SETTLED", "CANCELLED" ] }, "side": { "type": "string", "description": "Side of the execution.\n* BUY - \n* SELL - ", "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", "enum": [ "EUR", "GBP" ] }, "settlement_date": { "allOf": [ { "title": "Settlement date", "type": "string", "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", "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 - ", "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", "enum": [ "EUR", "GBP" ] } }, "required": [ "type", "value_type", "charge_method", "cash_amount", "currency" ], "additionalProperties": false }, { "title": "Transaction Fee Model", "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 } ] } }, "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": "", "in": "path", "required": true, "schema": { "title": "Order unique identifier", "type": "string", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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.", "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", "properties": { "id": { "title": "Order 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)" }, "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", "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": "Type of the order.\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. 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", "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. [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 - \n* PROCESSING - \n* FILLED - \n* CANCELLED - ", "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. The field is present in case the Order has a status of CANCELLED.\n* CANCELLED_BY_CLIENT - \n* CANCELLED_BY_UPVEST_OPERATIONS - \n* CANCELLED_BY_TRADING_PARTNER - \n* CANCELLED_BY_UPVEST_PLATFORM - ", "enum": [ "CANCELLED_BY_CLIENT", "CANCELLED_BY_UPVEST_OPERATIONS", "CANCELLED_BY_TRADING_PARTNER", "CANCELLED_BY_UPVEST_PLATFORM" ] }, "initiation_flow": { "type": "string", "description": "Initiation flow used during order creation, i.e. what triggered the order.\n* API - \n* PORTFOLIO - \n* CASH_DIVIDEND_REINVESTMENT - \n* PORTFOLIO_REBALANCING - \n* SELL_TO_COVER_FEES - \n* SELL_TO_COVER_TAXES - \n* ACCOUNT_LIQUIDATION - \n* UPVEST_OPERATIONS - \n* SAVINGS_PLAN - ", "enum": [ "API", "PORTFOLIO", "CASH_DIVIDEND_REINVESTMENT", "PORTFOLIO_REBALANCING", "SELL_TO_COVER_FEES", "SELL_TO_COVER_TAXES", "ACCOUNT_LIQUIDATION", "UPVEST_OPERATIONS", "SAVINGS_PLAN" ] }, "execution_flow": { "type": "string", "description": "Execution flow that the order processing goes through. If no value is specified, the default value is assumed - `STRAIGHT_THROUGH`.\n* STRAIGHT_THROUGH - \n* BLOCK - ", "enum": [ "STRAIGHT_THROUGH", "BLOCK" ] }, "executions": { "type": "array", "description": "Order executions associated with this order", "items": { "title": "Order execution", "type": "object", "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", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,4})?$" }, "transaction_time": { "type": "string", "format": "date-time" }, "taxes": { "type": "array", "items": { "title": "Tax", "type": "object", "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", "format": "uuid" }, "status": { "type": "string", "description": "Execution status of the Execution.\n* FILLED - \n* SETTLED - \n* CANCELLED - ", "enum": [ "FILLED", "SETTLED", "CANCELLED" ] }, "side": { "type": "string", "description": "Side of the execution.\n* BUY - \n* SELL - ", "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", "enum": [ "EUR", "GBP" ] }, "settlement_date": { "allOf": [ { "title": "Settlement date", "type": "string", "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", "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 - ", "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", "enum": [ "EUR", "GBP" ] } }, "required": [ "type", "value_type", "charge_method", "cash_amount", "currency" ], "additionalProperties": false }, { "title": "Transaction Fee Model", "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 } ] } }, "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": "", "properties": { "id": { "title": "Order unique identifier", "type": "string", "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": "", "in": "path", "required": true, "schema": { "title": "Order execution unique identifier", "type": "string", "format": "uuid" } }, { "name": "order_id", "description": "", "in": "path", "required": true, "schema": { "title": "Order unique identifier", "type": "string", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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.", "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", "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", "pattern": "^[0-9]{0,63}(\\.[0-9]{1,4})?$" }, "transaction_time": { "type": "string", "format": "date-time" }, "taxes": { "type": "array", "items": { "title": "Tax", "type": "object", "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", "format": "uuid" }, "status": { "type": "string", "description": "Execution status of the Execution.\n* FILLED - \n* SETTLED - \n* CANCELLED - ", "enum": [ "FILLED", "SETTLED", "CANCELLED" ] }, "side": { "type": "string", "description": "Side of the execution.\n* BUY - \n* SELL - ", "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", "enum": [ "EUR", "GBP" ] }, "settlement_date": { "allOf": [ { "title": "Settlement date", "type": "string", "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, "schema": { "title": "User unique identifier.", "type": "string", "description": "User unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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_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_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* GENERIC_COMMUNICATION - Generic communication\n* INCOME_DISTRIBUTION - Income distribution report\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_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)\n* FRENCH_IFU - French tax statement (Imprimé fiscal unique)", "type": "string", "enum": [ "ACCOUNT_CLOSING", "ACCOUNT_OPENING", "AD_HOC_ACCOUNT_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", "GENERIC_COMMUNICATION", "INCOME_DISTRIBUTION", "MONTHLY_BILLING_STATEMENT", "QUARTERLY_ACCOUNT_STATEMENT", "REVOKED_ORDER", "SECURITIES_TRANSFER_INCOMING", "SECURITIES_TRANSFER_OUTGOING", "SELL_ORDER", "TAX_PAYMENT", "TAX_PREPAYMENT_DE", "TAX_PREPAYMENT_DE_CANCELLATION", "TAX_REFUND", "FRENCH_IFU" ] }, { "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": "Report", "anyOf": [ { "title": "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": "User unique identifier.", "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_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* GENERIC_COMMUNICATION - Generic communication\n* INCOME_DISTRIBUTION - Income distribution report\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_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)\n* FRENCH_IFU - French tax statement (Imprimé fiscal unique)", "type": "string", "enum": [ "ACCOUNT_CLOSING", "ACCOUNT_OPENING", "AD_HOC_ACCOUNT_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", "GENERIC_COMMUNICATION", "INCOME_DISTRIBUTION", "MONTHLY_BILLING_STATEMENT", "QUARTERLY_ACCOUNT_STATEMENT", "REVOKED_ORDER", "SECURITIES_TRANSFER_INCOMING", "SECURITIES_TRANSFER_OUTGOING", "SELL_ORDER", "TAX_PAYMENT", "TAX_PREPAYMENT_DE", "TAX_PREPAYMENT_DE_CANCELLATION", "TAX_REFUND", "FRENCH_IFU" ] }, "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": "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": "User unique identifier.", "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": "Report Data - Order ex-ante cost", "type": "object", "description": "Contents of the order ex-ante cost report.", "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": "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": "" }, "address": { "type": "object", "description": "User residential 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": "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": "Type of the order.\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": { "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 } }, "additionalProperties": false } }, "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": "Tenant Client ID", "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", "type": "object", "description": "The order ex-ante cost report is generated by the client sharing the valid and relevant input data for the order.", "properties": { "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”." }, "order": { "title": "Order", "oneOf": [ { "title": "Ex-Ante Cost order", "type": "object", "description": "Ex Ante 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": "Type of the order.\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": [ "instrument_id", "instrument_id_type", "account_id", "user_id", "currency", "order_type", "side" ] }, { "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": "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": "Type of the order.\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", "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": { "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" } ] } }, "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" } ] } } } } } }, "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", "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": "User unique identifier.", "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": "Report Data - Order ex-ante cost", "type": "object", "description": "Contents of the order ex-ante cost report.", "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": "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": "" }, "address": { "type": "object", "description": "User residential 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": "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": "Type of the order.\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": { "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 } }, "additionalProperties": false } }, "required": [ "id", "user_id", "created_at", "type", "substituted_report_id" ], "additionalProperties": false }, "examples": { "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, "schema": { "title": "Report unique identifier.", "type": "string", "description": "Report unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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 user report", "description": "Retrieve a user report", "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": "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": "User unique identifier.", "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_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* GENERIC_COMMUNICATION - Generic communication\n* INCOME_DISTRIBUTION - Income distribution report\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_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)\n* FRENCH_IFU - French tax statement (Imprimé fiscal unique)", "type": "string", "enum": [ "ACCOUNT_CLOSING", "ACCOUNT_OPENING", "AD_HOC_ACCOUNT_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", "GENERIC_COMMUNICATION", "INCOME_DISTRIBUTION", "MONTHLY_BILLING_STATEMENT", "QUARTERLY_ACCOUNT_STATEMENT", "REVOKED_ORDER", "SECURITIES_TRANSFER_INCOMING", "SECURITIES_TRANSFER_OUTGOING", "SELL_ORDER", "TAX_PAYMENT", "TAX_PREPAYMENT_DE", "TAX_PREPAYMENT_DE_CANCELLATION", "TAX_REFUND", "FRENCH_IFU" ] }, "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": "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": "User unique identifier.", "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": "Report Data - Order ex-ante cost", "type": "object", "description": "Contents of the order ex-ante cost report.", "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": "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": "" }, "address": { "type": "object", "description": "User residential 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": "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": "Type of the order.\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": { "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 } }, "additionalProperties": false } }, "required": [ "id", "user_id", "created_at", "type", "substituted_report_id" ], "additionalProperties": false } ] }, "examples": { "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" } } } }, "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" } } } } } } }, "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, "schema": { "title": "User unique identifier.", "type": "string", "description": "User unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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": "Retrieve tax residencies", "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", "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", "items": { "title": "Tax residency", "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 identifier number" } }, "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": "Update tax residencies", "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", "properties": { "tax_residencies": { "type": "array", "minItems": 1, "items": { "title": "Tax residency for Create Request", "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 identifier number" } }, "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", "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", "items": { "title": "Tax residency", "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 identifier number" } }, "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": "Tenant Client ID", "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": "List portfolios allocations", "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", "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", "properties": { "id": { "title": "Portfolio allocation 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)" }, "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": "Create portfolios allocation", "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", "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", "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", "properties": { "id": { "title": "Portfolio allocation 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)" }, "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, "schema": { "title": "Portfolio allocation unique identifier", "type": "string", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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": "Retrieve portfolios allocation", "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", "properties": { "id": { "title": "Portfolio allocation 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)" }, "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": "Update portfolios allocation", "tags": [ "Portfolios" ], "security": [ { "oauth-client-credentials": [ "portfolios:admin" ] } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Portfolios allocation - Update - Request", "type": "object", "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", "properties": { "id": { "title": "Portfolio allocation 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)" }, "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": "Tenant Client ID", "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": "List portfolios configurations", "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", "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", "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", "format": "uuid" }, "rebalancing_strategy_ids": { "description": "List of rebalancing strategy ids", "type": "array", "items": { "title": "Portfolio rebalancing strategy unique identifier", "type": "string", "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": "Create portfolios configuration", "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", "properties": { "account_id": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" }, "allocation_id": { "title": "Portfolio allocation unique identifier", "type": "string", "format": "uuid" }, "rebalancing_strategy_ids": { "description": "List of rebalancing strategy ids", "type": "array", "items": { "title": "Portfolio rebalancing strategy unique identifier", "type": "string", "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", "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", "format": "uuid" }, "rebalancing_strategy_ids": { "description": "List of rebalancing strategy ids", "type": "array", "items": { "title": "Portfolio rebalancing strategy unique identifier", "type": "string", "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" } } } }, "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, "schema": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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": "Retrieve portfolios configuration", "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", "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", "format": "uuid" }, "rebalancing_strategy_ids": { "description": "List of rebalancing strategy ids", "type": "array", "items": { "title": "Portfolio rebalancing strategy unique identifier", "type": "string", "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": "Update portfolios configuration", "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", "properties": { "allocation_id": { "title": "Portfolio allocation unique identifier", "type": "string", "format": "uuid" }, "rebalancing_strategy_ids": { "description": "List of rebalancing strategy ids", "type": "array", "items": { "title": "Portfolio rebalancing strategy unique identifier", "type": "string", "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", "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", "format": "uuid" }, "rebalancing_strategy_ids": { "description": "List of rebalancing strategy ids", "type": "array", "items": { "title": "Portfolio rebalancing strategy unique identifier", "type": "string", "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": "Tenant Client ID", "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": "List portfolios orders", "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", "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", "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", "properties": { "id": { "title": "Portfolios order 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)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "User unique identifier.", "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", "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", "properties": { "id": { "title": "Order unique identifier", "type": "string", "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 - \n* PROCESSING - \n* FILLED - \n* CANCELLED - ", "enum": [ "NEW", "PROCESSING", "FILLED", "CANCELLED" ] } }, "required": [ "id", "side", "status" ], "additionalProperties": false } }, "client_reference": { "title": "An ID provided by the client", "type": "string" }, "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": "Create portfolios order", "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", "properties": { "user_id": { "title": "User unique identifier.", "type": "string", "description": "User unique identifier.", "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", "properties": { "id": { "title": "Portfolios order 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)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "User unique identifier.", "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", "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", "properties": { "id": { "title": "Order unique identifier", "type": "string", "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 - \n* PROCESSING - \n* FILLED - \n* CANCELLED - ", "enum": [ "NEW", "PROCESSING", "FILLED", "CANCELLED" ] } }, "required": [ "id", "side", "status" ], "additionalProperties": false } }, "client_reference": { "title": "An ID provided by the client", "type": "string" }, "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, "schema": { "title": "Portfolios order unique identifier", "type": "string", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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": "Retrieve portfolios order", "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", "properties": { "id": { "title": "Portfolios order 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)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "User unique identifier.", "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", "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", "properties": { "id": { "title": "Order unique identifier", "type": "string", "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 - \n* PROCESSING - \n* FILLED - \n* CANCELLED - ", "enum": [ "NEW", "PROCESSING", "FILLED", "CANCELLED" ] } }, "required": [ "id", "side", "status" ], "additionalProperties": false } }, "client_reference": { "title": "An ID provided by the client", "type": "string" }, "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": "Tenant Client ID", "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": "Trigger portfolio rebalancing", "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", "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", "properties": { "id": { "title": "Portfolio rebalancing execution unique identifier", "type": "string", "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": "", "in": "path", "required": true, "schema": { "title": "Order execution unique identifier", "type": "string", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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", "properties": { "id": { "title": "Portfolios order 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)" }, "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", "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": "", "in": "path", "required": true, "schema": { "title": "Order execution unique identifier", "type": "string", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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", "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", "properties": { "id": { "title": "Rebalancing execution order unique identifier", "type": "string", "format": "uuid" }, "execution_id": { "title": "Portfolio rebalancing execution unique identifier", "type": "string", "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", "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, "schema": { "title": "Portfolio allocation unique identifier", "type": "string", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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": "List portfolios allocation accounts", "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", "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", "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, "schema": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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, "schema": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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": "Tenant Client ID", "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", "enum": [ "EUR", "GBP" ] } }, "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", "enum": [ "EUR", "GBP" ] }, "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", "enum": [ "EUR", "GBP" ] } }, "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", "enum": [ "EUR", "GBP" ] }, "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", "enum": [ "EUR", "GBP" ] }, "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* 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", "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_OPTIMISATION - Tax optimisation\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_OPTIMISATION", "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": "Tenant Client ID", "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_OPTIMISATION - Tax optimisation\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_OPTIMISATION", "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, "schema": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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": "List accounts liquidations", "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", "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", "properties": { "id": { "title": "Account liquidation 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)" }, "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": "User unique identifier.", "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", "properties": { "id": { "title": "Account liquidation order unique identifier", "type": "string", "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 } } }, "required": [ "id", "created_at", "updated_at", "account_id", "cash_amount", "currency", "status", "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": "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" } ] } ] } } } }, "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": "Create account liquidation request", "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", "properties": { "user_id": { "title": "User unique identifier.", "type": "string", "description": "User unique identifier.", "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", "properties": { "id": { "title": "Account liquidation 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)" }, "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": "User unique identifier.", "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", "properties": { "id": { "title": "Account liquidation order unique identifier", "type": "string", "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 } } }, "required": [ "id", "created_at", "updated_at", "account_id", "cash_amount", "currency", "status", "orders" ], "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": [] } } } }, "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, "schema": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" } }, { "name": "account_liquidation_id", "in": "path", "required": true, "schema": { "title": "Account liquidation unique identifier", "type": "string", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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": "Retrieve account liquidation", "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", "properties": { "id": { "title": "Account liquidation 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)" }, "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": "User unique identifier.", "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", "properties": { "id": { "title": "Account liquidation order unique identifier", "type": "string", "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 } } }, "required": [ "id", "created_at", "updated_at", "account_id", "cash_amount", "currency", "status", "orders" ], "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" } ] } } } }, "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": "Cancel account liquidation", "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, "schema": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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": { "x-upvest-hidden-in-docs": false, "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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": "User unique identifier.", "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." } }, "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" } } }, "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" } } } } } } }, "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": "User unique identifier.", "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.*" } }, "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" } } }, "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" } } } } } } }, "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}": { "x-upvest-hidden-in-docs": false, "parameters": [ { "name": "account_transfer_id", "in": "path", "required": true, "schema": { "title": "Account transfer request unique identifier.", "type": "string", "description": "Account transfer request unique identifier.", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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": "User unique identifier.", "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.*" } }, "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" } } }, "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" } } } } } } }, "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": { "x-upvest-hidden-in-docs": false, "parameters": [ { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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, "schema": { "title": "User unique identifier.", "type": "string", "description": "User unique identifier.", "format": "uuid" } }, { "name": "account_id", "in": "query", "required": false, "schema": { "title": "Account unique identifier.", "type": "string", "description": "Account unique identifier.", "format": "uuid" } }, { "name": "account_group_id", "in": "query", "required": false, "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": "User unique identifier.", "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." } }, "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" }, { "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" } ] } }, "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" }, { "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" } ] } } } } } }, "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": "User unique identifier.", "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." } }, "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", "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" } }, "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", "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" } } } } } }, "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": "User unique identifier.", "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." } }, "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" } }, "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" } } } } } }, "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": "Tenant Client ID", "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": "User unique identifier.", "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": "User unique identifier.", "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": "Tenant Client ID", "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", "enum": [ "EUR", "GBP" ] } }, "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", "enum": [ "EUR", "GBP" ] }, "status": { "type": "string", "description": "Status of the virtual cash\n* ISSUED - Virtual cash increase is created.\n* CONFIRMED - Virtual cash increase was successfully processed.", "enum": [ "ISSUED", "CONFIRMED" ] } }, "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": "Tenant Client ID", "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", "enum": [ "EUR", "GBP" ] } }, "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", "enum": [ "EUR", "GBP" ] }, "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, "schema": { "title": "Virtual cash unique identifier", "type": "string", "description": "Virtual cash unique identifier", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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, "schema": { "title": "Savings plan unique identifier", "type": "string", "format": "uuid" } }, { "name": "upvest-client-id", "in": "header", "description": "Tenant Client ID", "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", "properties": { "id": { "title": "Savings plan 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)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "User unique identifier.", "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", "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": "Fee model unique identifier.", "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 order was cancelled .\n* CANCELLED_BY_CLIENT: The order was cancelled by the client.\n* CANCELLED_BY_UPVEST: The order 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": "Tenant Client ID", "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": "List savings plans", "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", "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", "properties": { "id": { "title": "Savings plan 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)" }, "user_id": { "title": "User unique identifier.", "type": "string", "description": "User unique identifier.", "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", "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": "Fee model unique identifier.", "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 order was cancelled .\n* CANCELLED_BY_CLIENT: The order was cancelled by the client.\n* CANCELLED_BY_UPVEST: The order 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