POST: Invite a Company to Collaborate via the Client/Vendor Access Program Ingrid 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. requestee_friendly_name * Required. [Body] Identify the recipient point of contact. Value: [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 * Required. [Body] Identify the recipient point of contact. Value: [String] The full name of the recipient. ↻ Default: If empty, the user that’s pre-attached with the recipient company is used. requestee_email * Required. [Body] Identify the recipient point of contact. Value: [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. Value: [String] The phone number of the recipient. requestee_company_guid * Required. [Body] Identify the recipient company. Value: [String] Company unique identifier [entity_guid]. See GET: Portfolio Details. message [Body] Introduce yourself and the purpose of your collaboration request. Value: [String] notes [Body] Document private notes for other users in your organization. Value: [String] read [Body] Indicate whether or not the vendor access request was read. Value: [Boolean] ccs [Body] Identify recipients to send a carbon copy to. Value: [Array] Comma-separated email addresses. trial_duration [Body] Set the duration in days the recipient has access to the Bitsight platform. Value: [Integer] 1–365 ↻ Default: 30 reason [Body] Provide the reason why you are sending the collaboration request. Value: [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. Value: [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. Value: [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: “Invalid requestee email” Details: The format of the recipient’s email address is invalid. Message: “It is not possible to send an access request to yourself” Details: You cannot be a recipient of your own access request. Message: “No entity found for specified guid” Details: The specified unique identifier (GUID) does not match any company in your portfolio. Message: “Please limit shared observations to 10” Details: Access requests can include up to 10 observations for context. Message: “The observations ids did not match the entity” Details: The specified contextual finding does not belong to any company in your portfolio. Message: “The requestee email domain is unrelated to the entity” Details: The email domain does not match the domain of the specified company. Message: “The entity cannot be used for vendor access requests” Details: Only Bitsight-curated or partner-provided companies can be sent an access request. Message: “It is not possible to send an access request with combined string of cc emails larger than 1023 characters” Details: 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. Related articles Cyber Insurance API Guide Access Request API Endpoint GET: Portfolio Details What Content-Security-Policy (CSP) Directives are Assessed? GET: Collaboration Outbox Feedback 0 comments Please sign in to leave a comment.