POST: Invite a Company to Collaborate via the Enable Access Program – Bitsight Knowledge Base

March 23, 2023: Added reason query parameter, example response, and response attributes.
June 16, 2022: Added third_parties query parameter.
December 11, 2020: Assigning a point of contact is required only if sending multiple invitations at once (in bulk).

https://api.bitsighttech.com/ratings/v1/access-requests

Invite a company to collaborate via the Enable Access Program.

This can also be used to send multiple collaboration requests. Ensure the recipients have a point of contact.

Parameters
Example Request
Example Response
Response Attributes
Errors

Parameters

*Required.

Parameter	Description	Values
requestee_friendly_name Body	Identify the recipient point of contact.	[String] The preferred name of the recipient. Default: If empty, the user that’s pre-attached with the recipient company is used.
requestee_formal_name Body	Identify the recipient point of contact.	[String] The full name of the recipient. Default: If empty, the user that’s pre-attached with the recipient company is used.
requestee_email Body	Identify the recipient point of contact.	[String] The email address of the recipient of the access request. The email domain must match a domain that belongs to the requested company. Default: If empty, the user that’s pre-attached with the recipient company is used.
requestee_phone Body	Identify the recipient point of contact.	[String] The phone number of the recipient.
requestee_company_guid Body	Identify the recipient company.	[String] Company unique identifier [`entity_guid`]. See GET: Portfolio Details.
message Body	Introduce yourself and the purpose of your collaboration request.	[String]
notes Body	Document private notes for other users in your organization.	[String]
read Body	Whether or not the vendor access request was read.	[Boolean]
ccs Body	The comma separated list of emails to be included as carbon copy.	[Array] Comma-separated email addresses.
trial_duration Body	The duration in days of trial access, after being accepted.	[Integer] 1–365 Default: `30`
reason Body	The reason why you are sending the collaboration request.	[String] `informational` = Provide general awareness of Bitsight and ratings. `remediation` = Address concerning areas of risk regarding the current rating of the recipient. `validation` = Validate topics of interest, such as ensuring the infrastructure best represents the organization, determining the impact of data for review, etc. `vulnerability` = Confirm potential exposure to a vulnerability and determine any next steps. `other` (default) = Unspecified reason.
slug String	The slug name of a risk vector you're including as context.	Example: `botnet`
third_parties Body	CC additional contacts on the introductory email. They don’t need to be part of the recipient’s organization or have access to the Bitsight platform. They do not receive an activation email.	[Array] Contact information. Example: [ { "email": "richard.kuga@saperix.com", "name": "Richard Kuga" } ]

Example Request

JSON:

{
  "vendor_access_request": {
    "requestee_friendly_name": "Bob",
    "requestee_formal_name": "Bob Robertson",
    "requestee_email": "bob@robertson.com",
    "requestee_phone": "555-555-5555",
    "requestee_company_guid": "dc24dc48-268a-4e44-8510-c2ae7185668e",
    "message": "This is a message to the recipient.",
    "notes": "This is a note to anyone in my organization.",
    "read": true,
    "ccs": "barb@barbara.com,rob@robson.com",
    "rolledup_observation_ids": [
      "abcdefghijkl=","aaa2+=2-aaaaa"
    ],
    "trial_duration": 30,
    "reason": "other",
    "context": {
      "risk_vectors": [
        {
          "risk_vector": {
            "slug": "botnet"
          }
        }
      ]
    },
    "resolved_by": {},
    "third_parties": [
      {
        "email": "richard.kuga@saperix.com",
        "name": "Richard Kuga"
      }
    ]
  }
}

Example Response

{
  "guid": "11111111-eeee-1111-eeee-111111111111",
  "requester_guid": "eeeeeeee-8888-eeee-8888-eeeeeeeeeeee",
  "requester_email": "emma@blueseas.com",
  "requestee_first_name": "Maria",
  "requestee_last_name": "Castro",
  "requester_first_name": "Emma",
  "requester_last_name": "Waters",
  "requester_friendly_name": "Emma",
  "requester_formal_name": "Emma Waters",
  "requester_company_guid": "feeccea4-e062-4cf5-9a3d-7034addb12d1",
  "requester_company_name": "Blue Seas International",
  "requester_customer_guid": "c940bb61-33c4-42c9-9231-c8194c305db3",
  "requester_customer_name": "My Company",
  "requestee_friendly_name": "Maria Castro",
  "requestee_formal_name": "Maria Castro",
  "requestee_email": "mcastro@blackhills.com",
  "requestee_phone": "555-555-5555",
  "requestee_company_guid": "a5e23bf0-38d4-4cea-aa50-19ee75da481d",
  "requestee_company_name": "Black Hills Technologies",
  "requestee_tos_date":null,
  "requestee_last_login": "2021-03-21",
  "message": "Please address these concerns - from Emma",
  "notes":null,
  "created_date": "2021-04-17",
  "created_time": "2021-04-17T12:26:21Z",
  "email_sent_date": "2021-04-24",
  "can_resend_email": true,
  "hubspot_status": "CREATED",
  "status": "Resolved",
  "is_real": true,
  "has_shared_observations":true,
  "shared_observations_count":3,
  "has_preferred_contacts":true,
  "read": true,
  "ccs":null,
  "rolledup_observation_ids": [
    "string"
  ],
  "invitation_duration": 14,
  "trial_duration": 30,
  "reason": "informational",
  "context": {
    "risk_vectors": [
      {
        "risk_vector": {
          "slug": "botnet"
        }
      }
    ]
  },
  "resolved_by": {
    "guid": "eeeeeeee-8888-eeee-8888-eeeeeeeeeeee",
    "formal_name": "Emma Waters"
  },
  "resolved_date": "2021-06-21",
  "recipient_customer_access": "active",
  "third_parties": [
    {
      "email": "richard.kuga@saperix.com",
      "name": "Richard Kuga"
    }
  ]
}

Response Attributes

Field				Description
guid String [`collab_guid`]				The unique identifier of the collaboration request.
requester_guid String [`user_guid`]				The unique identifier of the sender.
requester_email String				The email of the sender.
requestee_first_name String				The given name of the recipient.
requestee_last_name String				The surname of the recipient.
requester_first_name String				The given name of the sender.
requester_last_name String				The surname of the sender.
requester_friendly_name String				The preferred name of the sender.
requester_formal_name String				The full name of the sender.
requester_company_guid String [`entity_guid`]				The unique identifier of the sender’s company.
requester_company_name String				The name of the sender’s company.
requester_customer_guid String [`account_guid`]				The unique identifier of the sender’s account.
requester_customer_name String				The name of the sender’s account.
requestee_friendly_name String				The preferred name of the recipient.
requestee_formal_name String				The full name of the recipient.
requestee_email String				The email address of the recipient.
requestee_phone String				The phone number of the recipient.
requestee_company_guid String [`entity_guid`]				The unique identifier of the recipient company.
requestee_company_name String				The name of the recipient company.
requestee_tos_date String [`YYYY‑MM‑DD`]				The date when the recipient accepted the Bitsight Terms and Conditions and activated their account. This value is null if the recipient hasn't activated their Bitsight account.
requestee_last_login String [`YYYY‑MM‑DD`]				The most recent date when the recipient logged in to the Bitsight platform.
message String				The message from the sender to the recipient.
notes String				Private notes from the sender for other users in their organization. This is not visible to recipients.
created_date String [`YYYY‑MM‑DD`]				The date when the collaboration request was submitted.
created_time String [`YYYY‑MM‑DDTHH:MM:SSZ`]				The date and timestamp when the request was submitted.
email_sent_date String [`YYYY‑MM‑DD`]				The date when the invitation email was sent.
can_resend_email Boolean				`true` = The invitation email can be resent to the recipient.
hubspot_status String				For internal Bitsight use.
status String				The collaboration status.
is_real Boolean				For internal Bitsight use.
has_shared_observations Boolean				`true` = This request included contextual findings.
shared_observations_count Integer				The number of observations shared in the vendor access request.
has_preferred_contact Boolean				`true` = This company has assigned a user as their preferred contact for receiving invitations to collaborate via the Enable Access Program.
read Boolean				`true` = This invitation to collaborate has been received and read.
ccs String				An email address that's carbon copied (CC) on the invitation email.
rolledup_observation_ids Array				An identifier for findings.
reason String				The reason why you are sending the collaboration request.
context Object				Context provided by you.
	risk_vectors Array			Risk vectors provided as context.
		Object		The details of a risk vector provided as context.
			risk_vector Object	Details of this risk vector.
			slug String	The slug name of this risk vector.
resolved_by Object				The user who marked collaboration as “resolved.”
	guid String [`user_guid`]			The unique identifier of this user.
	formal_name String			The full name of this user.
resolved_date String [`YYYY‑MM‑DD`]				The date when collaboration was marked as “resolved.”
recipient_customer_access String				The activation status of the recipient.
third_parties Array				Additional recipients added to the Assign CCs field.
	Object			A contact.

		email String		This contact’s email address.

Errors

All of these are 400 Error messages:

Message	Description
“Invalid requestee email”	The format of the recipient’s email address is invalid.
“It is not possible to send an access request to yourself”	You cannot be a recipient of your own access request.
“No entity found for specified guid”	The specified unique identifier (GUID) does not match any company in your portfolio.
“Please limit shared observations to 10”	Access requests can include up to 10 observations for context.
“The observations ids did not match the entity”	The specified contextual finding does not belong to any company in your portfolio.
“The requestee email domain is unrelated to the entity”	The email domain does not match the domain of the specified company.
“The entity cannot be used for vendor access requests”	Only Bitsight-curated or partner-provided companies can be sent an access request.
“It is not possible to send an access request with combined string of cc emails larger than 1023 characters”	The CC field cannot contain more than 1023 characters. This includes separators.

Articles in this section

Parameters

Example Request

Example Response

Response Attributes

Errors

Related articles