Creditsafe Connect

Creditsafe Connect

β˜…
β˜…
β˜…
β˜…
β˜…
(0 reviews)

Monitoring Companies

Before you can Monitor companies you must have obtained the following:

  • A valid Authorization token
  • A Company's Connect ID
  • Access to Monitoring

    Please be aware currently Webhooks are not supported in Creditsafe Connect

Terminology

  • Portfolio - A collection of companies. e.g. International Suppliers - Low Risk
  • Rules - Portfolio specific parameters which can be monitored for company changes e.g. Credit Rating change
  • Events - changes to a company in your Portfolio that meet the monitoring parameters

Create a portfolio and manage companies in a portfolio

To create a portfolio:
Send a POST request to
https://connect.creditsafe.com/v1/monitoring/portfolios

To add a company to a portfolio:
Send a POST request to https://connect.creditsafe.com/v1/monitoring/portfolios/{portfolioId}/companies

To add bulk of companies to a portfolio:
Send a POST request to
https://connect.creditsafe.com/v1/monitoring/portfolios/{portfolioId}/companies/import

To update a company in a portfolio:
Send a PATCH request to
https://connect.creditsafe.com/v1/monitoring/portfolios/{portfolioId/companies/{id}

To remove a company from a portfolio:
Send a DELETE request to
https://connect.creditsafe.com/v1/monitoring/portfolios/{portfolioId}/companies/{id}

To copy companies from one portfolio to another:
Send a POST request to
https://connect.creditsafe.com/v1/monitoring/portfolios/{portfolioId}/companies/copy

To move companies from one portfolio to another:
Send a POST request to
https://connect.creditsafe.com/v1/monitoring/portfolios/{portfolioId}/companies/remove

To delete multiple companies from a porfolio:
Send a PATCH request to
https://connect.creditsafe.com/v1/monitoring/portfolios/{portfolioId}/companies/clear

To share portfolio permissions to other users within the customer:
Send a PATCH request to
https://connect.creditsafe.com/v1/monitoring/portfolios/{portfolioId}/sharingPermissions

Configure event rules on a portfolio

To see a list of rules available to configure on your portfolio:
Send a GET request to
https://connect.creditsafe.com/v1/monitoring/eventRules

Rules with 'ruleCountryCode' - XX are global rules that could be applied across the companies in the portfolio.

Rules with specific country code are local rules defined for the country.

To filter the rules based on the country code:
Send a GET request to
https://connect.creditsafe.com/v1/monitoring/eventRules/{countryCode}

The above api would return the global rules along with the rules specific to the countryCode in the request

To configure an event for a portfolio:
Send a PUT request to
https://connect.creditsafe.com/v1/monitoring/portfolios/{portfolioId}/eventRules/{countryCode}

To reset the event rules on a portfolio to default settings:
Send a PUT request to
https://connect.creditsafe.com/v1/monitoring/portfolios/{portfolioId}/eventRules/setDefault

View details of a portfolio

To view a portfolio:
Send a GET request to
https://connect.creditsafe.com/v1/monitoring/portfolios/{portfolioId}

To get a list of distinct countries monitored within a portfolio:
Send a GET request to
https://connect.creditsafe.com/v1/monitoring/portfolios/{portfolioId}/countries

To view the list of companies in a portfolio:
Send a GET request to
https://connect.creditsafe.com/v1/monitoring/portfolios/{portfolioId}/companies

To view the list of events configured in a portfolio:
Send a GET request to
https://connect.creditsafe.com/v1/monitoring/portfolios/{portfolioId}/notificationEvents

The below section details the format of the input and possible list of error responses for the available monitoring api's in detail:

Creating a Portfolio

POST https://connect.creditsafe.com/v1/monitoring/portfolios
HEADERS

Key: Authorization, Value: authToken

Key: Content-Type, Value: application/json
{
  "name": "portfolioName",
  "isDefault": false,

  "emails": [

    {

      "firstName": "Bob,",

      "lastName": "Smith,",

      "emailAddress": "bob.smith@adomain.com"

    }

  ],

  "emailSubject": "Notification Subject",

  "emailLanguage": "en",

  "frequency": "DailyDigest",

  "webhookUrl": "https://www.mycompanydomain.co.uk/incoming/ggs.ashx",

  "webhookEnabled": true

}

Possible Error Response:

400 - Bad Request:

Returns a bad request error in case of any violations in the request sent.

{
    "details": "Error validating JSON. Error: - Missing required field 'name'",
    "correlationId": "c7ed5060-1418-11e9-88cb-0677963223fe",
    "message": "Bad request"
}

403 - Forbidden:

Returns 403, in case of missing Authorization header.
{ "error": "Policy 360079: The message does not contain the Authorization header" }

Returns 403, in case of invalid Authorization header.
{ "error": "Policy 360079: JWT is not valid" }

Add companies to portfolio

POST https://connect.creditsafe.com/v1/monitoring/portfolios/{portfolioId}/companies

HEADERS
Key: Authorization, Value: authToken
Key: Content-Type, Value: application/json

{
  "id": "companyId to add",  
  "personalReference": "Some text",
  "freeText": "Some useful test",
  "personalLimit": "40"

}

Possible Error Response:

403 - Forbidden:

Returns 403, in case of missing Authorization header.
{ "error": "Policy 360079: The message does not contain the Authorization header" }

Returns 403, in case of invalid Authorization header.
{ "error": "Policy 360079: JWT is not valid" }

404 - Portfolio not found:

Returns 404 error, in case if the portfolio couldn't be found.

{
    "correlationId": "976eb3a0-1429-11e9-88cb-0677963223fe",
    "message": "Portfolios not found"
}

400 - Bad Request:

Returns a bad request error in case of any violations in the request sent
like the one below:

{
    "details": "Error validating JSON. Error: - Missing required field 'id'",
    "correlationId": "c7ed5060-1418-11e9-88cb-0677963223fe",
    "message": "Bad request"
}

Returns a bad request error in case if the company id could not be found:

{
    "correlationId": "f51b9130-1429-11e9-88cb-0677963223fe",
    "message": "Company ES001-1-43677678 not found"
}

Conflict - 409:

Returns 409 error, if a company that already exist is tried to be added to the portfolio
again.

{
    "correlationId": "2cdb1cd0-142a-11e9-88cb-0677963223fe",
    "message": "Company already exists"
}

Adding multiple companies to your portfolio via CSV file

POST https://connect.creditsafe.com/v1/monitoring/portfolios/{portfolioId}/import

HEADERS
Key: Authorization, Value: authToken

Body: multipart/form-data

CSV file to be uploaded that has the list of companies to be added to the portfolio
email - optional. Mail address that summaries the number of companies imported successfully
and number of companies failed to be imported due to bad format or duplicates.

CSV File details and format:

The uploaded CSV file can have the values defined for the fields in one of the below combinations, as either comma separated or semicolon separated:
{Connect Id}, {Reference}, {Free Text}, {Personal limit}
{Company Number}, {Country Code}, {Reference}, {Free Text}, {Personal limit}
{Connect Id}
{Company Number}, {Country Code}

The fields - Reference, Free Text and Personal limit are optional.
To import a company to a portfolio, the mandatory fields are either connect id or company number along with country code.

The data format in the csv file should look like one of the below:

ES001-1-436776;;;Test;Free Text;40
;835695382;BE;Test;Free Text;40
ES001-1-436776;;;;
;835695382;BE;

The order of the fields shouldn't be changed and if the optional fields aren't used they should still be separated by comma or semicolon.
The connect id and the company number could be fetched from the search api.

Possible Error Response:

403 - Forbidden:

Returns 403, in case of missing Authorization header.
{ "error": "Policy 360079: The message does not contain the Authorization header" }

Returns 403, in case of invalid Authorization header.
{ "error": "Policy 360079: JWT is not valid" }

Synchronise the companies in the portfolio with the one's defined in CSV file

The below api facilitates managing the companies in the portfolio with the one in csv file.
The api deletes the companies from the portfolio that aren't in the csv file and adds the companies
in csv file to the portfolio

POST https://connect.creditsafe.com/v1/monitoring/portfolios/{portfolioId}/sync
HEADERS
Key: Authorization, Value: authToken
Body: multipart/form-data

The csv file format is same as the api - https://connect.creditsafe.com/v1/monitoring/portfolios/{portfolioId}/import

Possible Error Response:

403 - Forbidden:

Returns 403, in case of missing Authorization header.
{ "error": "Policy 360079: The message does not contain the Authorization header" }

Returns 403, in case of invalid Authorization header.
{ "error": "Policy 360079: JWT is not valid" }

Copy companies from one portfolio to single or multiple portfolios

POST https://connect.creditsafe.com/v1/monitoring/portfolios/{portfolioId}/copy

HEADERS
Key: Authorization, Value: authToken
Key: Content-Type, Value: application/json

Query Parameter - copyAll is of type boolean and is an optional param. The default value is False.

When copyAll is set to True, it copies all companies from the portfolio in the uri param to the list of
portfolios mentioned in the request body.

When copyAll is set to False, it copies the companies mentioned in the request body to the list of portfolios
on the request body.

Below is a sample request to copy few companies from the portfolio in the uri param
to the list of portfolios in the request body:

Query Param - copyAll is set to False in this case.

{
  "portfolios": [
    196854,
    197369
  ],
  "companies": [
    {
      "id": "BE-X-733313367"
    },
    {
      "id": "BE-X-868222848"
    },
    {
      "id": "BE-X-835695382"
    }
  ]
}

Below is the sample request to copy all companies from a portfolio in the uri param
to the list of portfolios in the request body:

Query Param - copyAll is set to True in this case.

{
  "portfolios": [
    196854,
    197369
  ],
  "companies": [
  ]
}

Possible Error Response:

Forbidden - 403:

Returns 403 error, in case of missing Authorization header like the one below:

{
    "error": "Policy 360079: The message does not contain the Authorization header"
}

Returns 403 error, in case of invalid Authorization header like the one below:

{
    "error": "Policy 360079: JWT is not valid"
}

Move companies from one portfolio to single or multiple portfolios

POST https://connect.creditsafe.com/v1/monitoring/portfolios/{portfolioId}/remove

HEADERS
Key: Authorization, Value: authToken
Key: Content-Type, Value: application/json

Query Parameter - removeAll is of type boolean and is an optional param. The default value is False.

When removeAll is set to True, all companies from the portfolio in the uri param are moved to the list of
portfolios mentioned in the request body and deleted from the portfolio in the uri param.

When removeAll is set to False, it moves the companies mentioned in the request body to the list of portfolios
on the request body and deletes the companies from the portfolio in the uri param.

Below is a sample request to move few companies from the portfolio in the uri param
to the list of portfolios in the request body:

Query Param - removeAll is set to False in this case.

{
  "portfolios": [
    196854,
    197369
  ],
  "companies": [
    {
      "id": "BE-X-733313367"
    },
    {
      "id": "BE-X-868222848"
    },
    {
      "id": "BE-X-835695382"
    }
  ]
}

Below is the sample request to move all companies from a portfolio in the uri param
to the list of portfolios in the request body:

Query Param - removeAll is set to True in this case.

{
  "portfolios": [
    196854,
    197369
  ],
  "companies": [
  ]
}

Possible Error Response:

Forbidden - 403:

Returns 403 error, in case of missing Authorization header like the one below:

{
    "error": "Policy 360079: The message does not contain the Authorization header"
}

Returns 403 error, in case of invalid Authorization header like the one below:

{
    "error": "Policy 360079: JWT is not valid"
}

To delete companies from current portfolio

PATCH https://connect.creditsafe.com/v1/monitoring/portfolios/{portfolioId}/companies/clear

HEADERS
Key: Authorization, Value: authToken
Key: Content-Type, Value: application/json

Query Parameter - clearAll is of type boolean and is an optional param. The default value is False.

When clearAll is set to True, all companies in the current portfolio are deleted and companies list
in the request body must be empty.

When clearAll is set to False, only the companies defined in the request body will be deleted from
the current portfolio.

Below is a sample request to delete few companies from the current portfolio:
Query Param - clearAll is set to False.

{
  "companies": [
    "BE-X-733313367",
    "BE-X-868222848"
  ]
}

Below is a sample request to delete all companies from the current portfolio:
Query Param - clearAll is set to True.

{
  "companies": [
  ]
}

Possible Error Response:

Forbidden - 403:

Returns 403 error, in case of missing Authorization header like the one below:

{
    "error": "Policy 360079: The message does not contain the Authorization header"
}

Returns 403 error, in case of invalid Authorization header like the one below:

{
    "error": "Policy 360079: JWT is not valid"
}

To Update a company details defined in a portfolio

PATCH https://connect.creditsafe.com/v1/monitoring/portfolios/{portfolioId}/companies/{id}
HEADERS
Key: Authorization, Value: authToken
Key: Content-Type, Value: application/json

{
  "personalReference": "Some text",
  "freeText": "Some useful test",
  "personalLimit": "40"
}

Possible Error Response:

Forbidden - 403:

Returns 403 error, in case of missing Authorization header like the one below:

{
    "error": "Policy 360079: The message does not contain the Authorization header"
}

Returns 403 error, in case of invalid Authorization header like the one below:

{
    "error": "Policy 360079: JWT is not valid"
}

404 - Portfolio not found:

Returns a 404 error, if the portfolio sent in the request could not be found.

{
    "correlationId": "b2e61a60-17fd-11e9-a1cb-025d579e1fcc",
    "message": "Portfolios not found"
}

Returns a 404 error, if the company id sent in the request could not be found.

{
    "correlationId": "cd7396a0-17fd-11e9-a1cb-025d579e1fcc",
    "message": "Company {company id sent in the request} not found"
}

Configuring the rules on portfolio

Monitoring rules control the conditions under which companies in a portfolio will be treated as changed or not by the company listing calls. Rules are set per portfolio and apply to all companies in the portfolio they have been set in. All rules are treated as if there was an β€œOR” relationship between them meaning that at least one of them has to be met for the monitoring event to be taken into account.

An event is generated when a company in your portfolio changes in according with a rule set on the portfolio.

I.e.

If a company that is in your portfolio has a Credit Limit change, and your portfolio has the Credit Limit change rule activated, then a notification will be raised.

To see available rules that you can configure on your portfolio

GET https://connect.creditsafe.com/v1/monitoring/eventRules
HEADERS
Key: Authorization, Value: authToken
Key: Content-Type, Value: application/json
GET https://connect.creditsafe.com/v1/monitoring/portfolios/{portfolioId}/eventRules

HEADERS

Key: Authorization, Value: authToken

Key: Content-Type, Value: application/json

Use the following process to set the rules you want to monitor

PUT 
[
      {
        "ruleCode": 107,
        "isActive": 0
    }
]

Retrieving latest changes

By portfolio:

https://connect.creditsafe.com/v1/monitoring/portfolios/{portfolioId}/notificationEvents

HEADERS
Key: Authorization, Value: authToken
Key: Content-Type, Value: application/json

All Changes

https://connect.creditsafe.com/v1/monitoring/notificationEvents

HEADERS

Key: Authorization, Value: authToken

Key: Content-Type, Value: application/json

Adding companies to your portfolio

POST https://connect.creditsafe.com/v1/monitoring/portfolios/{portfolioId}/companies
HEADERS
Key: Authorization, Value: authToken
Key: Content-Type, Value: application/json
{
  "id": "companyId to add",
  "personalReference": "Some text",
  "includeBranches": true,
  "freeText": "Some useful test",
  "personalLimit": "40"
}

To see all companies in your Portfolio

HEADERS
Key: Authorization, Value: authToken
Key: Content-Type, Value: application/json
https://connect.creditsafe.com/v1/monitoring/portfolios/{portfolioId}/companies

To see a list of all your Portfolios

HEADERS
Key: Authorization, Value: authToken
Key: Content-Type, Value: application/json
GET https://connect.creditsafe.com/v1/monitoring/portfolios

Setting a portfolio back to default

https://connect.creditsafe.com/v1/monitoring/portfolios/{portfolioId}/eventRules/setDefault

How to enable monitoring of International Credit Score

The International Credit Score is an A - E score that indicates the Creditworthiness of a Company. To monitor changes in the Score, apply rule 101, which is a 2 parameter input.

Parameter 1 represents how many bandings a company would have to change by to raise a Notification Event.

Parameter 2 represents the minimum band the company can be in, before a Notification Event is generated

https://connect.creditsafe.com/v1/monitoring/portfolios/{portfolioId}/eventRules/XX
HEADERS
Key: Authorization, Value: authToken
Key: Content-Type, Value: application/json

[

      {

        "ruleCode": 101,
        "isActive": 1,
        "param0": "1",
        "param1": "C"

    }

]

##Understanding Event Types

|Rule Type | Rule|

|----|-----|

|1 |Bool

|2 |Value change - 1 input|

|3 |Value change in range - 2 inputs|

|4 |Rating band change - 3 input|

|5 |Limit value change - 3 input|

|6 |Rating change - 2 inputs|

|7 |Rating change +/- percentage or gt value - 3 inputs|

|8 |Change greater than -percent or lt value - 2 inputs|

|9 |Change greater than -percent - 1 input|

|10 |Change greater than -+/- percent - 1 input|


Reviews