POST: Invite a Company to Collaborate via the Client/Vendor Access Program – Bitsight Knowledge Base

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

Invite a company to collaborate via the Client/Vendor 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 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] Indicate whether or not the vendor access request was read.

[Boolean]

ccs

[Body] Identify recipients to send a carbon copy to.

[Array] Comma-separated email addresses.

trial_duration

[Body] Set the duration in days the recipient has access to the Bitsight platform.

[Integer] 1–365

Default: 30

reason

[Body] Provide 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 = Unspecified reason.

slug

[String] Include a risk vector as context.

[String] Risk vector slug name.

Example: botnet

third_parties

[Body] Carbon copy (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] The contact's 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 Client/Vendor 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				Stable and randomized identifiers for findings. They are assigned to a finding when one or more observations with largely similar key properties occur in close succession.
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.

May 06, 2024: Enable Access Program renamed to Client/Vendor Access Program.
March 23, 2023: Added reason query parameter, example response, and response attributes.
June 16, 2022: Added third_parties query parameter.

Parameters

Example Request

Example Response

Response Attributes

Errors

Related articles