Global Monitoring Process Flow

The Global Monitoring API enables businesses to monitor portfolios of companies and receive notifications about critical changes. This document outlines the key steps to:

• Authenticate
• Set up portfolios
• Manage event rules
• View notifications.

Standard Integration Flow Diagram

1. Authenticate

Before using any of the endpoints, you must authenticate. This ensures you have the necessary permissions to access the data.

Example Request

POST /authenticate

2. Create Monitoring Portfolio

This endpoint is to create the portfolio, it can hold any number of companies that are required to be monitored.

More than one portfolio can be made to group companies under common rules that you wish to monitor them.

Example Request

POST /monitoring/portfolios

Example requestBody

{
  "name": "Test Portfolio",
  "isDefault": false,
  "emails": [
    {
      "firstName": "John",
      "lastName": "Doe",
      "emailAddress": "john.doe@creditsafe.com"
    }
  ],
  "emailSubject": "Creditsafe Monitoring Notification on portfolio {{portfolioName}}",
  "emailLanguage": "en",
  "frequency": "string"
}

Key Details

• The name field is required and should be meaningful for easy identification.
• Upon success, the response will include a unique portfolioId that is essential for future interactions.

Example Response

{
  "correlationId": "14cc64a0-c108-11ea-b9af-06bcc69a383e",
  "portfolioId": 131318,
  "name": "Test Portfolio",
  "isDefault": true
}

3. Update Portfolio Details

To update portfolio details, such as email notifications or other properties, use the following endpoint.

Example Request

PATCH monitoring/portfolios/{portfolioId}

Key Details

• Include the portfolioId in the URL path to identify the portfolio to update.
• The frequency property must be set to "1" to activate email notifications.
• Ensure all required fields are included in the request body.

Example requestBody

{
  "name": "Test Portfolio",
  "emails": [
    {
      "firstName": "John",
      "lastName": "Smith",
      "emailAddress": "john.smith@creditsafe.com"
    }
  ],
  "frequency": "1"
}

Adding Companies to a Portfolio

There are three different ways to add companies to a portfolio:

1. Add Single Company: Add individual companies to the portfolio using their unique identifiers.
2. Import Companies: Upload a file (e.g., .csv) containing multiple companies to add them in bulk.
3. Sync Portfolio: Replace all existing companies in the portfolio with the contents of an uploaded file.

NOTE:
The Sync Portfolio option has a different outcome compared to the other methods. It deletes all previously allocated companies in the portfolio and replaces them with the new file contents. This functionality, along with other additional endpoints, is detailed in the Additional Information tab of the product documentation.

Now that you understand the available methods, proceed to the next section for details on how to add companies to a portfolio.

4. Add Companies to Portfolio

Companies can be added to a portfolio individually or in bulk. Below are the available methods:

1. Add Single Company: Add individual companies to the portfolio using their unique identifiers.
2. Import or Sync Companies: Upload a file (e.g., .csv) containing multiple companies to add them in bulk or replace the existing portfolio contents.

NOTE:
The Import and Sync options, along with detailed guidance on file formats, best practices, and processing considerations, are documented in the Import and Sync Companies section of the product documentation.

Add Single Company

This method allows you to add individual companies to a portfolio using their unique identifiers.

Example Request

POST /monitoring/portfolios/{portfolioId}/companies

Example requestBody

{
  "id": "GB-0-12345678",
  "personalReference": "Creditsafe Group",
  "freeText": "Collection of Creditsafe Companies",
  "personalLimit": ""
}

Key Details

• All properties in the requestBody are required. If there is no data for a property, you must pass an empty string ("").
• The id field represents the unique identifier for the company being added.
• The personalReference and freeText fields are intended for internal references and notes, allowing you to track additional information about the company.
• personalLimit:
  It is important to note that the personalLimit is not part of the credit limit associated with the company. Instead, it represents a limit you set internally for your own record-keeping purposes.

By using this endpoint, you can efficiently add individual companies to your portfolio, tailoring the information to suit your specific requirements.

5. View Available Event Rules

When applying event rules to a portfolio for monitoring, it is important to understand which rules are applicable to the companies within that portfolio. There are multiple ways to view available event rules, depending on your specific needs:

1. Targeted Approach for a Portfolio:
   The most efficient way to view event rules is by calling the endpoint that provides a filtered list of rules specifically applicable to the companies in your portfolio. This ensures that only relevant rules are displayed, saving time and effort in managing and understanding the available options.

   Endpoint

   GET /monitoring/portfolios/{portfolioId}/eventRules

By using this endpoint:

• The API automatically filters out any rules that are not relevant to the companies in the portfolio.
• You can focus on the rules that are directly applicable, streamlining the process of setting up event notifications.

Example Response

[
  {
    "isActive": 0,
    "ruleCode": 101,
    "ruleCountryCode": "XX",
    "ruleType": 4,
    "ruleTypeName": "Rating band change - 3 input",
    "name": "International Rating |{2} Return Band(A-E) |Reduce by {0} Band(s) OR Less than Band {1}",
    "param0": "1",
    "param1": "A"
  },
  {
    "isActive": 0,
    "ruleCode": 102,
    "ruleCountryCode": "XX",
    "ruleType": 5,
    "ruleTypeName": "Limit value change - 3 input",
    "name": "Limit |{0} Any |Reduce by {1}% OR Less than {2}",
    "param0": "True"
  }
]

Explanation of Properties

• isActive: Indicates the status of the rule. 0 means inactive, and 1 means active.
• ruleCode: Unique identifier for the rule. Codes starting with 10 are global rules that apply universally to all countries.
• ruleCountryCode: Represents the country code for the rule. XX indicates global applicability, while specific country codes (e.g., GB for Great Britain) apply to companies in that country.
• ruleType: Numerical representation of the rule type.
• ruleTypeName: Descriptive name of the rule type, making it easier to understand the event being monitored.
• name: Describes the event notification triggers for the rule, including any required parameters (param0, param1, param2).

NOTE: For additional information on rules that require parameters (param0, param1, param2), refer to the Special Event Rules Documentation.

2. View Rules for a Specific Country: If you want to see the rules available for a particular country included in your portfolio, you can use the following endpoint:

Endpoint

GET /monitoring/portfolios/{portfolioId}/eventRules/{countryCode}

By specifying the countryCode in the URL path (e.g., GB for Great Britain), the API will return a list of rules applicable to companies in that specific country. This approach is useful when you need to focus on country-specific rules.

3. View All Available Rules: For a more comprehensive view, you can call the endpoint that provides a complete list of all available rules. This method is less targeted but allows you to explore all rules, regardless of their applicability to your portfolio.

Endpoint

GET /monitoring/eventRules

This endpoint is ideal if you want to review the full range of event rules supported by the API.

Key Recommendations

• For most use cases, the Targeted Approach for a Portfolio is recommended, as it filters out irrelevant rules and provides a streamlined experience.
• Use the View Rules for a Specific Country endpoint when you need to focus on rules for a particular country within your portfolio.
• Refer to the Special Event Rules Documentation for detailed guidance on rules requiring parameters (param0, param1, param2) and how to configure them effectively.

By leveraging these endpoints, you can efficiently manage event rules for your portfolio, ensuring that your monitoring setup is tailored to your specific requirements.

6. Activate Event Rules

Activating event rules for a portfolio is a critical step in setting up monitoring. This section outlines the best practices and methods for activating rules, ensuring they are applied correctly to your portfolio.

Endpoint

PUT /monitoring/portfolios/{portfolioId}/eventRules/{countryCode}

Key Details

• Replace {portfolioId} with the unique identifier of the portfolio.
• Replace {countryCode} with: -XX for Global Rules (rules that apply to all countries in the portfolio). -A specific country code (e.g., FR for France) for Local Rules.

Example requestBody

[
  {
    "ruleCode": 101,
    "isActive": 1,
    "param0": "",
    "param1": "any"
  }
]

Explanation of Properties

• ruleCode: The unique identifier for the rule you want to activate.
• isActive: Set to 1 to activate the rule or 0 to deactivate it.
• param0, param1, param2: Include these parameters only if required by the rule. For rules that do not require parameters, omit these fields.

Global vs. Local Rules

1. Global Rules:
   • Use XX as the countryCode in the endpoint.
   • Global rules apply to all countries in the portfolio.
   • Example Global Rule Codes: 101, 102, 104, 105, 106, 107.

Example Global Rule Endpoint:

PUT /monitoring/portfolios/{portfolioId}/eventRules/XX

2. Local Rules:

   • Use the specific country code (e.g., FR for France) in the endpoint.
   • Local rules apply only to companies in the specified country.

Example Local Rule Endpoint:

PUT /monitoring/portfolios/{portfolioId}/eventRules/FR

Important:
It is not possible to use a Global Rule (XX) with a Local Rule endpoint. Doing so will result in an error response.

Best Practices for Activating Rules

1. Submit the Full List of Rules:
   When updating event rules, always resubmit the entire list of rules (both existing and new). This ensures that all rules are correctly applied and functioning as intended.

2. Verify Changes: After activating or updating rules, verify the active rules for your portfolio by calling the View Available Event Rules endpoint:

3. Use Parameters Where Required: Some rules require additional parameters (param0, param1, param2) to function. For detailed guidance on parameterized rules, refer to the Special Event Rules Documentation.

Example Workflow

1. Retrieve Applicable Rules:
   Use the View Available Event Rules endpoint to get a filtered list of rules for your portfolio.

2. Prepare the Request Body:
   Include the ruleCode, isActive, and any required parameters (param0, param1, param2) in the request body.

3. Activate Rules:
   Send a PUT request to the appropriate endpoint (XX for global rules or a specific country code for local rules).

4. Verify Activation:
   Call the View Available Event Rules endpoint again to confirm that the rules have been successfully activated.

Additional Notes

• Error Handling:
  If an error occurs during activation, review the request body and ensure all required fields are included. For rules requiring parameters, verify that the correct values are provided.

• Comprehensive Updates:
  Always include all rules (existing and new) in the request body to avoid unintentionally deactivating rules.

By following these best practices and using the provided endpoints effectively, you can tailor the monitoring capabilities of the API to meet your specific business requirements.

7. View Notification Events

The Global Monitoring API provides multiple ways to view notification events, allowing you to track changes and updates across portfolios and companies. This section outlines the available endpoints and their use cases.

1. View Notification Events for a Portfolio

To view all notification events that have occurred within a specific portfolio, use the following endpoint:

Endpoint

GET /monitoring/portfolios/{portfolioId}/notificationEvents

Key Details

• Replace {portfolioId} with the unique identifier of the portfolio.
• This endpoint provides a comprehensive list of all notification events for the specified portfolio, including:
  • Credit limit changes
  • Company updates
  • Other critical information related to the companies in the portfolio

Example Use Case

This endpoint is ideal for monitoring changes within a specific portfolio, enabling you to stay updated on relevant events and respond to developments in a timely manner.

2. View All Notification Events Across Portfolios

To view all notification events across all portfolios, use the following endpoint:

Endpoint

GET /monitoring/notificationEvents

Key Details

• This endpoint retrieves a consolidated list of all notification events triggered by enabled rules across all portfolios.
• It is useful for gaining a high-level overview of all monitored activities without focusing on a single portfolio.

Example Use Case

Use this endpoint to monitor global changes across your entire portfolio structure, ensuring no critical updates are missed.

3. View Notification Events for a Specific Company

To view notification events for a specific company, use the following endpoint:

Endpoint

GET /monitoring/companies/{id}/events

Key Details

• Replace {id} with the unique identifier of the company.
• The company must be part of at least one portfolio to retrieve its events.
• This endpoint provides detailed event information specific to the company, such as:
  • Credit score changes
  • Status updates
  • Other company-specific notifications

Example Use Case

This endpoint is ideal for tracking changes and updates for a specific company, allowing you to focus on individual entities within your portfolios.

Best Practices for Viewing Notification Events

1. Use Portfolio-Specific Events for Targeted Monitoring:
   Start with the portfolio-specific endpoint to focus on changes relevant to a particular portfolio.

2. Leverage Global Events for a Broader View: Use the all-events endpoint to gain a comprehensive overview of all notifications across your portfolios.

3. Drill Down to Company-Level Events When Needed: For detailed insights into a specific company, use the company-specific endpoint.

4. Verify Enabled Rules: Ensure that the appropriate event rules are enabled for your portfolios to capture the desired notifications. Refer to the Activate Event Rules section for guidance.

Example Workflow

1. Monitor Portfolio Events: Use the portfolio-specific endpoint to track changes within a specific portfolio:

GET /monitoring/portfolios/{portfolioId}/notificationEvents

2. Review All Events: Use the global events endpoint to review all notifications across portfolios:

GET /monitoring/notificationEvents

3. Focus on a Specific Company: Use the company-specific endpoint to track updates for an individual company:

GET /monitoring/companies/{id}/events

By leveraging these endpoints effectively, you can stay informed about critical changes and updates, ensuring that your monitoring setup is tailored to your business needs.

8. Reset All Event Rules to Default

Resetting all event rules to their default state is a significant action that disables all event monitoring for the specified portfolio. This endpoint is useful if you want to temporarily pause monitoring or start with a clean slate.

Endpoint

PUT /monitoring/portfolios/{portfolioId}/eventRules/setDefault

Key Details

• Replace {portfolioId} with the unique identifier of the portfolio.
• This endpoint sets all event rules within the portfolio to Off, effectively disabling all event monitoring for the companies in the portfolio.

Example Use Case

• Pause Monitoring: Temporarily disable all event rules for a portfolio while retaining the portfolio structure.
• Start Fresh: Reset all rules to their default state before reconfiguring and activating specific event rules.

Important Notes

1. Significant Action:
   Resetting all event rules will disable monitoring for all companies in the portfolio. Use this endpoint judiciously and ensure you understand its implications.

2. Reactivation Required:
   After resetting, you will need to manually activate the desired event rules again. Refer to the Activate Event Rules section for guidance.

Example Workflow

1. Reset Rules: Send a PUT request to the endpoint to reset all event rules for the portfolio:

PUT /monitoring/portfolios/{portfolioId}/eventRules/setDefault

2. Verify Reset: Use the View Available Event Rules endpoint to confirm that all rules have been disabled:

GET /monitoring/portfolios/{portfolioId}/eventRules

3. Reconfigure Rules: After resetting, reconfigure and activate the required rules using the Activate Event Rules endpoint.

By using this endpoint effectively, you can manage your portfolio's event rules with flexibility, ensuring that your monitoring setup aligns with your business needs.