Transaction Screening API

Number of APIs: 4

The Transaction Screening service enables submitting batches of message screening requests and obtaining the outcome of the screening process, up to the decision taken by a user when a message was considered suspect and raised some alert.

v1.1.2 release notes - Expected usage of some attributes, formerly given in the Transaction Screening API Usage Guidelines, are now described in line in this specification. The API Usage Guidelines document remains applicable for features susceptible from evolving with the releases of the Transaction Screening service (e.g. the supported message definitions) - New usage for from, to and direction attributes: the presence of these attributes will be checked for the ISO20022/MX message format (usage for the FIN/MT message format do not change) - Clarified that the sequence number based variant is the preferred way to poll for screening request status - Fixed screening request identifications in GET examples - Fixed mention of BLCK decision in documentation instead of BLOK - Additional examples - Relabeled rulebook as usage guidelines - Clarified that decision and reason NONE + TMOU is currently unused by the Transaction Screening service - Added a reference to the usage guidelines for additional information on decisions and reasons - Clarified documentation and addition of a section dedicated to failure recovery

v1.1.1 release notes - Updated pattern of screening request identification starting with a date

v1.1.0 release notes - Screening request identification attribute must start with a date - Producer identification is returned by the service with all responses - Producer identification GET parameter limited to 15 alphanumerical characters - Additional documentation

Key concepts

Screening request

When the consumer wants to submit a message for screening it posts a screening request to the Transaction Screening service. That screening request embeds the message to screen (in base64) and further details.

While the API model of the Screening Request is relatively flat, one can actually distinguish different kinds of attributes within the request, as shown in the diagram below:

Attributes that directly relate to the request such as its producer and identification, or how the Transaction Screening service will effectively have to process the request;
Attributes related to the message to screen, which includes the content of that message and a series of information about it; e.g. its business identifier (identifying the message in the sense defined by ISO 20022), its sending endpoint (from attribute). Note that the information at this level can also be present in the message content itself, depending on the format of message (e.g. a direction is present in the FIN MT message headers but it is not in a MX message).

Screening Request
    {producer, identification, ...}
    ↳ Message
        {message_definition_identifier, business_message_identifier, from, ...}
        ↳ Message Content
            <base64>

Screening request producer

The producer concept is meant to allow segregation between different producers of screening requests of a same institution subscribed to Transaction Screening; when retrieving screening results it acts as a filter, making it possible for a producer to only receive screening requests statuses for requests that it created. Note: the producer therefore does not specify which institution the screening requests belongs to; this aspect is dictated by the consumer credentials only.

The consumer can use the producer concept as it best suits its use case; e.g.

To enable entirely different back office systems submitting screening requests in the same institution while ensuring each is updated for the relevant statuses only;
To provide some affinity to a node when retrieving statuses when a back office system has multiple active nodes.

Screening request identification

The screening request identification unambiguously identifies the screening request of the producer that has created that request. This identification is defined by the producer (respecting the format defined in this specification) and serves in the correlation of the screening request and the statuses showing the progress of the screening process. A producer therefore cannot submit several screening requests with the same identification; any duplicate identification will cause the rejection of the screening request. Additionally,

If a screening request, in a prior batch, was already accepted it remains valid; but when the duplicate screening requests are found within a same batch, all duplicates in that batch are rejected.
Even if a screening request was rejected (i.e. the Transaction Screening service responded with an ERRR status when it was posted), the identification must not be reused.
There is no time limitation to this constraint: identifications, even if they pertained to screening requests purged from the system, must not be reused.

If necessary the producer can submit multiple screening requests for the same message instance (e.g. because the message has been corrected and needs to be rescreened, because the producer has lost prior screening results), provided that these are in screening requests carrying different identifications. Note that, since it is the same message instance, all these screening requests will likely have the same business message identifier.

The notion of duplicate screening request identification only applies to one given producer. Different producers (i.e. with different producer_identification), even if submitting screening requests for the same institution, can use the same identifications without causing duplicates.

Screening request status

The screening request status represents the progress of request along the screening process. Depending on the scenario the trace of statuses can be as follows (where the first status PROC or ERRR represents that returned synchronously when creating the screening request; see below).

Message with no alert or non-blocking alert
PROC (processing) → CMPL (complete)
Message with alert requiring a user decision
PROC (processing) → PEND (pending user decision) → CMPL (complete)
Error during processing (e.g. message parsing or screening)
PROC (processing) → ERRR (error)
Invalid screening request
ERRR (error)

Decision and reason

Once the screening request has reached the status CMPL (complete) the decision represents the outcome of the screening process. This decision is assorted with a reason motivating it. The combinations below of decisions and reasons can be returned by the Transaction Screening service.

The Transaction Screening API Usage Guidelines (see the documentation on the Standards & Developer Hub and SWIFT Knowledge Centre) clarify the effective usage of the decision and reason by the Transaction Screening service.

ALLO (allow) + NOSC (not screened), NOAL (no alert), NBLA (non-blocking alert) or USER (user decision)
BLOK (block) + USER (user decision)
NONE (none) + TMOU (timeout)

The combination NONE + TMOU is provisionally included in this specification for situations where the service is unable to give a response within some expected time frame; e.g. because alerts are set to expire when they were not reviewed by a user. At the moment, these are unused.

Using the Transaction Screening Service

Sending Screening Requests

Screening requests are submitted by a producer to the Transaction Screening service in batches (see limit of batch size in the API specification). For performance reasons and to avoid call rejection due to spike arresting and rate limitations, the consumer is encouraged to constitute batches of reasonable size rather than posting screening requests individually.

If the POST request body is properly formatted (i.e. it respects the API specification), the Transaction Screening service will,

Acknowledge the creation of some screening request resources (once for the whole POST) with an HTTP status code 201;
Provide, for each screening request within the POST, a status indicating if it was created in

- A PROC (processing) status because the request was properly formed and accepted;
- Or an ERRR (error) status due to some failure (in such a case an error structure is also included to help pinpointing the issue).

A batch can be partially accepted (i.e. the POST response can include a mix of PROC and ERRR statuses). Because of this the Transaction Screening service will not return an HTTP status code 400 when there is an error with a screening request. The consumer must review the status returned for each request to know which are accepted.

A screening request in status PROC will be processed asynchronously; its status will be monitored with the GET operation (see next section).

A batch of screening requests can mix messages of different formats; e.g. a batch can contain requests for both MT and MX messages.

Polling the Status of Screening Requests

The Transaction Screening service supports a polling model enabling screening request producers to be updated with the progress of their screening requests (via the GET operation). Several variants, below, are provided to enable the consumer getting the right statuses in a stateless way; the variants are mutually exclusive.

The variant querying the status by sequence number must be used for normal operations. In practice the other variants may only be used for exceptional cases; e.g. for error recovery. As highlighted below the date and time based variant come with limitations, while the variant querying specific screening requests can result in unwanted operations, as requests have not necessarily progressed when the query is performed (therefore returning again a status that was provided in a prior query). The latter variant, unlike that by sequence number, also requires the consumer to track the state of the incomplete screening requests to know which still need to be queried.

Sequence number based

GET filter: sequence_number

The Transaction Screening service stamps each status created during the screening process with a sequence number. By disclosing relevant sequence numbers to the consumer and letting it use them in the GET operation the Transaction Screening services can determine what statuses were not yet communicated to the consumer.

Practically, with each response to a GET call, the Transaction Screening service provides a new sequence number (along with the statuses) to enable obtaining, in a next query, more recent statuses than those already returned. The sequence number returned with the response ensures that there is no gap in the sequence returned by the service and that no status is returned more than once. This is illustrated in the following sequence of GET calls:

  GET request ?sequence_number=0      ⇢ GET response
                                          {sequence_number: 87407, statuses: [...]}
  GET request ?sequence_number=87407  ⇢ GET response
                                          {sequence_number: ..., statuses: [...]}
  ...

The series of GET calls can be bootstrapped by

Obtaining a sequence number with the date and time based variant below. The sequence number returned in that case will ensure that there is no gap or overlap between the statuses obtained by calling the two variants successively.
Using the special sequence number 0 representing a point in time anterior to any status of any screening request of the producer (shown in the figure above).

Calling the GET operation several times with the same sequence number will return

The same statuses each time;
Possibly additional newer statuses if some were created in between the calls due to the progress of some screening requests.

Also note that since this variant intends to keep the consumer updated with the actual progress of the screening requests

The status PROC (processing) is never returned in this case, as it is of no use to the consumer (the initial POST confirms the screening request is accepted and will be processed). Only subsequent statuses in the diagram above can be returned.
When the screening request raises an alert PEND (pending user decision) is only returned once. The next status returned by the GET operation for the particular screening request will indicate its completion (see screening request status transitions above).
- Date and time based
GET filter: last_update

The producer intends to retrieve all the statuses updated at, or after, a timestamp known from the producer.

Since there is a limit on the number of statuses returned in one call it is possible that the consumer will need to perform other calls with more recent timestamps to be fully up-to-date. Depending on the situation, determining a timestamp that creates no gap in the sequence and that will not cause the same status to be returned multiple times can be tricky (e.g. because the clocks of the consumer and the service provider are not necessarily perfectly aligned, even if all the systems rely on a time synchronisation service). Alternatively, after a call with a timestamp, the consumer can switch to the variant based on the sequence number (above); a sequence number is also included with the results of a date and time based query to enable this.

Similarly to the variant above the status PROC (processing) will not be returned.

Specific screening requests

GET filter: identification_list (array)

When explicitly querying some screening requests, by filtering on their identification, the Transaction Screening service returns the latest status of these requests. It is meant to be used in error recovery scenarios or e.g. when the consumer needs to check if a particular screening request has been submitted (no status will be returned if the screening request is unknown).

Unlike the variants above the status PROC (processing) can be returned if the screening request has not progressed.

Recovering from a Consumer Failure

Note: this section discusses a failure of the service consumer application, not errors associated with invalid screening requests or messages. See references to the ERRR (error) status in this documentation for details about the latter cases.

The consumer is advised to persist the sequence number value along with the screening request statuses in a transactional manner, so that even if a failure (of the consumer) occurs the GET sequence can restart with a sequence number guaranteeing no status will be omitted.

Although, when that is not possible (for reasons that solely depend on the consumer), we recommend making a first GET call with the date and time based variant after recovering from the failure. The last_update query parameter can be set to a value that slightly precedes the moment of failure to ensure no status is skipped. The consumer then discards any duplicate status that it would have processed already.

Alternatively, the bootstrap sequence number 0 can be used (see above). The Transaction Screening service will then return the sequence progression for all the screening requests it has received from the producer (and that were not yet cleaned according to the data retention policies applying to the service). Obtaining the statuses up to the moment of failure can require multiple GET calls, as the size of the response is limited.

Complement to Model Documentation

Due to restrictions in the OpenAPI standard, it is not possible to provide a description for attributes referencing a data type from the model. The list below complements the documentation with the missing descriptions.

The tag [guidelines] indicates that the attribute is further described in the Transaction Screening API Usage Guidelines (see the documentation on the Standards & Developer Hub and SWIFT Knowledge Centre).

For readers familiar with ISO 20022 an [ISO20022] tag is displayed with an additional pointer to highlight that the attribute refers to a concept present in ISO 20022.

ScreeningRequests
Collects a batch of screening requests.
- producer_identification
  Specifies the identification of the application instance that produced the batch of screening requests.
- screening_requests
  Provides the screening requests in the batch.
ScreeningRequest
Requests the screening of a message to the Transaction Screening service.
- identification
  Unambiguously identifies the screening request of the producer that has created that request. The identification is used to correlate the request and the statuses giving the progress of that request.
Usage:
The first 8 characters of the identification must be the YYYYMMDD date part of the current time in UTC without timezone offset. The Transaction Screening service will tolerate some deviation to cope with request transmission delays or minor clock de-synchronisation. The consumer can freely define the rest of the identification. - owner

Usage:
The attribute is reserved and must be omitted. - routing
Specifies a code that can be used in routing rules in the Transaction Screening service.

Usage:
The routing code is reserved for future use and must be omitted currently. - business_message_identifier [guidelines]
Unambiguously identifies the business message to the messaging endpoint that has created the business message.

[ISO20022] Business Application Header / Business Message Identifier (BizMsgIdr) - message_definition_identifier [guidelines]
Contains the message identifier that defines the business message in the message_content attribute.

[ISO20022] Business Application Header / Message Definition Identifier (MsgDefIdr) - business_service [guidelines]
Specifies the business service agreed between the two MessagingEndpoints under which rules this Business Message is exchanged.

[ISO20022] Business Application Header / Business Service (BizSvc) - from, to, message_direction
Specifies the BICs of the messaging endpoints exchanging the message and the direction of that message, assuming that the institution making the screening request for that message is the sending or the receiving messaging endpoint. These endpoint BICs are used as the “sender” and the “receiver” information in Transaction Screening.

[ISO20022] Business Application Header / From (Fr), To (To)

Usage:
The attributes must be used as follows depending on the format of message. - FIN message (MT format)
```
The attributes must all be omitted, they are determined automatically by the Transaction Screening service based on the message content (using block 1 and 2).
```
- Other message (e.g. ISO20022, SEPA, SIC)
  - The message_direction attribute is mandatory.
  - When the direction is SENT (that is, the institution is the sending MessagingEndpoint), the from attribute is mandatory and the BIC in the attribute must be one of the BIC (used for messaging purposes) with which the institution is subscribed to the Transaction Screening service.
  - When the direction is RECE (that is, the institution is the receiving MessagingEndpoint), the to attribute is mandatory. The same constraints on the BIC as above apply.
Notice that the points above do not require both the from and to attributes to be present. The Transaction Screening service will attempt to retrieve the BIC left unspecified from the Business Application Header (BAH) accompanying the Business Message (in the message_content attribute).

In absence of BAH, or if the BAH does not provide the missing BIC, the from or to attribute, depending on which was left unspecified, must be used. - message_content
Contains the base64 encoded content of the business message to be screened.
ScreeningRequestStatuses
Collects statuses of one or more of screening requests.
- producer_identification
  Indicates which producer has created the screening requests for which the statuses are given.
Usage:
The producer identification returned by the Transaction Screening service (whether it is when creating screening requests or polling for statuses) is necessarily the same as that in the consumer request. - sequence_number
Identifies the point in time (in a way that is understandable by the service provider) at which the most recent status in the collection was created. No assumption should be made on the format or values. It is meant to be passed as-is in sequence of operations to retrieve only statuses created past that point in time.

Usage:
The attribute is only present in response to operation retrieving screening request statuses when variant with parameters sequencenumber or lastupdate have been used. - status
Provides the screening requests statuses in the collection.

Usage:
When retrieving screening request statuses the array can be empty if the filter parameter are such that no status is retrieved. This includes the normal case where no screening request has progressed since the point in time identified by the sequencenumber or lastupdate parameters, or if the screening request identification_list parameter does not refer to an existing screening request.

None of the variants retrieving screening request statuses will report statuses for requests declared invalid upon POST (i.e. for which the POST response included a status ERRR).

When querying statuses using a point in time the collection of statuses possibly includes several statuses for the same screening request if it transitioned to different statuses since that point in time. While the consumer should not make any assumption on the order of the statuses of different screening requests, statuses of a same screening request are guaranteed to be in order of increasing last update time (therefore following the logical order in the screening process).

When querying statuses for specific screening requests (i.e. by identification_list) only the current status is returned.
ScreeningRequestStatus
Provides information about the status of a request along the screening process, and the outcome where relevant.
- identification
  Identifies the screening request for which the status is provided.
- last_update
  Indicates when the particular status was created or last updated.
- status
  Indicates the status of the request in the screening process.
- decision
  When the status code is COMPL, provides the outcome of the screening process, including the decision to be applied to the message. Attribute decision is mutually exclusive with error.
- error
  When the status code is ERR, provides details about the error condition. Attribute error is mutually exclusive with decision.
ScreeningDecision [guidelines]
Provides the outcome of the screening process, including the decision to be applied to the message.
- decision
  Indicates what decision must be applied to the message. This decision is a result of automated or user actions, depending on settings in the Transaction Screening service, and whether the screening caused an alert or not.
- reason
  Indicates what reason motivated the decision.

Contact Support: Name: Standards & Developer Hub Email: developer@swift.com

Submits a batch of screening requests. - Submits a batch of screening requests 2. POST {{baseUrl}}/screening-requests
Authorization - Refresh Token POST https://sandbox.swift.com/oauth2/v1/token
Retrieves the statuses of screening requests. - Retrieves the statuses of screening requests 2. GET {{baseUrl}}/screening-requests/statuses?producer_identification=BOAPPL0001&sequence_number=8979&last_update=1186-11-04T03:35:23.2105&identification_list=20190417.UseCase1Message1
Teardown - Revoke Token POST https://sandbox.swift.com/oauth2/v1/revoke