Companies
The Companies API includes several methods allowing the management of company accounts:
createCompany
: adds a new company.deleteCompany
: deletes a company.updateCompanyDetails
: updates company information, such as name.getCompanyDetails
: retrieves the details of a company.getCompanyDetailsByUser
: retrieves the details of the company linked to the specified user account.findCompaniesByName
: retrieves all managed companies containing the specified string in their name.suspendCompany
: disables access to Control Center for all user accounts of a company.activateCompany
: activates a previously suspended company.createCustomFieldDefinition
: adds a new custom field definition.updateCustomFieldDefinition
: updates a custom field definition.getCustomFieldsDefinitions
: retrieves the custom fields definitions.deleteCustomFieldDefinition
: deletes a custom field definition.
API url: CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/companies
createCompany
This method creates a customer or partner company account.
Parameters
Parameter | Type | Optional | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Number | No | The company type. Available values:
| ||||||||||
| String | No | The company name. Must be unique. | ||||||||||
| String | Yes | The ID of the parent partner company. | ||||||||||
| String | Yes | The company's physical address. | ||||||||||
| String | Yes | The company's country of operation. The value must be in ISO 3166 format. Default value: | ||||||||||
| String | Yes | The company's country state of operation. The value must be in ISO 3166 format. Default value: | ||||||||||
| String | Yes | The company's phone number. | ||||||||||
| String | Yes | The industry the company operates in. Possible values:
Default value: | ||||||||||
| Boolean | Yes | An option defining if the security of the new company can be managed by its Partner company. Available values: | ||||||||||
| Boolean | Yes | An parameter that defines Two Factor Authentication (2FA) enforcement for all GravityZone user accounts in the company. The value is always | ||||||||||
| Number | Yes | The period, defined in days, for which the users of the company can have their devices exempted from providing a two-factor code at authentication. Available values: | ||||||||||
| String | Yes | The email for the new user account to be linked to the new company. If the parameter | ||||||||||
| String | Yes | The full name of the new user account to be linked to the new company. This parameter is required when | ||||||||||
| Object | Yes | Contains information regarding the company's designated contact person. The object contains the following fields:
| ||||||||||
| String | Yes | The timezone of the new user account to be linked to the new company. The default value is | ||||||||||
| String | Yes | The user interface language for the new user account to be linked to the new company. The default value is | ||||||||||
| Object | Yes | An object containing the license details:
If not specified the company will be created with license subscription type | ||||||||||
| Object | Yes | An object containing the custom fields values for the company. |
Return value
This method returns a String: the ID of the newly-created company.
Example
Request:
{ "params": { "type": 0, "name": "Partner LTD", "parentId": "64babaafab366c53d20c83ca", "address": "Str Example No 1", "country": "US", "state": "US-CA", "phone": "0040740000000", "industry": 2, "canBeManagedByAbove": true, "enforce2FA": true, "skip2FAPeriod": 3, "accountEmail": "partner@example.com", "accountFullName": "Partner account", "contactPerson": { "fullName": "Stephen Johnson", "email": "stephen.johnson@example.email.com", "phoneNumber": "0040740000001", "companyRole": "Owner / President" }, "licenseSubscription": { "type": 3, "reservedSlots": 120, "endSubscription": "2028-04-14", "autoRenewPeriod": 12, "manageExchange": false, "manageEncryption": false, "managePatchManagement": false, "manageIntegrityMonitoring": true, "imDataRetention": 2, "ownUse": { "manageXDRIdentityProviders": true, "manageXDRProductivityApps": true, "manageXDRNetwork": true, "manageXDRCloudWorkloads": true, "manageRemoteEnginesScanning": true, "manageContainerProtection": true, "manageHyperDetect": true, "manageSandboxAnalyzer": true, "manageEventCorrelator": true }, "resell": { "manageXDRResell": true, "manageRemoteEnginesScanningResell": true, "manageContainerProtectionResell": true, "manageHyperDetectResell": true, "manageSandboxAnalyzerResell": true, "manageEventCorrelatorResell": true }, "minimumUsage": { "endpointMonthlyUsage": 120 }, "assignedProductType": 0, "additionalProductTypes": [ 0 ], "assignedProtectionModel": "aLaCarte", "additionalProtectionModels": [ "aLaCarte", "mspSecure", "mspSecurePlus", "mspSecureExtra" ], "licensedServices": { "mdrServiceOwnUse": 1 } }, "customFields": { "referenceID": "004562", "vertical": "healthcare", "partner_type": "platinum", "security_level": "high", "payment_status": "goodstanding" } }, "jsonrpc": "2.0", "method": "createCompany", "id": "e249c22c-0ada-4772-a9f1-ee1cbb322588" }
Response:
{ "id":"e249c22c-0ada-4772-a9f1-ee1cbb322588", "jsonrpc":"2.0", "result": "5493dcd2b1a43df00b7b23c6" }
deleteCompany
This method deletes a company.
Parameters
Parameter | Type | Optional | Description |
---|---|---|---|
| String | No | The ID of the company to be deleted. |
Return value
This method does not return any value.
Example
Request:
{ "params": { "companyId": "54a295d8b1a43d7c4a7b23c6", }, "jsonrpc": "2.0", "method": "deleteCompany", "id": "f5911ea2-9f14-4046-96eb-5fa24cca98f0" }
Response:
{ "id":"f5911ea2-9f14-4046-96eb-5fa24cca98f0", "jsonrpc":"2.0", "result": null }
updateCompanyDetails
This method updates the details of a company account.
Parameters
Parameter | Type | Optional | Description |
---|---|---|---|
| String | Yes | The ID of the company to be updated. The default value is the ID of the company linked to the user who generated the API key. |
| Number | Yes | The company type. Available values:
If not set, the company type will not be changed. |
| String | Yes | The company's name. It must be unique. If not set, the company's name will not be changed. |
| String | Yes | The company's address. If not set, the company's address will not be changed. |
| String | Yes | The company's phone number. |
| String | Yes | The industry the company operates in. Possible values:
Default value: |
| String | Yes | The company's country of operation. The value must be in ISO 3166 format. Default value: |
| String | Yes | The company's country state of operation. The value must be in ISO 3166 format. Default value: |
| Object | Yes | Contains information regarding the company's designated contact person. The object contains the following fields:
|
| String | Yes | The company's phone number. If not set, the company's phone number will not be changed. |
| Boolean | Yes | An parameter that defines Two Factor Authentication (2FA) enforcement for all GravityZone user accounts in the company. The value is always |
| Number | Yes | The period, defined in days, for which the users of the company can have their devices exempted from providing a two-factor code at authentication. Available values: |
| Object | Yes | An object containing the custom fields values for the company. To delete the custom fields, set it as an empty array. |
Return value
This method does not return any value.
Example
Request:
{ "params": { "id" : "5493dcd2b1a43df00b7b23c6", "type": 0, "name": "Customer to Partner LTD", "address": "Str Example No 1", "phone": "0040740000001", "enforce2FA": true, "skip2FAPeriod": 3 "customFields":{ "referenceID":"004562", "vertical":"healthcare", "partner_type":"platinum", "security_level":"high", "payment_status":"goodstanding" } }, "jsonrpc": "2.0", "method": "updateCompanyDetails", "id": "60357f0e-94da-463c-ba36-f50f2ef8c34f" }
{ "params": { "name": "Example LTD", "address": "Str Example No 1", "phone": "0040740000001" }, "jsonrpc": "2.0", "method": "updateCompanyDetails", "id": "60357f0e-94da-463c-ba36-f50f2ef8c34f" }
Response:
{ "id":"60357f0e-94da-463c-ba36-f50f2ef8c34f", "jsonrpc":"2.0", "result": null }
getCompanyDetails
This method retrieves the details of a company.
Parameters
Parameter | Type | Optional | Description |
---|---|---|---|
companyId | String | Yes | The company's ID. The default value is the ID of the company linked to the user who generated the API key. |
Return value
This method returns an Object containing the details of the selected company:
type
- the company type: 0 for Partner, 1 for Customername
- the name of the companyid
- the ID of the companyaddress
- the address of the companyphone
- the phone of the companycanBeManagedByAbove
- the security management status for the company:true
, if the security can be managed by parent companiesenforce2FA
- a boolean specifying if the Two Factor Authentication (2FA) is enforced for user accounts belonging to the selected companyskip2FAPeriod
- an integer specifying the duration, in days, that the users can be exempted from providing a two-factor authentication code at loginisSuspended
- company account status:true
, if the company is suspendedcreatedAt
- a String representing the UTC date and time at which the company was createdcountry
- a String representing the country code in ISO 3166 format. If the code is not specified, the String has the valueN/A
state
- a String representing the country state code in ISO 3166 format. If the code is not specified, the String has the valueN/A
industry
- a String representing the industry the company operates in. It can have one of the following values:0
- UNDEFINED1
- AEROSPACE2
- AGRICULTURE3
- ARTS_ENTERTAINMENT4
- AUTOMOTIVE5
- BUSINESS_ASSOCIATIONS6
- CHEMICALS7
- COMMERCIAL_SERVICES8
- CONGLOMERATE9
- CONSTRUCTION10
- CONSULTING11
- CONTAINERS_PACKAGING:12
- DEFENSE13
- EDUCATION_RESEARCH14
- ENERGY15
- ENGINEERING16
- FINANCIAL_SERVICES17
- FOOD_BEVERAGES18
- GOVERNMENT19
- HEALTHCARE20
- HOSPITALITY_LEISURE21
- MANUFACTURING22
- MARINE23
- MEDIA24
- MINING25
- NON_PROFIT26
- OFFICES_OF_LAWYERS27
- PAPER_FOREST_PRODUCTS28
- RETAIL29
- SUPPORT_SERVICE_ACTIVITIES30
- TECHNOLOGY31
- TELECOMMUNICATIONS_SERVICES32
- TRANSPORTATION33
- UTILITIES34
- WHOLESALE
Default value:
0
.contactPerson
- an Object containing the details of the contact person:fullName
, their first name and surnameemail
, their business email addressphoneNumber
, their business phone numbercompanyRole
, their position in the company
Note
If any field under this object has a value, all fields will be returned, regardless if they have a value assigned or not.
riskScore
- an Object containing the following information about the company's security risks:value
, the company's security risk score value in percentage. It is broken down into misconfigurations, app vulnerabilities, human risks, and adjusted by the health industry modifierimpact
, the company's security risk impact (Low, Medium, High)misconfigurations
, the percentage of misconfigurations in the company's security risk scoreappVulnerabilities
, the percentage of app vulnerabilities in the company's security risk scorehumanRisks
, the percentage of human risks in the company's security risk scoreindustryModifier
, dynamically adjusts your company score based on CVEs discovered in your environment that have already been exploited at industry level
customFields
- an Object containing the custom fields values for the company:custom field name 1
, custom field value 1,custom field name 2
, custom field value 2
Example
Request:
{
"params": {
"companyId" : "5493dcd2b1a43df00b7b23c6"
},
"jsonrpc": "2.0",
"method": "getCompanyDetails",
"id": "0df7568c-59c1-48e0-a31b-18d83e6d9810"
}
Response:
{
"id":"0df7568c-59c1-48e0-a31b-18d83e6d9810",
"jsonrpc":"2.0",
"result": {
"type": 1,
"name": "Example LTD",
"id": "54aeab40b1a43dc0467b23e9",
"address": "Str Example No 1",
"phone": "0040740000001",
"canBeManagedByAbove": true,
"enforce2FA": true,
"skip2FAPeriod": 3
"isSuspended": false,
"createdAt": "2017-01-28T15:01:15",
"country": "CA",
"state": "CA-BC",
"industry": 2,
"contactPerson": {
"fullName": "Stephen Jhonson",
"email": "stephen.jhonsons@example.email.com",
"phoneNumber": "0040740000001",
"companyRole": "Owner / President"
},
"customFields": {
"referenceID":"004562",
"vertical":"healthcare",
"partner_type":"platinum",
"security_level":"high",
"payment_status":"goodstanding"
},
"riskScore": {
"value": "87%",
"impact": "High",
"misconfigurations": "70%",
"appVulnerabilities": "11%",
"humanRisks": "19%",
"industryModifier": "6%"
}
}
}
getCompanyDetailsByUser
This method retrieves the details of a company linked to an account identified through the given username.
Parameters
Parameter | Type | Optional | Description |
---|---|---|---|
username | String | No | The username linked to the searched company. |
password | String | Yes | The password of the specified username. This parameter is required only when the searched company is not in the target companies of the user who makes the API call. |
Return value
This method returns an Object containing the details of the searched company:
type
- a Number that shows the company type: 0 for Partner, 1 for Customername
- a String representing the name of the companyid
- a String that shows the company ID in GravityZoneaddress
- a String showing the physical address of the company premisesphone
- a String that informs of the contact phone of the companycanBeManagedByAbove
- a Boolean representing the security management rights over the company. It has the valuetrue
if the Bitdefender Partner manages the security for the searched company. Otherwise, it is falseenforce2FA
- a Boolean specifying if the Two Factor Authentication (2FA) is enforced for user accounts belonging to the searched companyskip2FAPeriod
- an integer specifying the duration, in days, that the users can be exempted from providing a two-factor authentication code at loginisSuspended
- a Boolean informing of the company account status. It has the valuetrue
if the company account is suspendedcreatedAt
- a String representing the UTC date and time at which the company was createdcountry
- a String representing the country code in ISO 3166 format. If the code is not specified, the String has the valueN/A
state
- a String representing the country state code in ISO 3166 format. If the code is not specified, the String has the valueN/A
contactPerson
- an Object containing the details of the contact person:fullName
, their first name and surnameemail
, their business email addressphoneNumber
, their business phone numbercompanyRole
, their position in the company
customFields
- an Object containing the set of custom fields configured for the searched company, together with their associated values
Example
Request:
{ "params": { "username": "partner@bitdefender.com", "password": "password" }, "jsonrpc": "2.0", "method": "getCompanyDetailsByUser", "id": "6435c228-73b0-4e72-9a2a-8716cc58c883" }
Response:
{ "id":"6435c228-73b0-4e72-9a2a-8716cc58c883", "jsonrpc":"2.0", "result": { "type": 0, "name": "Test partner", "id": "550ac840b1a43da64d7b23c6", "address": "Str Example No 1", "phone": "0040740000001", "canBeManagedByAbove": true, "enforce2FA": true, "skip2FAPeriod": 1 "isSuspended": false, "createdAt": "2017-01-28T15:01:15", "country": "CA", "state": "CA-BC", "contactPerson": { "fullName": "Stephen Jhonson", "email": "stephen.jhonsons@example.email.com", "phoneNumber": "0040740000001", "companyRole": "Owner / President" }, "customFields":{ "referenceID":"004562", "vertical":"healthcare", "partner_type":"platinum", "security_level":"high", "payment_status":"goodstanding" } } }
findCompaniesByName
This method searches for all managed companies containing the specified string in their name.
Parameters
Parameter | Type | Optional | Description |
---|---|---|---|
nameFilter | String | No | The string to be searched in the company name. Use the asterisk symbol (*) in front of the keyword to search its appearance anywhere in the name. If omitted, only results where the name starts with the keyword will be returned. |
Return value
This method returns an Array containing company objects whose names contain the given search criteria. The size of the returned array is limited to 25 entries. Each entry in the array has the following structure:
type
- the company type: 0 for Partner, 1 for Customername
- the name of the companyid
- the ID of the companyaddress
- the address of the companyphone
- the phone of the companycanBeManagedByAbove
- the security management status for the company:true
, if the security can be managed by parent companiesenforce2FA
- a boolean specifying if the Two Factor Authentication (2FA) is enforced for user accounts belonging to the selected companyskip2FAPeriod
- an integer specifying the duration, in days, that the users can be exempted from providing a two-factor authentication code at loginisSuspended
- company account status:true
, if the company is suspendedcreatedAt
- a String representing the UTC date and time at which the company was createdcountry
- a String representing the country code in ISO 3166 format. If the code is not specified, the String has the valueN/A
state
- a String representing the country state code in ISO 3166 format. If the code is not specified, the String has the valueN/A
contactPerson
- an Object containing the details of the contact person:fullName
, their first name and surnameemail
, their business email addressphoneNumber
, their business phone numbercompanyRole
, their position in the company
customFields
- an Object containing the custom fields values for the company:custom field name 1
, custom field value 1,custom field name 2
, custom field value 2
Example
Request:
{ "params": { "nameFilter": "Test" }, "jsonrpc": "2.0", "method": "findCompaniesByName", "id": "ae037403-7947-4f2b-b0b2-af190a8b44eb" }
Response:
{ "id":"ae037403-7947-4f2b-b0b2-af190a8b44eb", "jsonrpc":"2.0", "result": [{ "type": 1, "name": "Test customer", "id": "55191c7ab1a43d1f107b23c7", "address": "Str Example No 1", "phone": "0040740000001", "canBeManagedByAbove": true, "enforce2FA": true, "skip2FAPeriod": 1 "isSuspended": false, "createdAt": "2017-01-28T15:01:15", "country": "CA", "state": "CA-BC", "contactPerson": { "fullName": "Stephen Jhonson", "email": "stephen.jhonsons@example.email.com", "phoneNumber": "0040740000001", "companyRole": "Owner / President" }, "customFields":{ "referenceID":"004562", "vertical":"healthcare", "partner_type":"platinum", "security_level":"high", "payment_status":"goodstanding" } }, { "type": 0, "name": "Test partner", "id": "55191c5fb1a43da8107b23c6", "address": "Str Example No 2", "phone": "0040740000002", "canBeManagedByAbove": true, "enforce2FA": false, "isSuspended": false, "createdAt": "2017-01-28T15:01:15", "country": "CA", "state": "CA-BC", "country": "CA", "state": "CA-BC", "contactPerson": { "fullName": "Stephen Jhonson", "email": "stephen.jhonsons@example.email.com", "phoneNumber": "0040740000001", "companyRole": "Owner / President" }, "customFields":{ "referenceID":"004562", "vertical":"healthcare", "partner_type":"platinum", "security_level":"high", "payment_status":"goodstanding" } }] }
suspendCompany
This method suspends an active company account, with the following implications:
Parameters
Parameter | Type | Optional | Description |
---|---|---|---|
companyId | String | No | The ID of the company to be suspended. |
recursive | Boolean | No | True if sub-companies should be suspended as well. |
Return value
This method does not return any value.
Example
Request:
{ "params": { "companyId" : "5493dcd2b1a43df00b7b23c6", "recursive" : false }, "jsonrpc": "2.0", "method": "suspendCompany", "id": "8f6748b9-d201-4b63-b17f-4ecbebce24a9" }
Response:
{ "id":"8f6748b9-d201-4b63-b17f-4ecbebce24a9", "jsonrpc":"2.0", "result": null }
activateCompany
This method activates a suspended company.
Parameters
Parameter | Type | Optional | Description |
---|---|---|---|
companyId | String | No | The ID of the company to be activated. |
recursive | Boolean | No | rue if sub-companies should be activated as well |
Return value
This method does not return any value.
Example
Request:
{ "params": { "companyId" : "5493dcd2b1a43df00b7b23c6", "recursive" : false }, "jsonrpc": "2.0", "method": "activateCompany", "id": "c67860e2-36cc-43bd-bc0f-f1061c180b52" }
Response:
{ "id":"c67860e2-36cc-43bd-bc0f-f1061c180b52", "jsonrpc":"2.0", "result": null }
createCustomFieldDefinition
This method creates a custom field definition.
Parameters
Parameter | Type | Optional | Description |
---|---|---|---|
name | String | No | The name of the custom field. |
Return value
This method returns a String: the ID of the newly-created custom field.
Example
Request:
{ "params": { "name": "referenceID" }, "jsonrpc": "2.0", "method": "createCustomFieldDefinition", "id": "e249c22c-0ada-4772-a9f1-ee1cbb322588" }
Response:
{ "id":"e249c22c-0ada-4772-a9f1-ee1cbb322588", "jsonrpc":"2.0", "result": "5493dcd2b1a43df00b7b23c6" }
updateCustomFieldDefinition
This method updates a custom field definition.
Parameters
Parameter | Type | Optional | Description |
---|---|---|---|
id | String | No | The ID of the custom field |
name | String | No | Custom field name |
Return value
This method does not return any value.
Example
Request:
{ "params": { "id": "5518f5f3b1a43d357e7b23c6", "name": "referenceID", }, "jsonrpc": "2.0", "method": "updateCustomFieldDefinition", "id": "e249c22c-0ada-4772-a9f1-ee1cbb322588" }
Response:
{ "id":"e249c22c-0ada-4772-a9f1-ee1cbb322588", "jsonrpc":"2.0", "result": null }
getCustomFieldsDefinitions
This method retrieves the custom fields definitions.
Parameters
No input parameters are required.
Return value
This method returns an Object containing a list of the custom fields definitions with the following structure:
id
- the ID of the custom fieldname
- the name of the custom field
Example
Request:
{ "params": { }, "jsonrpc": "2.0", "method": "getCustomFieldsDefinitions", "id": "6435c228-73b0-4e72-9a2a-8716cc58c883" }
Response:
{ "id":"6435c228-73b0-4e72-9a2a-8716cc58c883", "jsonrpc":"2.0", "result": [ { "name": "referenceID", "id": "5d8800330ea1de72721f9922" }, { "name": "vertical", "id": "5d91f4350ea1de6353701f62" }, { "name": "partner_type", "id": "5d91f2a90ea1de37ee1153f2" }, { "name": "security_level", "id": "5d91f70b0ea1de67a438aba2" } ] }
deleteCustomFieldDefinition
This method deletes a custom field definition.
Parameters
Parameter | Type | Optional | Description |
---|---|---|---|
id | String | No | The ID of the custom field to be deleted |
Return value
This method does not return any value.
Example
Request:
{ "params": { "id": "54a295d8b1a43d7c4a7b23c6", }, "jsonrpc": "2.0", "method": "deleteCustomFieldDefinition", "id": "f5911ea2-9f14-4046-96eb-5fa24cca98f0" }
Response:
{ "id":"f5911ea2-9f14-4046-96eb-5fa24cca98f0", "jsonrpc":"2.0", "result": null }