Guarantee Vault Platform Applicant API

Download OpenAPI specification:Download

The Guarantee Vault Platform API

Introduction

In the normal course of business, especially within the project business (e.g. construction) an applicant will need to arrange for a guarantee to be issued in favor of a beneficiary (normally its customer or buyer). The applicant will do this through a Guarantor (financial institution) that will issue the guarantee contract and be obligated by its terms. Today's challenge is that the storage of guarantees is decentralized while the guarantee related process is manual and paper based. The Guarantee Vault Platform seeks to create a centralized digital register that replaces the issued paper guarantee with its digital version. The digital guarantee would be issued by the guarantor on the GVP register and would retain the same legal authority as that held by the paper guarantee today.

GVP API looks to improve efficiency and increase transparency by replacing the decentralized paper process today with a centralized digital one that puts all market participants on the same digital page.

Problem | Solution – Putting participants on the same “digital page”

System Overview

At heart, in its simplest form, the system allows:

  • Applicants to request the issuance of digital guarantees
  • Guarantors to accept and issue digital guarantees to beneficiaries
  • Post issuance, the system allows applicants and beneficiaries to make certain requests (changes) to the issued guarantee has highlighted below.
    • Issuance – Applicant only
    • Amendment – Applicant only
    • Release – Both Applicant & Beneficiary
    • Claim – Beneficiary only

Workflow

Glossary

Term/AcronymDefinition
Access TokenA credential that is used by an application to access an API. It informs the API that the bearer of the token has been authorized to access the API and perform specific actions specified by the scope that has been granted. In the case, Access Tokens are formed as JSON Web Tokens. They should be transmitted to the API as a Bearer credential in an HTTP Authorization header.
APIApplication Programming Interface
ApplicantThe entity whose payment or performance is secured.
BeneficiaryThe entity to which the guarantee is issued.
client_idA unique ID determining the subject identified by Oauth/OpenID Connect.
CompanyRefers to a corporate entity
Corporate GuaranteeCorporate Guarantee is a guarantee in which a corporation agrees to be responsible for the financial obligations of, or the performance of, contractual obligations of another party (usually its subsidiary) in the event that the other party fails to discharge his financial obligations or perform the contractual obligations.
DVSDigital Vault Service GmbH company
Financial InstitutionRefers to both banks and insurance companies
Guarantee

An irrevocable payment obligation of a financial institution. It serves to secure certain contractually agreed performance, warranty and/or payment obligations of the parties to the trade contracts. Payment is made on demand. The term “Guarantee” when used in this document shall refer to all of the previously defined instruments namely:

  1. Bank Guarantee
  2. Surety Bond (“Bürgschaft”)
  3. Standby Letter of Credit
  4. Corporate Guarantee
GuarantorThe entity providing the guarantee, namely a financial institution e.g. Bank, Insurance Company, Corporate.
GVPGuarantee Vault Platform (a product under DVS)
GVP RegisterThe electronic register where the guarantor issues a new guarantee or posts an issuance action / event. Records made available on the GVP register are legally binding as per the terms of the guarantee contract once they become accessible by other transaction party(ies).
JWKS URLThe URL where a Relying Party presents new JSON Web Key Sets to the GVP authorization Service without having to upload the key sets manually via the GVP Web admin GUI.
JWT tokenJSON Web Tokens. An open, industry standard RFC 7519 method for representing claims securely between two parties. You may decode well-formed JWTs at JWT.io to view their claims.
Post Issuance Request

Refers to any requests coming after issuance of a guarantee from the applicant or beneficiary to the guarantor including:

  • Amendment
  • Reduction
  • Extension
  • Claim
  • Close
  • Extend-or-pay
  • Re-Assignment
  • Release
private_key_jwtPart of the cryptographic keypair that can be used to sign tokens that other parties can validate with the public key.
Refresh TokenA special kind of token that can be used to obtain a renewed Access Token. It is useful for renewing expiring Access Tokens without interrupting the integration. Using the Refresh Token, the Relying Partner can request a new Access Token at any time. Refresh Tokens can be renewed each time a new access token is requested.
Relying Party (RP) The client application that supports OAuth 2.0 and relies on the OpenID provider to authenticate the end user and request claims about that user. In this case, it's the Guarantors system integrating with GVP.
Standby Letter of Credit (SBLC)A lender's guarantee of payment to an interested third-party in the event the lender’s client who requested the SBLC defaults on an agreement.
Surety Bond (“Bürgschaft”)

A surety bond or surety (“Bürgschaft” in Germany) is a promise by a financial institution to pay one party(the obligee) a certain amount if a second party (the principal) fails to meet some obligation, such as fulfilling the terms of a contract. The surety bond protects the obligee against losses resulting from the principal's failure to meet the obligation.

Surety bonds are usually validity type “Unlimited”, not payable on first demand and are a standard in Germany.

Note: the surety bond (“Bürgschaft”) as such is regulated under the German Civil Code (“BGB”).

Unique Customer IdThe guarantors unique Customer Id for the applicant in their proprietary system.
Unlimited ValidityA guarantee for which the expiry is open-ended, i.e. it does not have a fixed expiry date.

Getting Started

With all participants using the same platform and rules, GVP will allow for a more streamlined end to end process. Once the guarantor validates, approves and issues the guarantee, the applicant will have the possibility to make it immediately available to the beneficiary via GVP. The beneficiary at that point (whether registered with GVP or not) will then have access to the guarantee in GVP with the possibility to view details or even print the guarantee if required.

Although GVP will be available through a user interface, the majority of participants will interact with GVP using APIs to their proprietary in-house systems. This document will detail the API specifications for Applicants.

Authentication

Security Scheme Type OAuth2
Client OAuth Flow - RFC6749 Section 4.4 Authorization URL: https://vault/.../oauth/token*

Scopes

Name Description
amendment:manage OpenID Connect scope for managing amendment requests
amendment:view OpenID Connect scope for viewing amendment requests
guarantee:manage OpenID Connect scope for managing guarantees
guarantee-request:manage OpenID Connect scope for managing guarantee-requests
guarantee-request:view OpenID Connect scope for viewing guarantee-requests
guarantee:view OpenID Connect scope for viewing guarantees
notification:manage OpenID Connect scope for managing notifications
notification:view OpenID Connect scope for viewing notifications
release:manage OpenID Connect scope for managing release requests
release:view OpenID Connect scope for viewing release requests
claim:manage OpenID Connect scope for managing claim requests
claim:view OpenID Connect scope for viewing claim requests

Authentication process

Relying Party will authenticate using its client_id (created during registration) and the private_key_jwt (according to OpenID Connect Core 1.0 chapter 9).

During the authentication process the Relying Party should generate a JWT token as described in RFC7523 section 2.2 and sign it using their private key and the RS256 algorithm (RFC7518 section 3.1).

If the Relying Party has been registered with "JWKS URL" option, the client developers should implement the corresponding endpoint on the guarantors side that returns public key(s) used for the verification. Then implementation should be done according to RFC7517 (page 10).

API Service account registration

Company admin users can create service accounts for a Relying Party. GVP system will generate a client_id for the new service account and then, the company admin will choose an application name (an informative label) and select the method to transmit the client's public key or certificate. This could be done via:

  1. JWKS URL endpoint (preferred)
  2. Manual file import
  3. Generating a keypair on the authorization server

The keypair will be required for the verification process. The preferred option for key handling is using the JWKS URL.

Using JWKS URL, the new keypairs will be downloaded from the client's JWKS endpoint. The other methods of communicating key-pairs will involve a manual step where company admin user re-imports the new key or certificate.

Authorization process overview
Overview of the authentication process.

Access token expiration

  • Access token - expires in 1 hour
  • Refresh token - expires in 2 hours

When the access token expires, the Relying Party shall use the refresh token in order to get a new access token or repeat the authentication process from the beginning.

Participants should implement this functionality or use any libraries that already provide a refresh token functionality “out of the box”.

Service errors

Error object specification based on RFC7807

Errors that return an error object will always return a JSON object with attributes as specified below.

  • type - string

    • A URI reference [RFC3986] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML [W3C.REC-html5-20141028]). When this member is not present, its value is assumed to be about:blank.
  • title - string

    • A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization (e.g., using) proactive content negotiation; see [RFC7231], Section 3.4).
  • status - number

    • The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.
  • detail - string

    • A human-readable explanation specific to this occurrence of the problem.
  • instance - string

    • A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.

Scope of the API

This API will cover the following workflow actions / scenarios

IDACTIONDESCRIPTION
1Guarantee RequestSubmit a guarantee request (Applicant → GVP → Guarantor)
2Guarantee IssuanceReceive issued guarantee (Guarantor → GVP → Applicant & Beneficiary)
3Guarantee ReturnReceive guarantee request back (Guarantor → GVP → Applicant)
4Re-submit Guarantee RequestSend previously returned guarantee request (Applicant → GVP → Guarantor)
5Amendment RequestSend amendment request (Applicant → GVP → Guarantor)
6Amendment IssuanceReceive issued amendment (Guarantor → GVP → Applicant & Beneficiary)
7Amendment ReturnReceive amendment request back (Guarantor → GVP → Applicant)
8Re-submit Amendment RequestSend previously returned amendment request (Applicant → GVP → Guarantor)
9Re-submit Release RequestSend previously returned release request (Applicant or Beneficiary → GVP → Guarantor)
10Release RequestSend release request (Applicant or Beneficiary → GVP → Guarantor)
11Release IssuanceReceive issued release (Guarantor → GVP → Applicant & Beneficiary)
12Close IssuanceReceive issued close (Guarantor → GVP → Applicant & Beneficiary)
13Reopen IssuanceReceive issued reopen (Guarantor → GVP → Applicant & Beneficiary)
14Claim IssuanceReceive issued claim (Guarantor → GVP → Applicant & Beneficiary)
15Corporate Guarantee IssuanceIssue corporate guarantee (Applicant → GVP → Beneficiary)
16Corporate Guarantee Amendment IssuanceIssue corporate guarantee amendment (Applicant → GVP → Beneficiary)
17Corporate Guarantee Release IssuanceIssue corporate guarantee release (Applicant → GVP → Beneficiary)
18Corporate Guarantee Claim IssuanceIssue corporate guarantee claim (Applicant → GVP → Beneficiary)
19Corporate Guarantee Close IssuanceIssue corporate guarantee close (Applicant → GVP → Beneficiary)
20Corporate Guarantee Reopen IssuanceIssue corporate guarantee reopen (Applicant → GVP → Beneficiary)
21Forward GuaranteeForward guarantee to beneficiary (Applicant → GVP → Beneficiary)
22Ask for Guarantee ReleaseSend ask release request to beneficiary (Applicant → GVP → Beneficiary)
23Certificate of Authenticity reportRetrieve certificate of authenticity report for guarantee (Applicant)

API Usage

  • The API is intended for usage with a system that usually receives incoming data either in a queue or batch-based manner.
  • The API assumes that the consumer of the API has a good understanding of the various steps in handling guarantees.
  • The interaction of the API is based around an end-point that presents notifications.
  • Notifications are references to new or changed business objects (e.g. guarantee request / issuance and post-issuance events such as amendments, releases, and claims),
  • These business objects may include links related to file resources.
  • The referenced business objects are expected to be downloaded and persisted in the client’s system, after which the notifications are “acknowledged”.
  • The objects are available even after being acknowledged, but will never change without a notification.
  • In the Guarantors system, decisions affecting the various business entities are made, and these are posted back into the GVP system as POST- or PUT-requests.
  • Error/successes are being transmitted back to the client via the HTTP response.
  • Successful transactions shall also appear listed in the notifications.
  • PUT update requests currently need to supply a complete copy the initial POST, including attached files.
  • Use ISO-8601 date format for all business-related dates in requests/responses.
    Business-related dates examples: Issuance Date, Expiry Date, Reference Date, Reference Expiry Date, Release Date etc.
  • Use ISO-8601 datetime format for all system-generated dates in requests/responses.
    System-generated dates examples: Decline date, Request Date, File Uploaded Date, Notification Creation Date etc.
  • All system-generated dates will be returned as datetimes in UTC
  • The maximum size permitted for uploaded files is 10MB
  • The maximum size allowed for requests(multipart/form-data or application/json) is 21MB
  • All the date fields are allowed between years '0001' and '9999'

Unregistered Beneficiary

When submitting a guarantee request through the POST: /applicant/v0/guarantee-requests endpoint, the beneficiary can be submitted using the uuid of an already registered beneficiary. If the beneficiary is not yet registered in the GVP or the uuid is not known, the details can be provided in the guarantee request instead. The beneficairy is now known as an Unregistered Beneficiary and the GVP response includes the uuid for this beneficiary. The GVP system will create a new entry in the Local Address Book of the consumer for any new Unregistered Beneficiary. For any subsequent request, GVP will try to identify the beneficiary now based on the beneficiary.name and beneficiary.email. If there is a matching entry already in the Local Address Book of the consumer, this beneficiary (e.g. the same uuid, address, details) will be used as a beneficiary.

Setting up your account

Identification of incoming applications

  • Prior to receiving any guarantee requests from a specific applicant, the applicant admin user must submit a “connection request” to the guarantor admin via the GVP web UI.
  • On accepting the “connection request” on the GVP web UI the guarantor admin will be prompted to provide their Unique Customer Id for the applicant in question
  • When receiving guarantee requests from applicants via the API, GVP shall dynamically add this unique Customer Id to the incoming request allowing the guarantor to immediately identify the applicant in their proprietary system.
On a connection request, the guarantor shall have the possibility to provide their unique Customer Id for a specific applicant
Once a connection is established, the guarantor participant shall also have the possibility to edit the unique “Customer Id”

The API Lifecycle

  1. The applicant sends guarantee request to GVP
  2. GVP dynamically adds guarantor’s unique Customer Id to the request
  3. As the guarantor’s system polls the notification endpoint, the guarantee request shall be listed in the notifications.
  4. The guarantor shall then download the guarantee request and referred attachments.
  5. It is expected that the data shall then be persisted in the guarantors proprietary system for financial guarantees.
  6. The guarantor shall then process the request at which time it shall have the following options:
    1. Return the request to the applicant
      • In this case the guarantor shall provide a reason for the return
      • The applicant shall have the possibility to edit and resubmit the request to the guarantor
      • In these cases where the request has been subsequentially re-sent to the guarantor the status shall be display as RESUBMITTED
    2. Issue the guarantee as requested by the applicant
      • On issuance the guarantor shall provide:
        1. The guarantor unique reference for the guarantee
        2. The issuance date
        3. The guarantee contract
      • The guarantor shall have the possibility to submit the guarantee contract as:
        1. Attached file (file types allowed to be confirmed)
        2. HTML text with format and images (to be confirmed)
    3. If the guarantor issues the guarantee, the records on the GVP central register are adjusted to reflect the issuance
    4. The applicant and beneficiary are notified and shall have access to the digital guarantee on the GVP register. The newly issued guarantee shall also appear listed in the notifications of the guarantor.

Notification Webhooks

As well as manually polling the notification API, any API Client can subscribe to notification events in the GVP system through Webhooks.

Configuration

Company admin user will have an option to configure the following webhook parameters for the API client:

  • Payload URL - endpoint URL that will receive the webhook POST requests (will be exposed from the client side)
  • Content Type - application/json or application/x-www-form-urlencoded
  • Secret - the secret that will be used for HMAC signature generation(see details below)
  • Activate flag - for enabling/disabling webhook
  • Notification types - the notification types that the client is interested in (GUARANTEE_REQUEST, GUARANTEE, AMENDMENT, RELEASE, CLAIM, CLOSE, REOPEN)
  • Version - GVP API version that API client uses (V0).

Usage

The HMAC signature will allow the API client to ensure that POST requests sent to the Payload URL are from GVP.

GVP will calculate a signature (based on a secret, the notification payload and the `HMAC SHA256` algorithm) and include it into X-Vault-Signature header in the webhook POST request as Base64-encoded hex value. The Client should implement the signature verification for these requests.

There are no retries of failed webhook deliveries and no API for listing or retrieving failed webhook events.

Therefore, the client service that exposes an endpoint for webhooks (see Payload URL) must be highly available. In case of any issues/maintenance on client service, API client should itself request/poll /v0/notifications/new endpoint (provided by GVP) in order to get missed notifications.

The notifications received through the webhook mechanism should still be acknowledged through the Acknowledge endpoint after being persisted by the Client API.

Exceptions/Error handling

When processing the requests to the API, different errors and exceptions can occur. The error states are listed in each request.

Most of GVP errors can be found on https://api-docs.guarantee-vault.com/errors/ErrorResponses.html

title field in response body displays exception type

type field in response body points to specific error description. For example, https://api-docs.guarantee-vault.com/errors/ErrorResponses.html#InvalidGuaranteeParticipantException

Questions

What is the purpose of the explicit Acknowledge function?

The explicit “Acknowledge” is required as the GVP system needs confirmation that each system has received the expected data.

When an Acknowledge is made by the client to GVP, GVP assumes that client received the data correctly and that it has been securely persisted into its proprietary system.

Without this explicit acknowledge, it is impossible for GVP to be certain that there were no technical difficulties and that the data was correctly received by the client’s system.

Will reporting of the items be provided via API?

Currently this is not within the scope of the API however this will be made available via the GVP web UI.

Support / Contact

If there are any questions regarding the API of the GVP system please contact us at [email protected].

Changelog

This changelog lists all additions and updates to the Guarantee Vault API, in chronological order. Changes can be in the following categories:

  • [added]: Added fields, endpoints or functionality
  • [changed]: Changes to existing data models
  • [removed]: Removed fields or functionality

14. January 2025

  • [added] Endpoint 'Guarantee Reopen'
  • [added] Endpoints 'Corporate Guarantee Reopen'

06. June 2024

  • [added] New attachment section guaranteeFilesLibrary added for guarantee-request and guarantee response models - this will be filled, if wordings from the wording library feature were supplied. Supplying library wordings is currently only availiable in the GVP UI.
  • [changed] If guaranteeWording OTHER was selected, it is now also possible to provide guaranteeFiles attachments or guaranteeText.

20. November 2023

  • [added] Field governingLawSubdivision for specifying the Subdivision of a Governing Law Country in a Guarantee.
  • [changed] Field placeOfJurisdiction in a Guarantee can only be filled if governingLaw is filled.
  • [changed] Field deliveryAddress in a Guarantee can also be filled optionally if APPLICANT, BENEFICIARY or OBLIGOR was selected to capture delivery details.
  • [changed] Field deliveryAddress in a Guarantee increased to 780 characters.
  • [changed] Field reason in an ask-release request increased to 1000 characters.

09. October 2023

  • [changed] Limit all issuance reference fields (issuance.ref) to 140 characters (guarantee, amendment, claim, release).

24. July 2023

  • [changed] Amendment Issuance files: minItems: 0 and maxItems: 10, not mandatory.

Notifications

The notifications gives the system a list of data of various types. The client should GET the document and referenced file resources. When the client is certain that the data is persisted to its system, a call to the Acknowledgement should be made.

The various resources will be available until they are explicitly acknowledged.

New Notifications

Retrieve up to limit un-acknowledged notifications from the notification inbox. This operation can be called either with or without a notification type, if type is omitted you will receive notifications from all channels/types. The latter is the suggested default, unless integration reasons dictate otherwise.

Although the requesting client is free to acknowledge at any time soon after receiving the notification, it is preferable that the object is retrieved before doing so.

query Parameters
type
string
limit
string
Default: 5

Responses

Response samples

Content type
application/json
{}

Acknowledge Notification

Marks the notification as received, and removes it from the notification inbox.

Although the requesting client is free to acknowledge at any time soon after receiving the notification, it is preferable that the object is retrieved before doing so.

path Parameters
notificationId
required
string

Responses

Response samples

Content type
application/json
{
  • "notificationId": "2d591c23-85b1-4e8c-a6bd-74d89f8955c5",
  • "status": "acknowledged"
}

Reject Notification

Marks the notification as rejected, saves the rejection reason and removes it from the notification inbox.

Although the requesting client is free to reject at any time soon after receiving the notification, it is preferable that the object is retrieved before doing so.

path Parameters
notificationId
required
string
Request Body schema: application/json
reason
required
string <= 1000 characters

Contains the reason for rejecting the notification

Responses

Request samples

Content type
application/json
{
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "notificationId": "2d591c23-85b1-4e8c-a6bd-74d89f8955c5",
  • "reason": "string",
  • "status": "acknowledged"
}

Guarantee Request

The guarantee request enables the applicant to submit a guarantee request, retrieve an overview of guarantee requests, retrieve the details of an individual guarantee request, and update a guarantee request in case it has been returned by the guarantor.

Submit a Guarantee Request

Submit a Guarantee Request to the GVP system. This makes it available for the Guarantor. If no uuid for the Beneficiary is provided, the Unregistered Beneficiary is used (see Usage of the API).

Instrument types allowed: BANK_GTEE, SURETY_BOND, STANDBY_LC, SURETY_PAYABLE_ON_FIRST_DEMAND

For detailed information about the maximum size permitted for uploaded file and for the request overall, please read API usage paragraph.

Request Body schema: multipart/form-data
required
object
guaranteeFiles
Array of strings <binary> [ 0 .. 10 ] items

Guarantee Files

If field "guaranteeWording" is set to "WORDING_APPLICANT" wording of applicant or "WORDING_BENEFICIARY" wording of beneficiary the user must either populate the field "guaranteeText" or attach file in field guaranteeFiles.

If field "guaranteeWording" is set to "OTHER" the user can optionally populate guaranteeText or attach guaranteeFiles.

Allowed content types:

  • text/plain
  • application/pdf
  • application/rtf
  • application/msword
  • application/vnd.ms-excel
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • application/vnd.oasis.opendocument.spreadsheet
  • application/vnd.oasis.opendocument.text
  • image/jpeg
  • image/png
  • image/tiff
otherAttachments
Array of strings <binary> [ 0 .. 10 ] items

Other Attachments

Other information related to the request can be attached here.

Can be multiple files

Allowed content types:

  • text/plain
  • application/pdf
  • application/rtf
  • application/msword
  • application/vnd.ms-excel
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • application/vnd.oasis.opendocument.spreadsheet
  • application/vnd.oasis.opendocument.text
  • image/jpeg
  • image/png
  • image/tiff

Responses

Response samples

Content type
application/json
{
  • "status": "REQUESTED",
  • "guaranteeRequestId": "ca6dede1-2b1d-49f0-9c04-ba7aa9df5986",
  • "instrument": "BANK_GTEE",
  • "obligor": {
    },
  • "applicant": {
    },
  • "guarantor": {
    },
  • "beneficiary": {
    },
  • "applicantRef": "Company0000345F",
  • "formInstrument": "DIRECT",
  • "guarantorDetailsSpecifiedBy": "APPLICANT",
  • "guaranteeType": "ADVANCE_PAY",
  • "guaranteeTypeOther": "Special Warranty Guarantee",
  • "guaranteeWording": "WORDING_BENEFICIARY",
  • "guaranteeWordingOther": "Other guarantee wording",
  • "specialTerms": "TERMS_EFFECTIVENESS",
  • "governingLaw": "DE",
  • "governingLawSubdivision": "Bavaria",
  • "placeOfJurisdiction": "Munich",
  • "nominalAmount": {
    },
  • "applicableRule": "ISPR",
  • "applicableRuleOther": "Under German Jurisdiction",
  • "validity": "LIMITED",
  • "expiryDate": "2020-09-23",
  • "expiryCondition": "Expiry condition",
  • "referenceType": "CONTRACT",
  • "referenceDate": "2020-07-23",
  • "referenceExpiryDate": "2020-07-30",
  • "contractNumber": "XS0000002334",
  • "contractAmount": {
    },
  • "contractCoverage": "17.5",
  • "instrumentPurpose": "DELIVER & INSTALL OF CEILING PANELS X 5",
  • "deliveryType": "DIGITAL",
  • "gvpDelivery": "APPLICANT_ONLY",
  • "deliverTo": "APPLICANT",
  • "deliveryAddress": "Company GmbH industrial boilers BU1, Maximilianstrasse 105, Schwäbisch Gmünd, Baden-Württemberg, DE",
  • "deliveryMethod": "OTHR",
  • "deliveryMethodDetails": "Additional Information delivery",
  • "comments": "Additional comment on the Guarantee",
  • "guaranteeText": "Guarantee sample text",
  • "guaranteeFiles": [],
  • "otherAttachments": [],
  • "issuance": {},
  • "language": "en",
  • "sent": {
    },
  • "correspondentGuarantor": {
    },
  • "approvedBy": "Approved by John Doe",
  • "demandIndicator": "NMLT",
  • "charges": "Charges",
  • "contactPerson": "Contact Person John Doe"
}

Retrieve Guarantee Requests

Retrieve Guarantee Requests up to limit for specified page. The response can be filtered

Filters

Name Description
lastChangeDateFrom Date range filter, marking the beginning of the interval. Example ?lastChangeDateFrom=2025-01-01&lastChangeDateTo=2025-05-01 or ?lastChangeDateFrom=2025-01-01. Can be specified without end boundary.
lastChangeDateTo Date range filter, marking the end of the interval. Example ?lastChangeDateFrom=2025-01-01&lastChangeDateTo=2025-05-01 or ?lastChangeDateTo=2025-05-01. Can be specified without begin boundary.
expiryDateFrom Date range filter, marking the beginning of the interval. Example ?expiryDateFrom=2025-01-01&expiryDateTo=2025-05-01 or ?expiryDateFrom=2025-01-01. Can be specified without end boundary.
expiryDateTo Date range filter, marking the end of the interval. Example ?expiryDateFrom=2025-01-01&expiryDateTo=2025-05-01 or ?expiryDateTo=2025-05-01. Can be specified without begin boundary.
guarantor.id Unary filter. Example guarantor.id=46d82fd0-ee0b-4716-8b1d-a67c1ff99c97
applicant.id Unary filter. Example applicant.id=46d82fd0-ee0b-4716-8b1d-a67c1ff99c97
obligor.id Unary filter. Example obligor.id=46d82fd0-ee0b-4716-8b1d-a67c1ff99c97
applicantRef Unary filter. Example applicantRef=46d82fd0-ee0b-4716-8b1d-a67c1ff99c97
status Unary filter. Example status=ISSUED. For guarantee requests only REQUESTED, SENT, ISSUED, RESUBMITTED, RETURNED, CLOSED are supported
query Parameters
applicantRef
string
guarantor.id
string
applicant.id
string
obligorId
string
status
string
lastChangeDateFrom
string
lastChangeDateTo
string
expiryDateFrom
string
expiryDateTo
string
page
string
Default: 0
limit
string <= 50
Default: 5

Responses

Response samples

Content type
application/json
{
  • "guaranteeRequests": [
    ]
}

Retrieve Guarantee Request

Fetch up-to-date copy of the specified guarantee request.

path Parameters
guaranteeRequestId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "status": "REQUESTED",
  • "guaranteeRequestId": "ca6dede1-2b1d-49f0-9c04-ba7aa9df5986",
  • "instrument": "BANK_GTEE",
  • "obligor": {
    },
  • "applicant": {
    },
  • "guarantor": {
    },
  • "beneficiary": {
    },
  • "applicantRef": "Company0000345F",
  • "formInstrument": "DIRECT",
  • "guarantorDetailsSpecifiedBy": "APPLICANT",
  • "guaranteeType": "ADVANCE_PAY",
  • "guaranteeTypeOther": "Special Warranty Guarantee",
  • "guaranteeWording": "WORDING_BENEFICIARY",
  • "guaranteeWordingOther": "Other guarantee wording",
  • "specialTerms": "TERMS_EFFECTIVENESS",
  • "governingLaw": "DE",
  • "governingLawSubdivision": "Bavaria",
  • "placeOfJurisdiction": "Munich",
  • "nominalAmount": {
    },
  • "applicableRule": "ISPR",
  • "applicableRuleOther": "Under German Jurisdiction",
  • "validity": "LIMITED",
  • "expiryDate": "2020-09-23",
  • "lastChangeDate": "2020-09-23",
  • "expiryCondition": "Expiry condition",
  • "referenceType": "CONTRACT",
  • "referenceDate": "2020-07-23",
  • "referenceExpiryDate": "2020-07-30",
  • "contractNumber": "XS0000002334",
  • "contractAmount": {
    },
  • "contractCoverage": "17.5",
  • "instrumentPurpose": "DELIVER & INSTALL OF CEILING PANELS X 5",
  • "deliveryType": "DIGITAL",
  • "gvpDelivery": "APPLICANT_ONLY",
  • "deliverTo": "APPLICANT",
  • "deliveryAddress": "Company GmbH industrial boilers BU1, Maximilianstrasse 105, Schwäbisch Gmünd, Baden-Württemberg, DE",
  • "deliveryMethod": "OTHR",
  • "deliveryMethodDetails": "Additional Information delivery",
  • "comments": "Additional comment on the Guarantee",
  • "guaranteeText": "Guarantee sample text",
  • "guaranteeFiles": [],
  • "guaranteeFilesLibrary": [],
  • "otherAttachments": [],
  • "issuance": {},
  • "language": "en",
  • "sent": {
    },
  • "declined": {
    },
  • "correspondentGuarantor": {
    },
  • "approvedBy": "Approved by John Doe",
  • "demandIndicator": "NMLT",
  • "charges": "Charges",
  • "contactPerson": "Contact Person John Doe"
}

Update returned Guarantee Request

Update Guarantee Request in RETURNED state. All original data will be updated. All fields not present in the body will be removed from the original request, including the attached files.

Instrument types allowed: BANK_GTEE, SURETY_BOND, STANDBY_LC, SURETY_PAYABLE_ON_FIRST_DEMAND

For detailed information about the maximum size permitted for uploaded file and for the request overall, please read API usage paragraph.

path Parameters
guaranteeRequestId
required
string
Request Body schema: multipart/form-data
required
object (UpdateGuaranteeRequest)
guaranteeFiles
Array of strings <binary> [ 0 .. 10 ] items

Guarantee Files

If field "guaranteeWording" is set to "WORDING_APPLICANT" wording of applicant or "WORDING_BENEFICIARY" wording of beneficiary the user must either populate the field "guaranteeText" or attach file in field guaranteeFiles..

If field "guaranteeWording" is set to "OTHER" the user can optionally populate guaranteeText or attach guaranteeFiles.

Allowed content types:

  • text/plain
  • application/pdf
  • application/rtf
  • application/msword
  • application/vnd.ms-excel
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • application/vnd.oasis.opendocument.spreadsheet
  • application/vnd.oasis.opendocument.text
  • image/jpeg
  • image/png
  • image/tiff
otherAttachments
Array of strings <binary> [ 0 .. 10 ] items

Other Attachments

Other information related to the request can be attached here.

Can be multiple files

Allowed content types:

  • text/plain
  • application/pdf
  • application/rtf
  • application/msword
  • application/vnd.ms-excel
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • application/vnd.oasis.opendocument.spreadsheet
  • application/vnd.oasis.opendocument.text
  • image/jpeg
  • image/png
  • image/tiff

Responses

Response samples

Content type
application/json
{
  • "status": "REQUESTED",
  • "guaranteeRequestId": "ca6dede1-2b1d-49f0-9c04-ba7aa9df5986",
  • "instrument": "BANK_GTEE",
  • "obligor": {
    },
  • "applicant": {
    },
  • "guarantor": {
    },
  • "beneficiary": {
    },
  • "applicantRef": "Company0000345F",
  • "formInstrument": "DIRECT",
  • "guarantorDetailsSpecifiedBy": "APPLICANT",
  • "guaranteeType": "ADVANCE_PAY",
  • "guaranteeTypeOther": "Special Warranty Guarantee",
  • "guaranteeWording": "WORDING_BENEFICIARY",
  • "guaranteeWordingOther": "Other guarantee wording",
  • "specialTerms": "TERMS_EFFECTIVENESS",
  • "governingLaw": "DE",
  • "governingLawSubdivision": "Bavaria",
  • "placeOfJurisdiction": "Munich",
  • "nominalAmount": {
    },
  • "applicableRule": "ISPR",
  • "applicableRuleOther": "Under German Jurisdiction",
  • "validity": "LIMITED",
  • "expiryDate": "2020-09-23",
  • "expiryCondition": "Expiry condition",
  • "referenceType": "CONTRACT",
  • "referenceDate": "2020-07-23",
  • "referenceExpiryDate": "2020-07-30",
  • "contractNumber": "XS0000002334",
  • "contractAmount": {
    },
  • "contractCoverage": "17.5",
  • "instrumentPurpose": "DELIVER & INSTALL OF CEILING PANELS X 5",
  • "deliveryType": "DIGITAL",
  • "gvpDelivery": "APPLICANT_ONLY",
  • "deliverTo": "APPLICANT",
  • "deliveryAddress": "Company GmbH industrial boilers BU1, Maximilianstrasse 105, Schwäbisch Gmünd, Baden-Württemberg, DE",
  • "deliveryMethod": "OTHR",
  • "deliveryMethodDetails": "Additional Information delivery",
  • "comments": "Additional comment on the Guarantee",
  • "guaranteeText": "Guarantee sample text",
  • "guaranteeFiles": [],
  • "otherAttachments": [],
  • "language": "en",
  • "sent": {
    },
  • "correspondentGuarantor": {
    },
  • "approvedBy": "Approved by John Doe",
  • "demandIndicator": "NMLT",
  • "charges": "Charges",
  • "contactPerson": "Contact Person John Doe"
}

Guarantee

The guarantee enables the applicant to retrieve the list of issued guarantees and retrieve the details of individual guarantees after issuance.

Retrieve Guarantees

Retrieve Guarantees up to limit for specified page. The response can filtered

Filters

Name Description
lastChangeDateFrom Date range filter, marking the beginning of the interval. Example ?lastChangeDateFrom=2025-01-01&lastChangeDateTo=2025-05-01 or ?lastChangeDateFrom=2025-01-01. Can be specified without end boundary.
lastChangeDateTo Date range filter, marking the end of the interval. Example ?lastChangeDateFrom=2025-01-01&lastChangeDateTo=2025-05-01 or ?lastChangeDateTo=2025-05-01. Can be specified without begin boundary.
expiryDateFrom Date range filter, marking the beginning of the interval. Example ?expiryDateFrom=2025-01-01&expiryDateTo=2025-05-01 or ?expiryDateFrom=2025-01-01. Can be specified without end boundary.
expiryDateTo Date range filter, marking the end of the interval. Example ?expiryDateFrom=2025-01-01&expiryDateTo=2025-05-01 or ?expiryDateTo=2025-05-01. Can be specified without begin boundary.
issuanceDateFrom Date range filter, marking the beginning of the interval. Example ?issuanceDateFrom=2025-01-01&issuanceDateTo=2025-05-01 or ?issuanceDateFrom=2025-01-01 . Can be specified without end boundary.
issuanceDateTo Date range filter, marking the end of the interval. Example ?issuanceDateFrom=2025-01-01&issuanceDateTo=2025-05-01 or ?issuanceDateTo=2025-05-01. Can be specified without begin boundary.
guarantor.id Unary filter. Example guarantor.id=46d82fd0-ee0b-4716-8b1d-a67c1ff99c97
applicant.id Unary filter. Example applicant.id=46d82fd0-ee0b-4716-8b1d-a67c1ff99c97
obligor.id Unary filter. Example obligor.id=46d82fd0-ee0b-4716-8b1d-a67c1ff99c97
applicantRef Unary filter. Example applicantRef=46d82fd0-ee0b-4716-8b1d-a67c1ff99c97
status Unary filter. Example status=ISSUED. For guarantees only ISSUED & CLOSED are supported
issuerRef Unary filter. Example issuerRef=46d82fd0-ee0b-4716-8b1d-a67c1ff99c97
query Parameters
applicantRef
string
issuerRef
string
guarantor.id
string
applicant.id
string
obligor.id
string
status
string
lastChangeDateFrom
string
lastChangeDateTo
string
expiryDateFrom
string
expiryDateTo
string
issuanceDateFrom
string
issuanceDateTo
string
page
string
Default: 0
limit
string <= 50
Default: 5

Responses

Response samples

Content type
application/json
{
  • "guarantees": [
    ]
}

Retrieve Guarantee

Up-to-date copy of the specified guarantee. The retrieved guarantee can be in any state.

path Parameters
guaranteeId
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "ISSUED",
  • "guaranteeId": "ed62b7ef-5f7e-440e-ac76-46a77832e008",
  • "instrument": "BANK_GTEE",
  • "obligor": {
    },
  • "applicant": {
    },
  • "guarantor": {
    },
  • "beneficiary": {
    },
  • "applicantRef": "Company0000345F",
  • "formInstrument": "DIRECT",
  • "guarantorDetailsSpecifiedBy": "APPLICANT",
  • "guaranteeType": "ADVANCE_PAY",
  • "guaranteeTypeOther": "Special Warranty Guarantee",
  • "guaranteeWording": "WORDING_BENEFICIARY",
  • "guaranteeWordingOther": "Other guarantee wording",
  • "specialTerms": "TERMS_EFFECTIVENESS",
  • "governingLaw": "DE",
  • "governingLawSubdivision": "Bavaria",
  • "placeOfJurisdiction": "Munich",
  • "nominalAmount": {
    },
  • "applicableRule": "ISPR",
  • "applicableRuleOther": "Under German Jurisdiction",
  • "validity": "LIMITED",
  • "expiryDate": "2020-09-23",
  • "lastChangeDate": "2020-09-23",
  • "expiryCondition": "Expiry condition",
  • "referenceType": "CONTRACT",
  • "referenceDate": "2020-07-23",
  • "referenceExpiryDate": "2020-07-30",
  • "contractNumber": "XS0000002334",
  • "contractAmount": {
    },
  • "contractCoverage": "17.5",
  • "instrumentPurpose": "DELIVER & INSTALL OF CEILING PANELS X 5",
  • "deliveryType": "DIGITAL",
  • "gvpDelivery": "APPLICANT_ONLY",
  • "deliverTo": "APPLICANT",
  • "deliveryAddress": "Company GmbH industrial boilers BU1, Maximilianstrasse 105, Schwäbisch Gmünd, Baden-Württemberg, DE",
  • "deliveryMethod": "OTHR",
  • "deliveryMethodDetails": "Additional Information delivery",
  • "comments": "Additional comment on the Guarantee",
  • "guaranteeText": "Guarantee sample text",
  • "guaranteeFiles": [],
  • "guaranteeFilesLibrary": [],
  • "otherAttachments": [],
  • "language": "en",
  • "issuance": {},
  • "correspondentGuarantor": {
    },
  • "sent": {
    },
  • "approvedBy": "Approved by John Doe",
  • "demandIndicator": "NMLT",
  • "charges": "Charges",
  • "contactPerson": "Contact Person John Doe"
}

Forward Guarantee

Forward the ISSUED guarantee to the Beneficiary.

The request body should be Empty.

Note: this endpoint is only applicable when the ISSUED guarantee DeliveryType is set to DIGITAL and gvpDelivery is set to APPLICANT_ONLY.

path Parameters
guaranteeId
required
string

Responses

Response samples

Content type
application/json
{}

Ask for Guarantee Release

Submits a request to beneficiary, to release DIGITAL guarantee

path Parameters
guaranteeId
required
string
Request Body schema: application/json
releaseDate
string <date>

Specifiy an optional release date for the guarantee.

reason
required
string <= 1000 characters

Contains the reason for the ask release request.

Responses

Request samples

Content type
application/json
{
  • "releaseDate": "2019-08-24",
  • "reason": "string"
}

Response samples

Content type
application/json
{}

Guarantee Amendment

The guarantee amendment enables the applicant to manage and process amendments to the original guarantee by submitting, retrieving and updating the amendments.

Submit an Amendment

Submit a Amendment Request to the GVP system. This makes it available for the Guarantor.

For detailed information about the maximum size permitted for uploaded file and for the request overall, please read API usage paragraph. Operation not supported on guarantees directly issued by guarantor with form of instrument 'INDIRECT' or 'DIRECT_ADVISING'.

path Parameters
guaranteeId
required
string
Request Body schema: multipart/form-data
required
object (SubmitAmendmentRequest)
guaranteeFiles
Array of strings <binary> [ 0 .. 10 ] items

Guarantee Files

If field "guaranteeWording" is set to "WORDING_APPLICANT" wording of applicant or "WORDING_BENEFICIARY" wording of beneficiary the user must either populate the field "guaranteeText" or attach file in field guaranteeFiles..

If field "guaranteeWording" is set to "OTHER" the user can optionally populate guaranteeText or attach guaranteeFiles.

Allowed content types:

  • text/plain
  • application/pdf
  • application/rtf
  • application/msword
  • application/vnd.ms-excel
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • application/vnd.oasis.opendocument.spreadsheet
  • application/vnd.oasis.opendocument.text
  • image/jpeg
  • image/png
  • image/tiff
attachments
Array of strings <binary> [ 0 .. 10 ] items

Attachments

Other information related to the request can be attached here.

Can be multiple files

Allowed content types:

  • text/plain
  • application/pdf
  • application/rtf
  • application/msword
  • application/vnd.ms-excel
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • application/vnd.oasis.opendocument.spreadsheet
  • application/vnd.oasis.opendocument.text
  • image/jpeg
  • image/png
  • image/tiff

Responses

Response samples

Content type
application/json
{
  • "amendmentRequestId": "f62d9c3e-1bd6-4c13-9f52-d1b5092380b3",
  • "guaranteeId": "ed62b7ef-5f7e-440e-ac76-46a77832e008",
  • "status": "REQUESTED",
  • "originator": "APPLICANT",
  • "nominalAmount": {
    },
  • "applicant": {
    },
  • "beneficiary": {
    },
  • "validity": "LIMITED",
  • "expiryDate": "2020-09-23",
  • "expiryCondition": "Expiry condition",
  • "referenceType": "CONTRACT",
  • "guaranteeType": "ADVANCE_PAY",
  • "guaranteeTypeOther": "Special Warranty Guarantee",
  • "guaranteeWording": "WORDING_BENEFICIARY",
  • "guaranteeWordingOther": "Other guarantee wording",
  • "specialTerms": "TERMS_EFFECTIVENESS",
  • "referenceDate": "2020-07-23",
  • "referenceExpiryDate": "2020-07-30",
  • "contractNumber": "XS0000002334",
  • "contractAmount": {
    },
  • "instrumentPurpose": "DELIVER & INSTALL OF CEILING PANELS X 5",
  • "details": {
    },
  • "bankInformation": "some useful information from Corporate X",
  • "guaranteeText": "Guarantee sample text",
  • "guaranteeFiles": [],
  • "attachments": [],
  • "sent": {
    },
  • "approvedBy": "Approved by John Doe",
  • "governingLaw": "DE",
  • "governingLawSubdivision": "Bavaria",
  • "placeOfJurisdiction": "Munich",
  • "demandIndicator": "NMLT",
  • "charges": "Charges",
  • "deliverTo": "APPLICANT",
  • "deliveryAddress": "Company GmbH industrial boilers BU1, Maximilianstrasse 105, Schwäbisch Gmünd, Baden-Württemberg, DE",
  • "deliveryMethod": "OTHR",
  • "deliveryMethodDetails": "Additional Information delivery",
  • "contactPerson": "Contact Person John Doe"
}

Retrieve an Amendment

Retrieve Amendments.

path Parameters
guaranteeId
required
string
amendmentRequestId
required
string

Responses

Response samples

Content type
application/json
{}

Update returned Amendment

Update Amendment request in RETURNED state. All original data will be updated. All fields not present in the body will be removed from the original Amendment request, including the attached files.

For detailed information about the maximum size permitted for uploaded file and for the request overall, please read API usage paragraph.

path Parameters
guaranteeId
required
string
amendmentRequestId
required
string
Request Body schema: multipart/form-data
required
object (UpdateAmendmentRequest)
guaranteeFiles
Array of strings <binary> [ 0 .. 10 ] items

Guarantee Files

If field "guaranteeWording" is set to "WORDING_APPLICANT" wording of applicant or "WORDING_BENEFICIARY" wording of beneficiary the user must either populate the field "guaranteeText" or attach file in field guaranteeFiles..

If field "guaranteeWording" is set to "OTHER" the user can optionally populate guaranteeText or attach guaranteeFiles.

Allowed content types:

  • text/plain
  • application/pdf
  • application/rtf
  • application/msword
  • application/vnd.ms-excel
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • application/vnd.oasis.opendocument.spreadsheet
  • application/vnd.oasis.opendocument.text
  • image/jpeg
  • image/png
  • image/tiff
attachments
Array of strings <binary> [ 0 .. 10 ] items

Attachments

Other information related to the request can be attached here.

Can be multiple files

Allowed content types:

  • text/plain
  • application/pdf
  • application/rtf
  • application/msword
  • application/vnd.ms-excel
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • application/vnd.oasis.opendocument.spreadsheet
  • application/vnd.oasis.opendocument.text
  • image/jpeg
  • image/png
  • image/tiff

Responses

Response samples

Content type
application/json
{
  • "amendmentRequestId": "f62d9c3e-1bd6-4c13-9f52-d1b5092380b3",
  • "guaranteeId": "ed62b7ef-5f7e-440e-ac76-46a77832e008",
  • "status": "REQUESTED",
  • "originator": "APPLICANT",
  • "nominalAmount": {
    },
  • "applicant": {
    },
  • "beneficiary": {
    },
  • "validity": "LIMITED",
  • "expiryDate": "2020-09-23",
  • "expiryCondition": "Expiry condition",
  • "referenceType": "CONTRACT",
  • "guaranteeType": "ADVANCE_PAY",
  • "guaranteeTypeOther": "Special Warranty Guarantee",
  • "guaranteeWording": "WORDING_BENEFICIARY",
  • "guaranteeWordingOther": "Other guarantee wording",
  • "specialTerms": "TERMS_EFFECTIVENESS",
  • "referenceDate": "2020-07-23",
  • "referenceExpiryDate": "2020-07-30",
  • "contractNumber": "XS0000002334",
  • "contractAmount": {
    },
  • "instrumentPurpose": "DELIVER & INSTALL OF CEILING PANELS X 5",
  • "details": {
    },
  • "bankInformation": "some useful information from Corporate X",
  • "guaranteeText": "Guarantee sample text",
  • "guaranteeFiles": [],
  • "attachments": [],
  • "sent": {
    },
  • "approvedBy": "Approved by John Doe",
  • "governingLaw": "DE",
  • "governingLawSubdivision": "Bavaria",
  • "placeOfJurisdiction": "Munich",
  • "demandIndicator": "NMLT",
  • "charges": "Charges",
  • "deliverTo": "APPLICANT",
  • "deliveryAddress": "Company GmbH industrial boilers BU1, Maximilianstrasse 105, Schwäbisch Gmünd, Baden-Württemberg, DE",
  • "deliveryMethod": "OTHR",
  • "deliveryMethodDetails": "Additional Information delivery",
  • "contactPerson": "Contact Person John Doe"
}

Guarantee Release

The guarantee release enables the applicant to retrieve the up-to-date information on the specified release.

Retrieve Guarantee Release

Up-to-date copy of the specified release. The release can be in any state.

path Parameters
guaranteeId
required
string
releaseRequestId
required
string

Responses

Response samples

Content type
application/json
{}

Update returned Release

Update Release request in RETURNED state. All original data will be updated. All fields not present in the body will be removed from the original Release request, including the attached files.

For detailed information about the maximum size permitted for uploaded file and for the request overall, please read API usage paragraph.

path Parameters
guaranteeId
required
string
releaseRequestId
required
string
Request Body schema: multipart/form-data
required
object (UpdateReleaseRequest)
supportingDocuments
Array of strings <binary> >= 0 items

Supporting Documents

Other information related to the request can be attached here.

Can be multiple files

Allowed content types:

  • text/plain
  • application/pdf
  • application/rtf
  • application/msword
  • application/vnd.ms-excel
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • application/vnd.oasis.opendocument.spreadsheet
  • application/vnd.oasis.opendocument.text
  • image/jpeg
  • image/png
  • image/tiff

Responses

Response samples

Content type
application/json
{}

Submit a Release

Submit Release Request to the GVP system. This makes it available for the Guarantor.

For detailed information about the maximum size permitted for uploaded file and for the request overall, please read API usage paragraph. Operation not supported on guarantees directly issued by guarantor with form of instrument 'INDIRECT' or 'DIRECT_ADVISING'.

path Parameters
guaranteeId
required
string
Request Body schema: multipart/form-data
required
object (SubmitReleaseRequest)
supportingDocuments
Array of strings <binary> >= 0 items

Supporting Documents

Other information related to the request can be attached here.

Can be multiple files

Allowed content types:

  • text/plain
  • application/pdf
  • application/rtf
  • application/msword
  • application/vnd.ms-excel
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • application/vnd.oasis.opendocument.spreadsheet
  • application/vnd.oasis.opendocument.text
  • image/jpeg
  • image/png
  • image/tiff

Responses

Response samples

Content type
application/json
{}

Guarantee Claim

The guarantee claim enables the applicant to retrieve the up-to-date information on the specified claim request.

Retrieve a Claim

Retrieve Claim.

path Parameters
guaranteeId
required
string
claimRequestId
required
string

Responses

Response samples

Content type
application/json
{}

Guarantee Close

The guarantee close enables the applicant to retrieve the up-to-date information on the specified close request.

Retrieve Close Request

Up-to-date copy of the specified close request. The close request can be in ISSUED state only.

path Parameters
guaranteeId
required
string
closeRequestId
required
string

Responses

Response samples

Content type
application/json
{}

Guarantee Reopen

The guarantee reopen enables the applicant to retrieve the up-to-date information on the specified reopen request.

Retrieve Reopen Request

Up-to-date copy of the specified reopen request. The reopen request can be in ISSUED state only.

path Parameters
guaranteeId
required
string
reopenRequestId
required
string

Responses

Response samples

Content type
application/json
{}

Guarantee Reports

Provides the possibility for the applicant to download guarantee reports generated by GVP.

Generate the Certificate of Authenticity report

Generate the Certificate of Authenticity for an existing guarantee. The report is generated in pdf format

path Parameters
guaranteeId
required
string

Responses

Response samples

Content type
application/json
{}

Corporate Guarantee

The corporate guarantee enables the user to issue corporate guarantees to beneficiaries and also expire the corporate guarantees accordingly.

Issue Corporate Guarantee

Issue Corporate Guarantee in GVP system. This makes it available for the corporate and beneficiary. If no uuid for the Beneficiary is provided, the Unregistered Beneficiary is used (see Usage of the API).

Instrument types allowed: CORPORATE_GTEE, CORPORATE_SURETY, COMFORT_LETTER, CORPORATE_SURETY_PAYABLE_ON_FIRST_DEMAND

Guarantee wordings allowed: WORDING_APPLICANT, WORDING_BENEFICIARY

For detailed information about the maximum size permitted for uploaded file and for the request overall, please read API usage paragraph.

Request Body schema: multipart/form-data
required
object (IssueCorporateGuarantee)
guaranteeFiles
Array of strings <binary> [ 0 .. 10 ] items

Guarantee Files

If field "guaranteeWording" is set to "WORDING_APPLICANT" wording of applicant or "WORDING_BENEFICIARY" wording of beneficiary the user must either populate the field "guaranteeText" or attach file in field guaranteeFiles..

If field "guaranteeWording" is set to "OTHER" the user can optionally populate guaranteeText or attach guaranteeFiles.

Allowed content types:

  • text/plain
  • application/pdf
  • application/rtf
  • application/msword
  • application/vnd.ms-excel
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • application/vnd.oasis.opendocument.spreadsheet
  • application/vnd.oasis.opendocument.text
  • image/jpeg
  • image/png
  • image/tiff
otherAttachments
Array of strings <binary> [ 0 .. 10 ] items

Other Attachments

Other information related to the request can be attached here.

Can be multiple files

Allowed content types:

  • text/plain
  • application/pdf
  • application/rtf
  • application/msword
  • application/vnd.ms-excel
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • application/vnd.oasis.opendocument.spreadsheet
  • application/vnd.oasis.opendocument.text
  • image/jpeg
  • image/png
  • image/tiff
issuedGuaranteeFiles
required
Array of strings <binary> = 1 items

The Guarantee file should be supplied here. Currently only pdf files are supported.

additionalAttachments
Array of strings <binary> [ 0 .. 10 ] items

Additional Attachments

Issuer might provide extra information related to the guarantee(release letter templates, signatory book, etc)

Can be multiple files.

Allowed content types:

  • text/plain
  • application/pdf
  • application/rtf
  • application/msword
  • application/vnd.ms-excel
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • application/vnd.oasis.opendocument.spreadsheet
  • application/vnd.oasis.opendocument.text
  • image/jpeg
  • image/png
  • image/tiff

Responses

Response samples

Content type
application/json
{
  • "status": "ISSUED",
  • "guaranteeId": "ed62b7ef-5f7e-440e-ac76-46a77832e008",
  • "instrument": "BANK_GTEE",
  • "obligor": {
    },
  • "applicant": {
    },
  • "guarantor": {
    },
  • "beneficiary": {
    },
  • "applicantRef": "Company0000345F",
  • "formInstrument": "DIRECT",
  • "guarantorDetailsSpecifiedBy": "APPLICANT",
  • "guaranteeType": "ADVANCE_PAY",
  • "guaranteeTypeOther": "Special Warranty Guarantee",
  • "guaranteeWording": "WORDING_BENEFICIARY",
  • "guaranteeWordingOther": "Other guarantee wording",
  • "governingLaw": "DE",
  • "placeOfJurisdiction": "Munich",
  • "nominalAmount": {
    },
  • "applicableRule": "ISPR",
  • "applicableRuleOther": "Under German Jurisdiction",
  • "validity": "LIMITED",
  • "expiryDate": "2020-09-23",
  • "expiryCondition": "Expiry condition",
  • "referenceType": "CONTRACT",
  • "referenceDate": "2020-07-23",
  • "referenceExpiryDate": "2020-07-30",
  • "contractNumber": "XS0000002334",
  • "contractAmount": {
    },
  • "contractCoverage": "17.5",
  • "instrumentPurpose": "DELIVER & INSTALL OF CEILING PANELS X 5",
  • "deliveryType": "DIGITAL",
  • "gvpDelivery": "APPLICANT_ONLY",
  • "deliverTo": "APPLICANT",
  • "deliveryAddress": "Company GmbH industrial boilers BU1, Maximilianstrasse 105, Schwäbisch Gmünd, Baden-Württemberg, DE",
  • "deliveryMethod": "OTHR",
  • "deliveryMethodDetails": "Additional Information delivery",
  • "comments": "Additional comment on the Guarantee",
  • "guaranteeText": "Guarantee sample text",
  • "guaranteeFiles": [],
  • "otherAttachments": [],
  • "language": "en",
  • "issuance": {},
  • "sent": {
    },
  • "approvedBy": "Approved by John Doe",
  • "demandIndicator": "NMLT",
  • "charges": "Charges"
}

Corporate Guarantee Amendment

The corporate guarantee amendment enables the user to manage and process amendments to the original guarantee by issuing and returning the amendments.

Issue Corporate Amendment(Applicant)

Issue Corporate Amendment in GVP system. This makes it available for the Beneficiary.

For detailed information about the maximum size permitted for uploaded file and for the request overall, please read API usage paragraph.

path Parameters
guaranteeId
required
string
Request Body schema: multipart/form-data
required
object (IssueCorporateGuaranteeAmendment)
guaranteeFiles
Array of strings <binary> [ 0 .. 10 ] items

Guarantee Files

If field "guaranteeWording" is set to "WORDING_APPLICANT" wording of applicant or "WORDING_BENEFICIARY" wording of beneficiary the user must either populate the field "guaranteeText" or attach file in field guaranteeFiles..

If field "guaranteeWording" is set to "OTHER" the user can optionally populate guaranteeText or attach guaranteeFiles.

Allowed content types:

  • text/plain
  • application/pdf
  • application/rtf
  • application/msword
  • application/vnd.ms-excel
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • application/vnd.oasis.opendocument.spreadsheet
  • application/vnd.oasis.opendocument.text
  • image/jpeg
  • image/png
  • image/tiff
attachments
Array of strings <binary> [ 0 .. 10 ] items

Attachments

Other information related to the request can be attached here.

Can be multiple files

Allowed content types:

  • text/plain
  • application/pdf
  • application/rtf
  • application/msword
  • application/vnd.ms-excel
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • application/vnd.oasis.opendocument.spreadsheet
  • application/vnd.oasis.opendocument.text
  • image/jpeg
  • image/png
  • image/tiff
issuedGuaranteeFiles
Array of strings <binary> [ 0 .. 10 ] items

The Guarantee file should be supplied here.

Allowed content types:

  • text/plain
  • application/pdf
  • application/rtf
  • application/msword
  • application/vnd.ms-excel
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • application/vnd.oasis.opendocument.spreadsheet
  • application/vnd.oasis.opendocument.text
  • image/jpeg
  • image/png
  • image/tiff

issuedGuaranteeNewFiles
Array of strings <binary> [ 0 .. 1 ] items

The new Guarantee file should be supplied here. Currently only pdf files are supported.

issuedGuaranteeNewAdditionalAttachments
Array of strings <binary> [ 0 .. 10 ] items

The Guarantee file should be supplied here.

Allowed content types:

  • text/plain
  • application/pdf
  • application/rtf
  • application/msword
  • application/vnd.ms-excel
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • application/vnd.oasis.opendocument.spreadsheet
  • application/vnd.oasis.opendocument.text
  • image/jpeg
  • image/png
  • image/tiff

Responses

Response samples

Content type
application/json
{}

Corporate Guarantee Release

The corporate guarantee release enables the user to release the applicant from the guarantee and return the corporate release request back to the beneficiary.

Issue Corporate Release

Release the applicant from the guarantee.

For detailed information about the maximum size permitted for uploaded file and for the request overall, please read API usage paragraph.

path Parameters
guaranteeId
required
string <uuid>
releaseRequestId
required
string <uuid>
Request Body schema: multipart/form-data
required
object (IssueReleaseRequest)

Issuance

Issuance details coming from the corporate

issuedReleaseFiles
Array of strings <binary> >= 0 items

The release issuance files should be supplied here.

Currently only pdf files are supported.

Responses

Response samples

Content type
application/json
{}

Return Corporate Release Request

Return corporate release request back to Beneficiary

path Parameters
guaranteeId
required
string <uuid>
releaseRequestId
required
string <uuid>
Request Body schema: application/json
reason
required
string <= 1000 characters

Reason for returning the Release Request.

Responses

Request samples

Content type
application/json
{
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "releaseRequestId": "52fa10f0-dae9-42a5-8c65-9d09b483fb63",
  • "date": "2019-08-24T14:15:22Z",
  • "reason": "string"
}

Issue Corporate Release(Applicant)

Issue Corporate Release in GVP system. This makes it available for the Beneficiary.

For detailed information about the maximum size permitted for uploaded file and for the request overall, please read API usage paragraph.

path Parameters
guaranteeId
required
string
Request Body schema: multipart/form-data
required
object (IssueCorporateGuaranteeRelease)
supportingDocuments
Array of strings <binary> >= 0 items

Supporting Documents

Other information related to the request can be attached here.

Can be multiple files

Allowed content types:

  • text/plain
  • application/pdf
  • application/rtf
  • application/msword
  • application/vnd.ms-excel
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • application/vnd.oasis.opendocument.spreadsheet
  • application/vnd.oasis.opendocument.text
  • image/jpeg
  • image/png
  • image/tiff
issuedReleaseFiles
Array of strings <binary> >= 0 items

The release issuance files should be supplied here.

Allowed content types:

  • text/plain
  • application/pdf
  • application/rtf
  • application/msword
  • application/vnd.ms-excel
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • application/vnd.oasis.opendocument.spreadsheet
  • application/vnd.oasis.opendocument.text
  • image/jpeg
  • image/png
  • image/tiff

Responses

Response samples

Content type
application/json
{}

Corporate Guarantee Claim

The corporate guarantee claim enables the user to demand for an amount of money be sent to beneficiary based on the value of the guarantee. The claim will reduce the nominal amount of the guarantee.

Issue Corporate Claim(Applicant)

Issue Corporate Claim in GVP system. This makes it available for the Beneficiary.

For detailed information about the maximum size permitted for uploaded file and for the request overall, please read API usage paragraph.

path Parameters
guaranteeId
required
string
Request Body schema: multipart/form-data
required
object (IssueCorporateGuaranteeClaim)
claimFiles
Array of strings <binary> [ 0 .. 10 ] items

Claim Files

The client must either populate the Text of Claim field or attach file in field "claimFiles"

Allowed content types:

  • text/plain
  • application/pdf
  • application/rtf
  • application/msword
  • application/vnd.ms-excel
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • application/vnd.oasis.opendocument.spreadsheet
  • application/vnd.oasis.opendocument.text
  • image/jpeg
  • image/png
  • image/tiff
attachments
Array of strings <binary> [ 0 .. 10 ] items

Attachments

Other information related to the request can be attached here.

Can be multiple files

Allowed content types:

  • text/plain
  • application/pdf
  • application/rtf
  • application/msword
  • application/vnd.ms-excel
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • application/vnd.oasis.opendocument.spreadsheet
  • application/vnd.oasis.opendocument.text
  • image/jpeg
  • image/png
  • image/tiff
claimAttachments
Array of strings <binary> >= 0 items

References to Guarantee Claim Issuance files from issuing party.

Allowed content types:

  • text/plain
  • application/pdf
  • application/rtf
  • application/msword
  • application/vnd.ms-excel
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • application/vnd.oasis.opendocument.spreadsheet
  • application/vnd.oasis.opendocument.text
  • image/jpeg
  • image/png
  • image/tiff

Responses

Response samples

Content type
application/json
{}

Issue Corporate Claim Request(Beneficiary)

Claims are issued after processing claim requests sent in by the Beneficiary. The Claim Request contains details which should render an updated Guarantee Document, which is sent in on the issuance of the claim.

For detailed information about the maximum size permitted for uploaded file and for the request overall, please read API usage paragraph.

path Parameters
guaranteeId
required
string
claimRequestId
required
string
Request Body schema: multipart/form-data
required
object (IssueIncomingCorporateClaimRequest)
claimAttachments
Array of strings <binary> >= 0 items

References to Guarantee Claim Issuance files from issuing party.

Allowed content types:

  • text/plain
  • application/pdf
  • application/rtf
  • application/msword
  • application/vnd.ms-excel
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • application/vnd.oasis.opendocument.spreadsheet
  • application/vnd.oasis.opendocument.text
  • image/jpeg
  • image/png
  • image/tiff

Responses

Response samples

Content type
application/json
{}

Return Corporate Claim Request

Return corporate guarantee claim request back to Beneficiary

path Parameters
guaranteeId
required
string <uuid>
claimRequestId
required
string <uuid>
Request Body schema: application/json
reason
required
string <= 1000 characters

Reason for returning the Claim.

Responses

Request samples

Content type
application/json
{
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "claimRequestId": "ae6cd89f-9216-4c24-8f5b-59e86a5ccecd",
  • "guaranteeId": "ed62b7ef-5f7e-440e-ac76-46a77832e008",
  • "date": "2019-08-24T14:15:22Z",
  • "reason": "string"
}

Corporate Guarantee Close

The corporate guarantee close enables the user to expire the guarantee. An issued request will close the guarantee.

Issue Corporate Close

Issue Corporate Close in GVP system. This makes it available for the Beneficiary.

For detailed information about the maximum size permitted for uploaded file and for the request overall, please read API usage paragraph.

path Parameters
guaranteeId
required
string
Request Body schema: multipart/form-data
required
object (IssueClose)
issuedCloseFiles
Array of strings <binary> >= 0 items

The close issuance files should be supplied here.

Allowed content types:

  • text/plain
  • application/pdf
  • application/rtf
  • application/msword
  • application/vnd.ms-excel
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • application/vnd.oasis.opendocument.spreadsheet
  • application/vnd.oasis.opendocument.text
  • image/jpeg
  • image/png
  • image/tiff

Responses

Response samples

Content type
application/json
{}

Corporate Guarantee Reopen

The corporate guarantee reopen enables the user to reopen the guarantee. An issued request will set the guarantee into issued state.

Issue Corporate Reopen

Issue Corporate Reopen in GVP system. This makes it available for the Beneficiary.

For detailed information about the maximum size permitted for uploaded file and for the request overall, please read API usage paragraph.

path Parameters
guaranteeId
required
string
Request Body schema: multipart/form-data
required
object (IssueReopen)
issuedReopenFiles
Array of strings <binary> >= 0 items

The reopen issuance files should be supplied here.

Allowed content types:

  • text/plain
  • application/pdf
  • application/rtf
  • application/msword
  • application/vnd.ms-excel
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • application/vnd.oasis.opendocument.spreadsheet
  • application/vnd.oasis.opendocument.text
  • image/jpeg
  • image/png
  • image/tiff

Responses

Response samples

Content type
application/json
{}