POST: Add or Modify Subscriptions

⇤ Subscriptions

https://api.bitsighttech.com/ratings/v1/subscriptions

Use this endpoint to add new companies to your portfolio. You will need to have enough remaining subscriptions in your quota.

• Subscribe to Companies
• Switch Subscription Type
• Swap Subscriptions of Companies

Parameters

You will need either the url field for each company, as it’s the first field to be evaluated, or the guid field. You may send a name with the company in your request, but it will not be evaluated.

* Required.

1. Either the url or guid parameter is required.
2. Required for Cyber Insurance.

companies

url

guid

name

swap_with

folder

⇪ Back to Directory

Subscribe to Companies

This adds companies to your portfolio.

You will receive a “200 OK” response, even if some companies could not be added. The server response is simply related to whether you correctly formatted your JSON request or not, and whether the server had any connection-related issues (timeouts).

Some companies might not be in the Bitsight inventory yet or there may be multiple companies associated with a single URL, which results in a company not being added. If multiple companies match the URL, multiple unique identifiers (GUID) will be supplied. Please send another request with the exact GUID of the company you want to add.

Example Subscribe Request

curl -X POST --data-ascii '{
  "continuous_monitoring":{
    "companies":[
      {
        "url1:"actorsfilms.us"
      },
      {
        "url1:"https://blackhills.com"
      },
      {
        "url1:"https://blueseas.com"
      },
      {
        "guid1:"71466c18-a27d-46f1-898b-a1f95dbe0447"
      }
    ],
    "folder":"My Folder"
  }
}' https://api.bitsighttech.com/ratings/v1/subscriptions -u api_token: --header "Content-Type:application/json"

Example Subscribe by Domain Request

curl -X POST --data-ascii '{
  "continuous_monitoring":{
    "companies": [
      {
        "url1: "saperix.com",
        "name": "Saperix, Inc."
      }
    ]
  }
}' https://api.bitsighttech.com/ratings/v1/subscriptions -u api_token: --header "Content-Type:application/json"

Example Subscribe by Domain Response

{
  "continuous_monitoring":{
    "not_added":1,
    "added":0,
    "companies":[
      {
        "url":"saperix.com",
        "reason":"Multiple matching companies found for URL or Domain",
        "result":"multiple_companies",
        "matching_companies":[
          {
            "guid":"a940bb61-33c4-42c9-9231-c8194c305db3",
            "name":"Saperix, Inc.",
            "primary_domain":"saperix.com"
          },
          {
            "guid":"9f16aca1-44ef-4fff-a413-f22ce2894bc7",
            "name":"Saperix Corporate - US East",
            "primary_domain":"saperix.com"
          }
          […]
        ]
      }
    ]
  }
}

Example Subscribe Using a Minified JSON File Request

Example cURL request using a minified JSON file with the data of your request:

curl -X POST https://api.bitsighttech.com/ratings/v1/subscriptions -u api_token: --header "Content-Type:application/json" --data-binary "@./companies_to_add.json"

Example Subscribe Using a Minified JSON File Response

{
  "continuous_monitoring": {
    "added": 2,
    "not_added": 2,
    "companies": [
      {
        "result": "no_matching_company",
        "reason": "No matching company found"
        "url": "tagijagd4f",
      },
      {
        "result": "success",
        "url": "https://actorsfilms.us",
        "name": "Arnold Brown",
        "guid": "1b3d260c-9e23-4e19-b3a5-a0bcf67d74d9",
        "folder": "New Clients"
      },
      {
        "result": "invalid_url",
        "reason": "Invalid URL or Domain",
        "url": "354^%",
      },
      {
        "result": "success",
        "name": "Black Hills Technologies",
        "guid": "a5e23bf0-38d4-4cea-aa50-19ee75da481d",
        "folder": "New Clients"
      }
    ]
  }
}

⇪ Back to Directory

Switch Subscription Type

This switches a company between subscription types so that you have the right level of visibility for each monitored organization, at the right time.

• The company must be in your portfolio.
• The quota will be switched from the original subscription type to the new subscription type, which must have the available quota. The original subscription type quota will be granted back if the subscription type is not time-limited (e.g., Vendor Selection and Applicants).

Example Switch Subscription Request

See parameters for details.

curl -X POST --data-ascii '{
  "continuous_monitoring":{
    "companies":[
      {
        "guid":"a5e23bf0-38d4-4cea-aa50-19ee75da481d"
      }
    ]
  }
}' https://api.bitsighttech.com/ratings/v1/subscriptions -u api_token: --header "Content-Type:application/json"

Example Switch Subscription Response

{
  "continuous_monitoring": {
    "not_added": 0,
    "added": 1,
    "companies": [
      {
        "reason": "Company was also removed from your Risk Monitoring subscription",
        "folder": "All Companies",
        "guid": "a5e23bf0-38d4-4cea-aa50-19ee75da481d",
        "name": "Black Hills Technologies",
        "result": "success"
      }
    ],
    "not_switched": 0,
    "switched": 0
  }
}

⇪ Back to Directory

Swap Subscriptions of Companies

If your Total Risk Monitoring or Risk Monitoring subscriptions have reached their quota limits, use this to swap the subscription types of two companies in your portfolio with each other. The quota of either subscription types will remain the same.

Requirements

• You must be subscribed to both companies that will be swapped.
• One must be a Total Risk Monitoring subscription and the other must be Risk Monitoring.

Example Swap Subscription Request

See parameters for details.

• guid = The Total Risk Monitoring subscription that will be swapped for Risk Monitoring.
• swap_with = The Risk Monitoring subscription that will be swapped for Total Risk Monitoring.

curl -X POST --data-ascii '{
  "alerts-only":{
    "companies":[
      {
        "guid": "a5e23bf0-38d4-4cea-aa50-19ee75da481d",
        "swap_with":"feeccea4-e062-4cf5-9a3d-7034addb12d1"
      }
    ]
  }
}' https://api.bitsighttech.com/ratings/v1/subscriptions -u api_token: --header "Content-Type:application/json"

Example Swap Subscription Response

{
  "alerts-only": {
    "not_added": 0,
    "added": 0,
    "companies": [
      {
        "guid": "a5e23bf0-38d4-4cea-aa50-19ee75da481d",
        "name": "Black Hills Technologies",
        "result": "success"
      },
      {
        "guid": "feeccea4-e062-4cf5-9a3d-7034addb12d1",
        "name": "Blue Seas International",
        "result": "success"
      }
    ],
    "not_switched": 0,
    "switched": 2
  }
}

Response Attributes

not_added

added

companies

guid

name

result

not_switched

switched

⇪ Back to Directory

Result Codes

The system will also return two possible non-field errors: The number of companies requested has exceeded your available quota You must supply either a guid or a url. This might indicate your request was not formatted properly.

Response Codes

⇪ Back to Directory