Security Performance Management
Continuous Monitoring
Cyber Insurance
National Cybersecurity

Articles in this section

POST: Add or Modify Subscriptions

Avatar
Ingrid
Follow
  • March 21, 2022: POST: Bulk Subscriptions [/v1/subscriptions/bulk] is now available.
  • May 18, 2020: Added directory to each functionality.

⇤ 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.

POST requests must be sent in JSON format, but the response can be received in either JSON or XML.

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.
Parameter Description Values
Subscription Type
Body		 Identify the subscription type to use. [String] Subscription slug name [subscription_type]. See subscription types. 
companies
Body		 Company details to modify. [Array] Comma-separated company detail objects.
  
url
Body1		 Identify the company. [String] Domain name.
Example: saperix.com
 
guid
Body1		 Identify the company. [String] Company unique identifier [entity_guid]. See GET: Portfolio Details. 
name
Body		 Assign a name to organize requests. This is not used by the API. [String] The intended name for the company. 
swap_with
Body		 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.
 [String] Company unique identifiers [company_guid]. See GET: Portfolio 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.
 
folder
Body2		 Assign a name for the destination folder. [String]

⇪ Back to Directory

Subscribe to Companies

POST: Bulk Subscribe [/v1/subscriptions/bulk] is now available.

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

Field Description
Subscription Type
Object		 Details of the subscription swap. This value is always alerts-only when swapping subscriptions.
  
not_added
Integer		 The number of companies that were not added to your portfolio. This value is always 0 when swapping subscriptions. 
added
Integer		 The number of companies that were added to your portfolio. This value is always 0 when swapping subscriptions. 
companies
Array		 The swapped companies with the Total Risk Monitoring subscription listed first.
  
guid
String [entity_guid]		 The unique identifier of the company that was swapped. 
name
String		 The name of the company that was swapped. 
result
String		 The request results. See the result codes. 
not_switched
Integer		 The number of companies that were not swapped. 
switched
Integer		 The number of companies that were swapped.

⇪ Back to Directory

Result Codes

Returned Messages via result Field Description
success The operation was successful.
no_matching_company The requested company is not a part of our active database of companies or the GUID did not return a match.
subscription_exists This company is already part of your subscription of the specified type.
company_exists_in_folder This company already exists in the folder sent with your request.
invalid_url An invalid or incomplete URL or domain was supplied in the “url” field for a company, like “ww.website.c” or “asbdffdf.”
multiple_companies More than one company matched the domain or URL passed in. Submit another API request and add the specific company.
error_adding_company There was an internal error. A support email was automatically generated for your request.
cannot_swap_invalid_guid The swap_with parameter was used and one of the companies was invalid or did not meet swapping requirements.

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

Code Description
200 – Okay The request was parsed successfully and attempts were made to add the requested companies to the customer’s portfolio.
400 – Bad Request The request contained an invalid input (incorrect field name or a company didn't have a specified guid or url). No companies were added to your portfolio.
401 – Unauthorized The authorization header didn't contain a valid API token.
404 – Not Found This is returned if the endpoint URL is incorrect or the user’s API token was valid but they don't have permission to access the requested resource (i.e. they are not a customer admin).
503 – Service Unavailable This is returned in the rare case that an exception is thrown by the system. An email is also sent to support if this happens.

⇪ Back to Directory

Related articles