{ "openapi": "3.0.1", "info": { "title": "Bank of England RTGS Tasks API", "version": "1.11.0", "description": "Request from the API / UI to update / create a resource in RTGS results in a task being created (except some exceptions which will result in a direct create/update). Tasks may result in an MSR (Multi Step Review) approval request (if MSR is turned on for the task), or may be processed by the RTGS without requiring approval (if MSR is turned off for the task). Multi Step Review (MSR) is the process where a second user needs to action a request for change from the Operator or BERTI. This is to ensure that critical business functions are checked and approved by another user to avoid accidental operational requests being actioned in the RTGS. \n\n The Bank of England RTGS Tasks API enables an organisation to: \n- Retrieve a specific task details", "contact": { "email": "APITeam@bankofengland.co.uk", "name": "RTGS API team" }, "license": { "url": "https://www.bankofengland.co.uk/payment-and-settlement", "name": "Please refer to the API Annex under the \"Requirements for use of RTGS accounts\" section" } }, "servers": [ { "url": "https://api-test.swiftnet.sipn.swift.com/boe-rtgs-api-pilot-i1/task-mgmt/np4/v1", "description": "NP4 Environment (Non-Prod)", "variables": { "apiPath": { "default": "/boe-rtgs-api-pilot-i1/task-mgmt/np4" }, "taskApiPath": { "default": "/boe-rtgs-api-pilot-i1/task-mgmt/np4" } } }, { "url": "https://api-test.swiftnet.sipn.swift.com/boe-rtgs-api-pilot-i1/task-mgmt/np5/v1", "description": "NP5 Environment (Non-Prod)", "variables": { "apiPath": { "default": "/boe-rtgs-api-pilot-i1/task-mgmt/np5" }, "taskApiPath": { "default": "/boe-rtgs-api-pilot-i1/task-mgmt/np5" } } }, { "url": "https://api-test.swiftnet.sipn.swift.com/boe-rtgs-api-pilot-i2/task-mgmt/pp2/v1", "description": "PP2 Environment (Dress-Rehearsals)", "variables": { "apiPath": { "default": "/boe-rtgs-api-pilot-i2/task-mgmt/pp2" }, "taskApiPath": { "default": "/boe-rtgs-api-pilot-i2/task-mgmt/pp2" } } }, { "url": "https://api-test.swiftnet.sipn.swift.com/boe-rtgs-api-pilot-i3/task-mgmt/pp2/v1", "description": "PP2 Environment (Pre-Prod)", "variables": { "apiPath": { "default": "/boe-rtgs-api-pilot-i3/task-mgmt/pp2" }, "taskApiPath": { "default": "/boe-rtgs-api-pilot-i3/task-mgmt/pp2" } } }, { "url": "https://api.swiftnet.sipn.swift.com/boe-rtgs-api/task-mgmt/v1", "description": "Live Environment (Prod)", "variables": { "apiPath": { "default": "/boe-rtgs-api/task-mgmt" }, "taskApiPath": { "default": "/boe-rtgs-api/task-mgmt" } } } ], "paths": { "/tasks/{taskId}": { "get": { "tags": [ "Tasks" ], "summary": "Retrieves specific task details along with the status based on the task id.", "description": "A \"task\" is used to track any update / create requests made to a resource (E.g.: Chaps Payments Controls). The task resource URL along with a task id is returned in response of the resources update / create API call. Given a task id, this endpoint allows the consumer to retrieve the details and status of a specific task, that the consumer is authorised to, for up to past 30 days from the creation of the task.", "operationId": "getSingleTask", "parameters": [ { "name": "taskId", "in": "path", "description": "A unique ID for the task assigned by the RTGS. A \"task\" is used to track any create / delete / update requests made to a resource (E.g.: Chaps Payments Controls). ", "required": true, "schema": { "pattern": "^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$", "type": "string" }, "example": "a4faa192-ddd7-11ed-b5ea-0242ac120002" }, { "name": "x-userContext", "in": "header", "description": "User context is in base64 format. It will include the institution BIC. Participants do not need to send this value. This will be populated at Network Level.", "required": false, "schema": { "type": "string", "format": "byte" }, "example": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImN1cmwgLXYgbGRhcDovL0RJUkwwMS5zd2lmdG5ldC5zaXBuLnN3aWZ0LmNvbTozODkvY249dHNzY2hhbm5lbCxvPXN3bGliZWIzLG89c3dpZnQ/dXNlckNlcnRpZmljYXRlIiwidHlwIjoiSldUIn0=" }, { "name": "x-journeyId", "in": "header", "description": "Used to uniquely identify end to end journey of the API request. If header is provided in the request, then the same will be replayed in response headers. This will be populated at Network Level.", "required": false, "schema": { "maxLength": 64, "minLength": 64, "type": "string" }, "example": "721C04F0B91A53908E4233D56E07E35D7C62AE63B881DD50B24FF19315CB4F92" }, { "name": "X-Forwarded-Host", "in": "header", "description": "Identifies the original host and port requested by the client in the Host HTTP request header. If no port is included, the default port for the service requested is implied. This will be populated at Network Level.", "required": false, "schema": { "pattern": "^[-a-zA-Z0-9@:%._+~#]{2,256}(:[0-9]{2,4})*$", "type": "string" }, "example": "example.com:8080" }, { "name": "X-Forwarded-Path", "in": "header", "description": "Identifies the original URL path requested by the client, including any query string. This will be populated at Network Level. ", "required": false, "schema": { "type": "string" }, "example": "/boe-rtgs-api/resource-mgmt/v1/resources?parentName=eq%3Aparent" } ], "responses": { "200": { "description": "Task found", "headers": { "x-journeyId": { "description": "Used to identify end to end journey of the API request.", "style": "simple", "schema": { "type": "string", "example": "721C04F0B91A53908E4233D56E07E35D7C62AE63B881DD50B24FF19315CB4F92" } }, "Cache-Control": { "description": "Holds directives (instructions) for caching in responses. No caching done from API gateway side. ", "style": "simple", "schema": { "type": "string", "example": "no-cache, no-store, no-transform" } }, "Content-Language": { "description": "Describes the language(s) intended for the audience. Allowed values: \"en-GB\".", "style": "simple", "schema": { "type": "string", "example": "en-GB" } } }, "content": { "application/json;charset=utf-8": { "schema": { "$ref": "#/components/schemas/TaskSingleResponse_OperatorSingleEndpoints" } } } }, "400": { "description": "Bad request", "headers": { "x-journeyId": { "description": "Used to identify end to end journey of the API request.", "style": "simple", "schema": { "type": "string", "example": "721C04F0B91A53908E4233D56E07E35D7C62AE63B881DD50B24FF19315CB4F92" } }, "Cache-Control": { "description": "Holds directives (instructions) for caching in responses. No caching done from API gateway side. ", "style": "simple", "schema": { "type": "string", "example": "no-cache, no-store, no-transform" } }, "Content-Language": { "description": "Describes the language(s) intended for the audience. Allowed values: \"en-GB\".", "style": "simple", "schema": { "type": "string", "example": "en-GB" } } }, "content": { "application/json;charset=utf-8": { "schema": { "$ref": "#/components/schemas/APIErrorResponseWrapperDTO_OperatorSingleEndpoints" }, "example": { "error": { "status": "400", "id": "a1aa1111-1a11-1111-11a1-1aa1aa111a13", "detail": "Constraint Violation - Path Variable(s)", "errors": [ { "errorCode": "EAPIGTW2002", "detail": "Invalid id provided: TT" } ] } } } } }, "401": { "description": "Unauthorized", "headers": { "x-journeyId": { "description": "Used to identify end to end journey of the API request.", "style": "simple", "schema": { "type": "string", "example": "721C04F0B91A53908E4233D56E07E35D7C62AE63B881DD50B24FF19315CB4F92" } } } }, "403": { "description": "Forbidden", "headers": { "x-journeyId": { "description": "Used to identify end to end journey of the API request.", "style": "simple", "schema": { "type": "string", "example": "721C04F0B91A53908E4233D56E07E35D7C62AE63B881DD50B24FF19315CB4F92" } } } }, "404": { "description": "Record not found", "headers": { "x-journeyId": { "description": "Used to identify end to end journey of the API request.", "style": "simple", "schema": { "type": "string", "example": "721C04F0B91A53908E4233D56E07E35D7C62AE63B881DD50B24FF19315CB4F92" } }, "Cache-Control": { "description": "Holds directives (instructions) for caching in responses. No caching done from API gateway side. ", "style": "simple", "schema": { "type": "string", "example": "no-cache, no-store, no-transform" } }, "Content-Language": { "description": "Describes the language(s) intended for the audience. Allowed values: \"en-GB\".", "style": "simple", "schema": { "type": "string", "example": "en-GB" } } }, "content": { "application/json;charset=utf-8": { "schema": { "$ref": "#/components/schemas/APIErrorResponseWrapperDTO_OperatorSingleEndpoints" }, "example": { "error": { "status": "404", "id": "a1aa1111-1a11-1111-11a1-1aa1aa111a15", "detail": "Record not found", "errors": [ { "errorCode": "EAPIGTW2017", "detail": "Record does not exist for given ID : 88" } ] } } } } }, "405": { "description": "Method not allowed", "headers": { "x-journeyId": { "description": "Used to identify end to end journey of the API request.", "style": "simple", "schema": { "type": "string", "example": "721C04F0B91A53908E4233D56E07E35D7C62AE63B881DD50B24FF19315CB4F92" } } } }, "406": { "description": "Not acceptable", "headers": { "x-journeyId": { "description": "Used to identify end to end journey of the API request.", "style": "simple", "schema": { "type": "string", "example": "721C04F0B91A53908E4233D56E07E35D7C62AE63B881DD50B24FF19315CB4F92" } } } }, "429": { "description": "Too many request", "headers": { "x-journeyId": { "description": "Used to identify end to end journey of the API request.", "style": "simple", "schema": { "type": "string", "example": "721C04F0B91A53908E4233D56E07E35D7C62AE63B881DD50B24FF19315CB4F92" } } } }, "500": { "description": "Internal server error", "headers": { "x-journeyId": { "description": "Used to identify end to end journey of the API request.", "style": "simple", "schema": { "type": "string", "example": "721C04F0B91A53908E4233D56E07E35D7C62AE63B881DD50B24FF19315CB4F92" } } } } }, "path": "/tasks/{taskId}", "method": "GET" } } }, "components": { "schemas": { "DualInputKey_OperatorSingleEndpoints": { "type": "object", "properties": { "label": { "type": "string" }, "userInput": { "$ref": "#/components/schemas/JsonNode_OperatorSingleEndpoints" } }, "description": "This field contains the values entered by the approver.This is for blind dual input which allows an approver to input the same values as the requester without seeing what they have inputted. For authorised consumers, when performing an update, this is an editable field. ", "nullable": true, "example": [ { "label": "currencyCode", "userInput": {} } ] }, "JsonNode_OperatorSingleEndpoints": { "type": "object" }, "SingleResponseLinksSchema_OperatorSingleEndpoints": { "title": "Links", "required": [ "self" ], "type": "object", "properties": { "self": { "type": "string", "description": "A URL to reproduce the current request.", "example": "{apiPath}/v1/resource/1f740fe7-c251-4d82-8abd-11953d76f594" }, "taskUrl": { "type": "string", "description": "A URL to retrieve task information associated to a resource.", "example": "{taskApiPath}/v1/tasks/0e740fe7-c251-4d82-8abd-11953d76f593" } } }, "SingleResponseTask_OperatorSingleEndpoints": { "title": "SingleResponse", "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Task_OperatorSingleEndpoints" } } } }, "TaskSingleResponse_OperatorSingleEndpoints": { "title": "TaskSingleResponse", "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SingleResponseTask_OperatorSingleEndpoints" }, "links": { "$ref": "#/components/schemas/SingleResponseLinksSchema_OperatorSingleEndpoints" } } }, "TaskTrail_OperatorSingleEndpoints": { "required": [ "insertedAt", "taskStatusName", "userName" ], "type": "object", "properties": { "userName": { "pattern": "^[A-Za-z0-9'\\.\\- \\s]{1,255}$", "type": "string", "description": "Unique username for the user assigned in RTGS who created the task.", "example": "John Smith" }, "comment": { "pattern": "^[\\\\0-9A-Za-z\\s\\/\\-\\?\\)\\.\\,\\'\\+\\!\\#\\$\\%\\&\\*\\=\\^\\_\\`\\{\\|\\}\\~\"\\;\\<\\>\\@]{0,200}$", "type": "string", "description": "Additional narrative when updating a task", "example": "Verified and Approving the task" }, "taskStatusName": { "pattern": "^[A-Za-z\\s]{1,35}$", "type": "string", "description": "Status of the task", "example": "Submitted" }, "insertedAt": { "type": "string", "description": "Date and time at which the Task was last updated", "format": "date-time", "example": "2021-02-22T12:00:00.123456Z" } }, "description": "This field provides a history of changes to the request. It includes status, date, time, userName and comment", "nullable": true }, "Task_OperatorSingleEndpoints": { "title": "Task", "required": [ "createdByUserName", "createdOn", "dualInputAttempts", "dualInputRequired", "isAmendmentAllowed", "lastUpdatedByUserName", "lastUpdatedOn", "msrRequired", "participantFullName", "priority", "readOnly", "resourceIds", "revisionCapacityReached", "taskId", "taskStatusCode", "taskStatusName", "taskTypeName" ], "type": "object", "properties": { "taskId": { "pattern": "^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$", "type": "string", "description": "A unique ID for the task assigned by the RTGS. A \"task\" is used to track any create / delete / update requests made to a resource (E.g.: Chaps Payments Controls). ", "example": "d4605a02-f776-437f-8691-b7b4e29395ec" }, "taskRef": { "pattern": "^(?=.{1,35}$)[A-Z0-9]{1,23}-[A-Z0-9]{4}(-\\d{1,7})?$", "type": "string", "description": "The unique task reference assigned by the RTGS. For non-atomic requests (that generate multiple tasks), this will include the numeric suffix.", "nullable": true, "example": "D04NOTES-R2D3" }, "taskTypeName": { "pattern": "^[A-Za-z_\\-\\(\\)&'\\s]{1,50}$", "type": "string", "description": "Identifier of the category to which the task belongs to. For authorised consumers, this will help you to identify the endpoint which if used in conjunction with the resourceIds, will allow you to retrieve the resource associated to the task. Possible values can be fetched from \"GET /filterValues?resourceName=taskTypes\" endpoint. ", "example": "Update Participant Details" }, "taskStatusCode": { "pattern": "^[A-Z_]{1,35}$", "type": "string", "description": "Current status code of the task within RTGS. Possible values can be fetched from \"GET /filterValues?resourceName=taskStatuses\" endpoint. For authorised consumers, when performing an update, this is an editable field. ", "example": "SUBMITTED" }, "taskStatusName": { "pattern": "^[A-Za-z\\s]{1,35}$", "type": "string", "description": "Current status name of the task within RTGS. Possible values can be fetched from \"GET /filterValues?resourceName=taskStatuses\" endpoint. ", "example": "Submitted" }, "participantFullName": { "pattern": "^[\\\\0-9a-zA-Z\\/\\-\\?\\:\\(\\)\\.\\,\\'\\+\\s\\!\\#\\$\\%\\&\\*\\=\\^\\_\\`\\{\\|\\}~\"\\;\\<\\>\\@\\[\\]]{1,100}$", "type": "string", "description": "Full Name of the organisations / participants in the RTGS.", "example": "Barclays" }, "team": { "pattern": "^[A-Za-z\\s]{1,50}$", "type": "string", "description": "The team responsible for the task. This is not applicable for participants. ", "nullable": true, "example": "" }, "priority": { "type": "string", "description": "Priority of the task", "example": "NORMAL", "enum": [ "NORMAL", "URGENT" ] }, "payload": { "type": "string", "description": "This will contain the old and new value of the resource requested by the initial API call or after an amendment has been made. For authorised consumers, when performing an update, this is an editable field. ", "nullable": true, "example": "{\"oldValue\":{\"participantId\":\"d4605a01-f776-437f-869a-b7b4e29395ed\",\"headroomId\":\"d4605a01-f776-437f-869a-b7b4e29395ed\",\"headroomBalance\":10000,\"maxHeadroom\":50000,\"headroomLastUpdatedOn\":\"2022-12-02T13:00:00.123456Z\",\"multilateralLimitId\":\"d4605a01-f776-437f-869a-b7b4e29395ed\",\"multilateralLimit\":400,\"multilateralLimitLastUpdatedOn\":\"2022-12-02T13:00:00.123456Z\",\"multilateralPosition\":500,\"headroomRefresh\":\"On\",\"multilateralValueCapId\":\"d4605a01-f776-437f-869a-b7b4e29395ed\",\"multilateralValueCap\":50000,\"multilateralValueCapLastUpdatedOn\":\"2022-12-02T13:00:00.123456Z\",\"autoPromoteDelay\":60,\"nonUrgentBalance\":50000,\"multilateralPositionPercentage\":80},\"newValue\":{\"participantId\":\"d4605a01-f776-437f-869a-b7b4e29395ed\",\"headroomId\":\"d4605a01-f776-437f-869a-b7b4e29395ed\",\"headroomBalance\":10000,\"maxHeadroom\":50000,\"headroomLastUpdatedOn\":\"2022-12-02T13:00:00.123456Z\",\"multilateralLimitId\":\"d4605a01-f776-437f-869a-b7b4e29395ed\",\"multilateralLimit\":1000,\"multilateralLimitLastUpdatedOn\":\"2022-12-02T13:00:00.123456Z\",\"multilateralPosition\":1000,\"headroomRefresh\":\"On\",\"multilateralValueCapId\":\"d4605a01-f776-437f-869a-b7b4e29395ed\",\"multilateralValueCap\":50000,\"multilateralValueCapLastUpdatedOn\":\"2022-12-02T13:00:00.123456Z\",\"autoPromoteDelay\":60,\"nonUrgentBalance\":50000,\"multilateralPositionPercentage\":100}}" }, "msrRequired": { "type": "boolean", "description": "Flag to indicate whether this task requires a multi step review. If the flag is \"true\", then this task requires a multi step review. ", "example": true }, "isAmendmentAllowed": { "type": "boolean", "description": "Flag to indicate whether this task is allowed to be amendment. If the flag is \"true\", then this task can be amendment. Note: a task can only be amended once. ", "example": true }, "dualInputRequired": { "type": "boolean", "description": "Flag to indicate whether this task requires additional user input for approval. If the flag is \"true\" then this task requires additional user input for approval.", "example": true }, "dualInputAttempts": { "maximum": 3, "minimum": 0, "type": "integer", "description": "This field tracks the number of attempts when an approver performs blind dual input. Blind dual input is to allow an approver to input the same values as the requester without seeing what they have inputted. An approver has a total of 3 attempts to blindly input the same values as the requester.", "format": "int32", "example": 0 }, "dualInputKeys": { "type": "array", "description": "This field contains the values entered by the approver.This is for blind dual input which allows an approver to input the same values as the requester without seeing what they have inputted. For authorised consumers, when performing an update, this is an editable field. ", "nullable": true, "example": [ { "label": "currencyCode", "userInput": {} } ], "items": { "$ref": "#/components/schemas/DualInputKey_OperatorSingleEndpoints" } }, "taskTrail": { "type": "array", "description": "This field provides a history of changes to the request. It includes status, date, time, userName and comment", "nullable": true, "items": { "$ref": "#/components/schemas/TaskTrail_OperatorSingleEndpoints" } }, "revisionCapacityReached": { "type": "boolean", "description": "Flag to indicate whether the given task can be amended or it must be finalised via rejection or approval. If the flag is \"true\", then this task cannot be amended and must be finalised via rejection or approval.", "example": false }, "comments": { "pattern": "^[\\\\0-9A-Za-z\\s\\/\\-\\?\\)\\.\\,\\'\\+\\!\\#\\$\\%\\&\\*\\=\\^\\_\\`\\{\\|\\}\\~\"\\;\\<\\>\\@]{0,200}$", "type": "string", "description": "This is a free text field that can be used by the user to input comments when approving / rejecting a request. For authorised consumers, when performing an update, this is an editable field. ", "nullable": true, "example": "Update required" }, "resourceIds": { "pattern": "^[A-Za-z0-9\\-]{1,100}$", "type": "array", "description": "List of resources the task belongs to", "example": [ "a4faa192-ddd7-11ed-b5ea-0242ac120002" ], "items": { "pattern": "^[A-Za-z0-9\\-]{1,100}$", "type": "string", "description": "List of resources the task belongs to", "example": "[\"a4faa192-ddd7-11ed-b5ea-0242ac120002\"]" } }, "expiredAt": { "type": "string", "description": "Date and time at which the task has expired. Note: this field will only be populated once the task has expired. This should follow the standard ISO 8601 format with UTC offset. ", "format": "date-time", "nullable": true, "example": "2021-02-23T00:00:00.123456Z" }, "createdOn": { "type": "string", "description": "Date and time at which the task was created on. This should follow the standard ISO 8601 format with UTC offset. ", "format": "date-time", "example": "2021-02-22T12:00:00.123456Z" }, "createdByUserName": { "pattern": "^[A-Za-z0-9'\\.\\- \\s]{1,255}$", "type": "string", "description": "Unique username for the user assigned in RTGS who created the task.", "example": "John Smith" }, "lastUpdatedOn": { "type": "string", "description": "Date and time at which the task was last updated. This should follow the standard ISO 8601 format with UTC offset. ", "format": "date-time", "example": "2021-02-22T12:00:00.123456Z" }, "lastUpdatedByUserName": { "pattern": "^[A-Za-z0-9'\\.\\- \\s]{1,255}$", "type": "string", "description": "Unique username for the user assigned in the RTGS who last updated the task. ", "example": "Haley Berry" }, "readOnly": { "type": "boolean", "description": "Flag to indicate whether the resource is editable. If the flag is \"true\", the request to update/delete a resource will fail. This field will be available on the GET Single Task endpoint only. ", "example": true } } }, "APIErrorResponseDTO_OperatorSingleEndpoints": { "title": "APIErrorResponse", "required": [ "detail", "errors", "id", "status" ], "type": "object", "properties": { "status": { "pattern": "^\\d{3}$", "type": "string", "description": "Standard HTTP Status code defined in RFC 7231" }, "id": { "maxLength": 36, "minLength": 36, "type": "string", "description": "A unique reference (GUID) for the error instance, for audit purposes and traceability.", "format": "uuid", "example": "fb06dbc9-da8d-4927-b0f8-0eec823aaaa7" }, "detail": { "type": "string", "description": "Brief error message explaining the error" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorsFragment_OperatorSingleEndpoints" } } } }, "APIErrorResponseWrapperDTO_OperatorSingleEndpoints": { "title": "APIErrorResponseWrapper", "type": "object", "properties": { "error": { "$ref": "#/components/schemas/APIErrorResponseDTO_OperatorSingleEndpoints" } } }, "ErrorsFragment_OperatorSingleEndpoints": { "title": "ErrorInfo", "required": [ "detail", "errorCode" ], "type": "object", "properties": { "errorCode": { "maxLength": 11, "minLength": 11, "pattern": "E[A-Z0-9]{6}[0-9]{4}", "type": "string", "description": "Custom Error Code consists of the following \n ", "example": "EAPIGTW2039" }, "detail": { "type": "string", "description": "Description of the error detail with further granularity" }, "uri": { "type": "string", "description": "URL to help remediate the problem, or provide more information, or to API Reference or help etc.", "format": "uri" } } } }, "securitySchemes": { "oauthBearerToken": { "type": "http", "scheme": "bearer", "bearerFormat": "opaque OAuth 2.0", "description": "\nThe access token obtained as a result of OAuth 2.0 flows. SWIFT supports two OAuth grant types depending on the API service.\n* JWT-Bearer grant type [RFC 7523](https://tools.ietf.org/html/rfc7523)\n* Password grant type\n\nThis API uses JWT-Bearer grant type.\n\nPlease visit [SWIFT OAuth Token API](https://developer.swift.com/swift-oauth-token-api) page for more information and examples on how to generate an OAuth token.\n \nIn this declaration only the basic security element to transport the bearer token of an OAuth2 process is declared.securitySchemes:" } } }, "security": [ { "oauthBearerToken": [] } ] }