Skip to content

Overview

Getting started with our API is straight-forward using the guide below.

Terminology

Term Meaning
Access token A token is retrieved by the Client after a successful access authorization flow. The access token is used by the API to authenticate Clients. The access token does not contain any information that the Client (or client's application) can use.
SieSmart The backend system to which the API connects.
Introducer Collective name for you as the user, representing either a broker or vendor.

Prerequisites

  • A trading agreement with Siemens Financial Services (SFS) - contact us to get this
  • A signed End-User License Agreement (EULA) that covers our API connection
  • Credentials (client ID and secret)

Differences between production and test APIs

The production version of the API provides access to real data. The system (SieSmart) is also connected to live applications such as credit search engines. The test environment is where you can develop your applications before you are ready to promote them to production. Config items, for example pricelist IDs, are consistent across the test and production environments.

The test environment is subject to regular database refreshes, therefore any data you have sent is liable to be periodically deleted.

Promoting your connection to production

Production API credentials are only provided by SFS after we are satisfied that your application is working correctly in the test environment. This will include (but not limited to) verifying that proposals you have sent have all the correct information. There is no limit to the amount of tests you are allowed to perform.

When everything is in order, the production credentials will be generated and sent to you.

Security considerations

Security is an important aspect. This API is developed by using well-tested and widely adopted security schemes. The Access Token are sent in the header of the request. All the communication between the API and client is secured by TLS, which encrypts the traffic. When developing an application, it is important to keep the credentials and tokens safe and handle them carefully. If you believe your credentials have been compromised please contact SFS immediately.

HTTP Response codes

SFS uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, the token has expired, etc.). Codes in the 5xx range indicate an error with our servers.

General responses to API requests

Status Meaning Description Schema
200 OK The request has been successful Dependent on request
401 Unauthorized The auth token is invalid or not present Error
403 Forbidden The requested operation is not authorized for your token Error
412 Precondition failed For POST requests, the 'If-Match' header is missing Error
429 Too Many Requests The request rate limit has been reached Error
500 Internal server error Internal server error Error
503 Service unavailable Service unavailable Error

POST request precondition

For any modifying calls (POST, PUT, PATCH, DELETE) there is a mandatory If-Match request header. The purpose of this is to make sure you are modifying the most recent version of the proposal. This header is a string that represents a date time object.

The value for this can be retrieved from the ETag response header from the initial proposal creation, or by making a GET request to the proposal endpoint.

Here is an example of where you can capture your ETag when testing in Postman:

ETag Upload

Hint

  • The If-Match request header is not needed for the initial proposal creation call

Request IDs

Each API request has an associated request identifier. You can find this value in the response headers, under X-B2B-TRACE-ID. You can also find request identifiers in the Error object of unsuccessful requests. If you provide this request identifier when contacting SFS it will allow us to debug and help you as quickly as possible.

Rate limiting

There is a limit of 100 requests per minute, enforced at the connecting IP address level. If you reach this limit you will receive an HTTP 429 Too Many Requests response status code. If your request rate falls below this limit then the block will be automatically removed.

Connecting to the API

To be able to connect to our API, there are a few requirements:

If you do not have your Client ID and Client Secret, please contact us.

The generated token is valid for 12 hours and must be sent in the header of every request.

Once you are connected successfully, there are a number of config endpoints that will help you get started.

Configuration