DocumentationRelease Notes
Log In
Documentation

BeyondInsight APIs

The BeyondInsight APIs require a valid BeyondInsight license and are available to Password Safe-licensed installs.

This document specifies the Representational State Transfer (REST) compliant Application Programmer Interface (API) over HTTPS for BeyondInsight and Password Safe. It is a way to integrate a portion of the BeyondInsight and Password Safe functionality into your own applications.

Using the REST API makes it easier for users to build customized solutions for their specific needs while ensuring secure data transmission. The API provides a set of predefined operations, or endpoints, that can be accessed using HTTP Requests, including GET requests to retrieve data, POST requests to create new data, PUT requests to update existing data, and DELETE requests to remove data.

This resource is intended for readers with knowledge of HTTPS request and response processing, web development, and JSON notation.

Access levels

(i.e., None, Read, Read/Write)

GET AccessLevels

Purpose

Returns a list of access levels for permissions, for example, None, Read, and Read/Write.

Required permissions

User Accounts Management (Read).

Request body

None.

Response body

Content-Type: application/json

[
    {
        AccessLevelID:int,
        Name: string,
    },
    …
]

Response codes

200 - Request successful. Access Levels in the response body.

POST UserGroups/{userGroupId}/SmartRules/{smartRuleId}/AccessLevels

Purpose

Sets the Access Level for a User Group Smart Rule.

Required permissions

  • User Accounts Management (Read/Write).

URL parameters

  • userGroupId: ID of the user group.
  • smartRuleId: ID of the Smart Rule.

Request body

Content-Type: application/json

{
    AccessLevelID: int
}

Response body

None.

Response codes

  • 200 - Request successful.

ℹ️

Note

For more information, see "Common Response Codes" on page 1.

Address groups

GET Organizations/{orgID}/AddressGroups

Purpose

List the address groups for a given organization.

Required permissions

  • Current user has access to the organization.
  • Asset Management (Read).

URL parameters

orgId: Organization ID.

Request body

None.

Response body

Content-Type: application/json

[
    {
        AddressGroupID: int,
        Name: string,
        OrganizationID: guid // can be null
    }
]

Response codes

200 - Request successful.

GET AddressGroups

Purpose

List the address groups.

Required permissions

  • Current user has access to the organization.
  • Asset Management (Read).

URL parameters

None.

Request body

None.

Response body

Content-Type: application/json

[
    {
        AddressGroupID: int,
        Name: string,
        OrganizationID: guid // can be null
    {
]

Response codes

200 - Request successful.

GET AddressGroups/{addressGroupId}/Addresses

Purpose

List the addresses for an address group.

Required permissions

  • Current user has access to the organization.
  • Asset Management (Read).

URL parameters

addressGroupId: Address Group ID.

Request body

None.

Response body

Content-Type: application/json

[
    {
        AddressID: int,
        AddressGroupID: int,
        Omit: boolean,
        Type: int,
     Value: string,
        LastUpdatedDate: datetime
    }
]

Response body details

  • Type: The Address type
    • 1: Single IP Address
    • 2: IP Address Range
    • 3: CIDR Notation
    • 4: Named Host
  • Omit: true to omit this entry, otherwise false.

Response codes

200 - Request successful.

POST AddressGroups/{id}/Addresses

Purpose

Create an address in an Address Book.

Required permissions

  • Asset Management (Read/Write).

URL parameters

addressGroupId: Address Group ID.

Request body

{
    Type: int,
    Value: string,
    Omit: bool
}

Request body details

  • Max string length for Value is 225.
  • Type: The Address type
    • 1: Single IP Address
    • 2: IP Address Range
    • 3: CIDR Notation
    • 4: Named Host
  • Omit: true to omit this entry, otherwise false.

Response body

Content-Type: application/json

{
    AddressID: int,
    AddressGroupID: int,
    Omit: bool,
    Type: int,
    Value: string,
    LastUpdatedDate: datetime
}

Response body details

  • Type: The Address type
    • 1: Single IP Address
    • 2: IP Address Range
    • 3: CIDR Notation
    • 4: Named Host
  • Omit: true to omit this entry, otherwise false.

Response codes

201 - Request successful. Address in the response body.

DELETE AddressGroups/{addressGroupId}

Purpose

Delete the address group and all it's addresses.

Required permissions

  • Current user has access to the organization.
  • Asset Management (Read/Write).

URL parameters

addressGroupId: Address Group ID.

Request body

None.

Response body

None.

Response codes

200 - Request successful.

DELETE AddressGroups/{addressGroupId}/Addresses

Purpose

Delete the addresses within the address group.

Required permissions

  • Current user has access to the organization.
  • Asset Management (Read/Write).

URL parameters

addressGroupId: Address Group ID.

Request body

None.

Response body

None.

Response codes

200 - Request successful.

GET AddressGroups/?name={name}

Purpose

Returns the Address Group by name.

Required permissions

  • Asset Management (Read).

Query parameters

name: Name of the Address Group.

Request body

None.

Response body

Content-Type: application/json

{
    AddressGroupID: int,
    Name: string
}

Response codes

200 - Request successful. Address Group in the response body.

GET AddressGroups/{id}

Purpose

Returns the Address Group by ID.

Required permissions

  • Asset Management (Read).

URL parameters

id: ID of the Address Group.

Request body

None.

Response body

Content-Type: application/json

{
    AddressGroupID: int,
    Name: string
}

Response codes

200 - Request successful. Address Group in the response body.

PUT AddressGroups/{id}

Purpose

Updates and Address Group by ID.

Required permissions

  • Asset Management (Read/Write).

Request body

Content-Type: application/json

{
    Name: string,
}

Request body details

Max string length for Name is 225.

Response body

Content-Type: application/json

{
    AddressGroupID: int,
    Name: string
}

Response codes

200 - Request successful. Address Group in the response body.

POST AddressGroups

Purpose

Creates an Address Book.

Required permissions

  • Asset Management (Read/Write).

Request body

Content-Type: application/json

{
    Name: string
}

Request body details

Max string length for Name is 225.

Response body

Content-Type: application/json

{
    AddressGroupID: int,
    Name: string
}

Response codes

201 - Request successful. Address Group in the response body.

GET Addresses/{id}

Purpose

Returns the Address by ID.

Required permissions

  • Asset Management (Read).

URL parameters

id: ID of the Address.

Request body

None.

Response body

Content-Type: application/json

{
    AddressId: int,
    AddressGroupId : int,
    Omit: bool,
    Type: int,
    Value: string,
    LastUpdateDate: datetime
}

Response body details

  • Type: The Address type
    • 1: Single IP Address
    • 2: IP Address Range
    • 3: CIDR Notation
    • 4: Named Host
  • Omit: true to omit this entry, otherwise false.

Response codes

200 - Request successful. Address in the response body.

DELETE Addresses/{id}

Purpose

Deletes an Address by ID.

Required permissions

Asset Management (Read/Write).

Request body

None.

Response body

None.

Response codes

200 - Request successful.

PUT Addresses/{id}

Purpose

Updates and Address by ID.

Required permissions

  • Asset Management (Read/Write).

Request body

Content-Type: application/json

{
    Type: int,
    Value: string,
    Omit: bool
}

Request body details

  • Max string length for Value is 225.
  • Type: The Address type
    • 1: Single IP Address
    • 2: IP Address Range
    • 3: CIDR Notation
    • 4: Named Host
  • Omit: true to omit this entry, otherwise false.

Response body

Content-Type: application/json

{
    AddressD: int,
    AddressGroupID: int,
    Omit: bool,
    Type: int,
    Value: string,
    LastUpdateDate: datetime
}

Response body details

  • Type: The Address type
    • 1: Single IP Address
    • 2: IP Address Range
    • 3: CIDR Notation
    • 4: Named Host
  • Omit: true to omit this entry, otherwise false.

Response codes

200 - Request successful. Address in the response body.

API registrations

GET ApiRegistrations

Purpose

Returns a list of all API registrations.

Required permissions

API Registration Management (Read).

Query parameters

...

Request body

None.

Response body

Content-Type: application/json

{
            Id: int,
            Name: string,
            RegistrationType: string,
            Active: bool,
            Visible: bool,
            MultiFactorAuthenticationEnforced: bool,
            ClientCertificateRequired: bool,
            UserPasswordRequired: bool,   
            VerifyPsrunSignature: bool,
            IPAuthenticationRules:[
                   {
                           Id: int, 
                           Type: string,
                           Value: string,
                           Description: string,
                           CreatedDate: date
                   },
                   ...
            ],
            PSRUNRules:[
                  {
                           Id:int,
                           IPAddress: string,
                           MacAddress: string,
                           SystemName: string,
                           FQDN: string,
                           DomainName: string,
                           UserId: string,  
                           RootVolumeId: string,
                           OSVersion: string,
                           CreatedDate: date
                   },

                   ...
            ], 
            XForwardedForAuthenticationRules:[
                   {
                           Id: int,
                           Type: string,
                           Value: string,
                           Description: string,
                           CreatedDate: date
                   },
                   ...

            ]
}

Response codes

200 – Request successful. API Registration in the response body.

GET ApiRegistrations/{id}

Purpose

Returns an API registration by ID.

Required permissions

API Registration Management (Read).

Query parameters

Id: ID of the API registration.

Request body

None.

Response body

Content-Type: application/json

{
        Id: int,
        Name: string,
        RegistrationType: string,
        Active: bool,
        Visible: bool,
        MultiFactorAuthenticationEnforced: bool,
        ClientCertificateRequired: bool,
        UserPasswordRequired: bool,   
        VerifyPsrunSignature: bool,
        IPAuthenticationRules:[
                   {
                           Id: int, 
                           Type: string,
                           Value: string,
                           Description: string,
                           CreatedDate: date
                   },
                   ...
            ],
            PSRUNRules:[
                  {
                           Id:int,
                           IPAddress: string,
                           MacAddress: string,
                           SystemName: string,
                           FQDN: string,
                           DomainName: string,
                           UserId: string,  
                           RootVolumeId: string,
                           OSVersion: string,
                           CreatedDate: date
                   },

                   ...
            ], 
            XForwardedForAuthenticationRules: [
                   {
                           Id: int,
                           Type: string,
                           Value: string,
                           Description: string,
                           CreatedDate: date
                   },
                   ...

            ]
}

Response codes

200 – Request successful. API Registration in the response body.

POST ApiRegistrations

Purpose

Creates an API registration.

Required permissions

API Registration Management (Read/Write).

Query parameters

...

Request body

The request body differs by RegistrationType.

Content-Type: application/json

ApiKeyPolicy
{
            Id: int,
            Name: string,
            RegistrationType: string = “ApiKeyPolicy”,
            Active: bool,
            Visible: bool,
            MultiFactorAuthenticationEnforced: bool,
            ClientCertificateRequired: bool,
            UserPasswordRequired: bool,   
            VerifyPsrunSignature: bool,
            IPAuthenticationRules:[
                   {
                           Id: int, 
                           Type: string,
                           Value: string,
                           Description: string,
                   },
                   ...
            ],
            PSRUNRules:[
                  {
                           Id:int,
                           IPAddress: string,
                           MacAddress: string,
                           SystemName: string,
                           FQDN: string,
                           DomainName: string,
                           UserId: string,  
                           RootVolumeId: string,
                           OSVersion: string,
                   },

                   ...
            ], 
            XForwardedForAuthenticationRules:[
                   {
                           Id: int,
                           Type: string,
                           Value: string,
                           Description: string,
                   },
                   ...

            ]
}
ApiAccessPolicy
{
            Id: int,
            Name: string,
            RegistrationType: string = “ApiAccessPolicy”,
            AccessTokenDuration: int = 60,
            Active: bool,
            Visible: bool,
            ClientCertificateRequired: bool,
            IPAuthenticationRules:[
                   {
                           Id: int, 
                           Type: string,
                           Value: string,
                           Description: string,
                   },
                   ...
            ],
            XForwardedForAuthenticationRules:[
                   {
                           Id: int,
                           Type: string,
                           Value: string,
                           Description: string,
                   },
                   ...

            ]
}

Response body

Content-Type: application/json

{
            Id: int,
            Name: string,
            RegistrationType: string,
            AccessTokenDuration: int,
            Active: bool,
            Visible: bool,
            MultiFactorAuthenticationEnforced: bool,
            ClientCertificateRequired: bool,
            UserPasswordRequired: bool,   
            VerifyPsrunSignature: bool,
            IPAuthenticationRules:[
                   {
                           Id: int, 
                           Type: string,
                           Value: string,
                           Description: string,
                           CreatedDate; date
                   },
                   ...
            ],
            PSRUNRules:[
                  {
                           Id:int,
                           IPAddress: string,
                           MacAddress: string,
                           SystemName: string,
                           FQDN: string,
                           DomainName: string,
                           UserId: string,  
                           RootVolumeId: string,
                           OSVersion: string,
                           CreatedDate; date
                   },

                   ...
            ], 
            XForwardedForAuthenticationRules:[
                   {
                           Id: int,
                           Type: string,
                           Value: string,
                           Description: string,
                           CreatedDate; date
                   },
                   ...

            ]
}

Response codes

200 – Request successful. API Registration in the response body.

PUT ApiRegistrations/{id}

Purpose

Updates an API registration by ID.

Required permissions

API Registration Management (Read/Write).

Query parameters

Id: ID of the API registration.

Request body

The request body differs by Registration Type.

Content-Type: application/json

ApiKeyPolicy
{
            Id: int,
            Name: string,
            RegistrationType: string = “ApiKeyPolicy”,
            Active: bool,
            Visible: bool,
            MultiFactorAuthenticationEnforced: bool,
            ClientCertificateRequired: bool,
            UserPasswordRequired: bool,   
            VerifyPsrunSignature: bool,
            IPAuthenticationRules:[
                   {
                           Id: int, 
                           Type: string,
                           Value: string,
                           Description: string,
                   },
                   ...
            ],
            PSRUNRules:[
                  {
                           Id:int,
                           IPAddress: string,
                           MacAddress: string,
                           SystemName: string,
                           FQDN: string,
                           DomainName: string,
                           UserId: string,  
                           RootVolumeId: string,
                           OSVersion: string,
                   },

                   ...
            ], 
            XForwardedForAuthenticationRules:[
                   {
                           Id: int,
                           Type: string,
                           Value: string,
                           Description: string,
                   },
                   ...

            ]
}
ApiAccessPolicy
{
            Id: int,
            Name: string,
            RegistrationType: string = “ApiAccessPolicy”,
            AccessTokenDuration: int = 60,
            Active: bool,
            Visible: bool,
            ClientCertificateRequired: bool,
            IPAuthenticationRules:[
                   {
                           Id: int, 
                           Type: string,
                           Value: string,
                           Description: string,
                   },
                   ...
            ],
            XForwardedForAuthenticationRules:[
                   {
                           Id: int,
                           Type: string,
                           Value: string,
                           Description: string,
                   },
                   ...

            ]
}

Response body

Content-Type: application/json

{
            Id: int,
            Name: string,
            RegistrationType: string,
            AccessTokenDuration: int,
            Active: bool,
            Visible: bool,
            MultiFactorAuthenticationEnforced: bool,
            ClientCertificateRequired: bool,
            UserPasswordRequired: bool,   
            VerifyPsrunSignature: bool,
            IPAuthenticationRules:[
                   {
                           Id: int, 
                           Type: string,
                           Value: string,
                           Description: string,
                           CreatedDate; date
                   },
                   ...
            ],
            PSRUNRules:[
                  {
                           Id:int,
                           IPAddress: string,
                           MacAddress: string,
                           SystemName: string,
                           FQDN: string,
                           DomainName: string,
                           UserId: string,  
                           RootVolumeId: string,
                           OSVersion: string,
                           CreatedDate; date
                   },

                   ...
            ], 
            XForwardedForAuthenticationRules:[
                   {
                           Id: int,
                           Type: string,
                           Value: string,
                           Description: string,
                           CreatedDate; date
                   },
                   ...

            ]
}

Response codes

200 – Request successful. API Registration in the response body.

DELETE ApiRegistrations/{id}

Purpose

Deletes the API Registration for the ID provided.

Required permissions

API Registration Management (Read/Write).

Request body

None.

Response body

None.

Response codes

200 – Request successful.

POST ApiRegistrations/{id}/Rotate

ℹ️

Note

For API Key Policy only.

Purpose

Rotates the API key for an API Key policy API Registration

Required permissions

API Registration Management (Read/Write).

Query parameters

...

Request body

None.

Response body

Content-Type: application/json

string

Response codes

201 – Request successful. API key in the response body.

GET ApiRegistrations/{id}/Key

ℹ️

Note

For API Key Policy only.

Purpose

Retrieves the API key for an API Key policy API Registration.

Required permissions

API Registration Management (Read/Write).

Query parameters

...

Request body

None.

Response body

Content- Type: application/json

string

Response codes

200 – Request successful. API Key in the response body.

Assets

GET Assets/{id}

Purpose

Returns an asset by ID.

Required permissions

Asset Management (Read).

URL parameters

id: ID of the asset.

Request body

None.

Response body

Content-Type: application/json

{
    WorkgroupID: int,
    AssetID: int,
    AssetName: string,
    DnsName: string,
    DomainName: string,
    IPAddress: string,
    MacAddress: string,
    AssetType: string,
    Description: string,
    OperatingSystem: string,
    CreateDate: datetime,
    LastUpdateDate: datetime
}

Response codes

200 - Request successful. Asset in response body.

GET Workgroups/{workgroupID}/Assets

Purpose

Returns a list of assets by Workgroup ID.

Required permissions

Asset Management (Read).

URL parameters

workgroupID: ID of the Workgroup.

Query parameters (optional)

  • limit: (default: 100000) Number of records to return.
  • offset: (default: 0) Number of records to skip before returning records (can be used in conjunction only with limit).

Request body

None.

Response body (when limit is not given)

Content-Type: application/json

[
    {
        WorkgroupID: int,
        AssetID: int,
        AssetName: string,
        DnsName: string,
        DomainName: string,
        IPAddress: string,
        MacAddress: string,
        AssetType: string,
        OperatingSystem: string,
        CreateDate: datetime,
        LastUpdateDate: datetime
    },
    …
]

Response body (when limit is given)

Content-Type: application/json

{
    TotalCount : int,
    Data :
    [
        {
            WorkgroupID: int,
            AssetID: int,
            AssetName: string,
            DnsName: string,
            DomainName: string,
            IPAddress: string,
            MacAddress: string,
            AssetType: string,
            OperatingSystem: string,
            CreateDate: datetime,
            LastUpdateDate: datetime
        },
        …
    ]
}

Response codes

200 - Request successful. Assets in response body.

GET Workgroups/{workgroupName}/Assets

Purpose

Returns a list of assets by Workgroup name.

Required permissions

Asset Management (Read).

URL parameters

workgroupName: Name of the Workgroup.

Query parameters (optional)

  • limit: (default: 100000) Number of records to return.
  • offset: (default: 0) Number of records to skip before returning records (can only be used in conjunction with limit).

Request body

None.

Response body (when limit is not given)

Content-Type: application/json

[
    {
        WorkgroupID: int,
        AssetID: int,
        AssetName: string,
        DnsName: string,
        DomainName: string,
        IPAddress: string,
        MacAddress: string,
        AssetType: string,
        OperatingSystem: string,
        CreateDate: datetime,
        LastUpdateDate: datetime
    },
    …
]

Response body (when limit is given)

Content-Type: application/json

{
    TotalCount : int,
    Data :
    [
        {
            WorkgroupID: int,
            AssetID: int,
            AssetName: string,
            DnsName: string,
            DomainName: string,
            IPAddress: string,
            MacAddress: string,
            AssetType: string,
            OperatingSystem: string,
            CreateDate: datetime,
            LastUpdateDate: datetime
        },
        …
    ]
}

Response codes

200 - Request successful. Assets in response body.

GET Workgroups/{workgroupName}/Assets?name={name}

Purpose

Returns an asset by Workgroup name and asset name.

Required permissions

Asset Management (Read).

URL parameters

workgroupName: Name of the Workgroup.

Query parameters

name: Name of the asset.

Request body

None.

Response body

Content-Type: application/json

{
    WorkgroupID: int,
    AssetID: int,
    AssetName: string,
    DnsName: string,
    DomainName: string,
    IPAddress: string,
    MacAddress: string,
    AssetType: string,
    OperatingSystem: string,
    CreateDate: datetime,
    LastUpdateDate: datetime
}

Response codes

200 - Request successful. Asset in response body.

POST Workgroups/{workgroupID}/Assets

Purpose

Creates a new asset in the Workgroup, referenced by ID.

Required permissions

Asset Management (Read/Write).

URL parameters

workgroupID: ID of the Workgroup.

Request body

Content-Type: application/json

{
    IPAddress: string,
    AssetName: string,
    DnsName: string,
    DomainName: string,
    MacAddress: string,
    AssetType: string,
    Description: string,
    OperatingSystem: string
}

Request body details

  • IPAddress: (required) Asset IP address. Max string length is 45.
  • AssetName: (optional) Asset name. If not given, a padded IP address is used. Max string length is 128.
  • DnsName: (optional) Asset DNS name. Max string length is 255.
  • DomainName: (optional) Asset domain name. Max string length is 64.
  • MacAddress: (optional) Asset MAC address. Max string length is 128.
  • AssetType: (optional) Asset type. Max string length is 64.
  • Description: (optional) Asset description. Only updated if version in the URL is 3.1 or greater. Max string length is 255.
  • OperatingSystem: (optional) Asset operating system. Max string length is 255.

Response body

Content-Type: application/json

{
    WorkgroupID: int,
    AssetID: int,
    AssetName: string,
    DnsName: string,
    DomainName: string,
    IPAddress: string,
    MacAddress: string,
    AssetType: string,
    OperatingSystem: string,
    CreateDate: datetime,
    LastUpdateDate: datetime
}

Response codes

201 - Request successful. Asset in response body.

POST Workgroups/{workgroupName}/Assets

Purpose

Creates a new asset in the Workgroup referenced by name.

Required permissions

Asset Management (Read/Write).

URL parameters

workgroupName: Name of the Workgroup.

Request body

Content-Type: application/json

{
    IPAddress: string,
    AssetName: string,
    DnsName: string,
    DomainName: string,
    MacAddress: string,
    AssetType: string,
    Description: string,
    OperatingSystem: string
}

Request body details

  • IPAddress: (required) Asset IP address. Max string length is 45.
  • AssetName: (optional) Asset name. If not given, a padded IP address is used. Max string length is 128.
  • DnsName: (optional) Asset DNS name. Max string length is 255.
  • DomainName: (optional) Asset domain name. Max string length is 64.
  • MacAddress: (optional) Asset MAC address. Max string length is 128.
  • AssetType: (optional) Asset type. Max string length is 64.
  • Description: (optional) Asset description. Only updated if version in the URL is 3.1 or greater. Max string length is 255.
  • OperatingSystem: (optional) Asset operating system. Max string length is 255.

Response body

Content-Type: application/json

{
    WorkgroupID: int,
    AssetID: int,
    AssetName: string,
    DnsName: string,
    DomainName: string,
    IPAddress: string,
    MacAddress: string,
    AssetType: string,

    OperatingSystem: string,
    CreateDate: datetime,
    LastUpdateDate: datetime
}

Response codes

201 - Request successful. Asset in response body.

PUT Assets/{id}

Purpose

Updates an existing asset by ID.

ℹ️

Note

Call GET Assets/{id} (or equivalent) first to get the current state of the asset before calling PUT Assets/{id} to update it with new values.

Required permissions

Asset Management (Read/Write).

URL parameters

id: ID of the asset.

Request body

Content-Type: application/json

{
    WorkgroupID: int,
    AssetName: string,
    DnsName: string,
    DomainName: string,
    IPAddress: string,
    MacAddress: string,
    AssetType: string,
    Description: string,
    OperatingSystem: string,
}

Request body details

  • WorkgroupID: (required) ID of the Workgroup to which the asset belongs.
  • AssetName: (required) Asset name.
  • DnsName: (required) Asset DNS name.
  • DomainName: (required) Asset domain name.
  • IPAddress: (required) Asset IP address.
  • MacAddress: (required) Asset MAC address. An empty value is accepted and clears any existing value.
  • AssetType: (required) Asset type. An empty value is accepted and clears any existing value.
  • Description: (optional) Asset description. Only updated if version in the URL is 3.1 or greater. Max string length is 255.
  • OperatingSystem: (required) Asset operating system. An empty value is accepted and clears any existing value.

Response body

Content-Type: application/json

{
    WorkgroupID: int,
    AssetID: int,
    AssetName: string,
    DnsName: string,
    DomainName: string,
    IPAddress: string,
    MacAddress: string,
    AssetType: string,
    OperatingSystem: string,
    CreateDate: datetime,
    LastUpdateDate: datetime
}

Response codes

200 - Request successful. Asset in response body.

POST Assets/Search

Purpose

Returns a list of assets that match the given search criteria.

Required permissions

Asset Management (Read).

Query parameters (optional)

  • limit: (default: 100000) Number of records to return.
  • offset: (default: 0) Number of records to skip before returning records (can only be used in conjunction with limit).

Request body

Content-Type: application/json

{
    AssetName: string,
    DnsName: string,
    DomainName: string,
    IPAddress: string,
    MacAddress: string,
    AssetType: string,
}

Request body details

At least one request body property should be provided; any property not provided is ignored. All search criteria is case insensitive and is an exact match (equality), except for IPAddress.

IPAddress can be a single IP address (10.0.0.1), a comma-delimited list of IPs (10.0.0.1,10.0.0.2,10.0.0.3), an IP range (10.0.0.1-10.0.0.25), or CIDR notation (10.0.0.0/24).

Response body (when limit is not given)

Content-Type: application/json

[
    {
        WorkgroupID: int,
        AssetID: int,
        AssetName: string,
        DnsName: string,
        DomainName: string,
        IPAddress: string,
        MacAddress: string,
        AssetType: string,
        OperatingSystem: string,
        CreateDate: datetime,
        LastUpdateDate: datetime
    },
    …
]

Response body (when limit is given)

Content-Type: application/json

{
    TotalCount : int,
    Data :
    [
        {
            WorkgroupID: int,
            AssetID: int,
            AssetName: string,
            DnsName: string,
            DomainName: string,
            IPAddress: string,
            MacAddress: string,
            AssetType: string,
            OperatingSystem: string,
            CreateDate: datetime,
            LastUpdateDate: datetime
        },
        …
    ]
}

Response codes

200 - Request successful. Assets in response body.

DELETE Assets/{id}

Purpose

Deletes an asset by ID.

Required permissions

Asset Management (Read/Write).

URL parameters

id: ID of the asset.

Request body

None.

Response body

None.

Response codes

200 - Request successful.

DELETE Workgroups/{workgroupName}/Assets?name={name}

Purpose

Deletes an asset by Workgroup name and asset name.

Required permissions

Asset Management (Read/Write).

URL parameters

workgroupName: Name of the Workgroup.

Query parameters

name: Name of the asset.

Request body

None.

Response body

None.

Response codes

200 - Request successful.

Smart Rule Assets

GET SmartRules/{id}/Assets

Purpose

Returns a list of assets by Smart Rule ID.

Required permissions

Read access to the Smart Rule referenced by ID.

URL parameters

id: ID of the Smart Rule.

Query parameters (optional)

  • limit: (default: 100000) Number of records to return.
  • offset: (default: 0) Number of records to skip before returning records (can be used only in conjunction with limit).

Request body

None.

Response body (when limit is not given)

Content-Type: application/json

[
    {
        WorkgroupID: int,
        AssetID: int,
        AssetName: string,
        DnsName: string,
        DomainName: string,
        IPAddress: string,
        MacAddress: string,
        AssetType: string,
        OperatingSystem: string,
        CreateDate: datetime,
        LastUpdateDate: datetime
    },
    …
]

Response body (when limit is given)

Content-Type: application/json

{
    TotalCount : int,
    Data :
    [
        {
            WorkgroupID: int,
            AssetID: int,
            AssetName: string,
            DnsName: string,
            DomainName: string,
            IPAddress: string,
            MacAddress: string,
            AssetType: string,
            OperatingSystem: string,
            CreateDate: datetime,
            LastUpdateDate: datetime
        },
        …
    ]
}

Response codes

200 - Request successful. Assets in response body.

Asset attributes

GET Assets/{assetID}/Attributes

Purpose

Returns a list of attributes by Asset ID.

Required permissions

Asset Management (Read), Attribute Management (Read).

URL parameters

assetID: ID of the asset.

Request body

None.

Response body

Content-Type: application/json

[
    {
        AttributeID : int, AttributeTypeID : int,
        ParentAttributeID : int, // can be null
        ShortName : string,
        LongName : string,
        Description : string,
        ValueInt : int, // can be null
        IsReadOnly: bool
    },
    …
]

Response codes

200 – Request successful. Attributes associated with the asset in the response body.

POST Assets/{assetID}/Attributes/{attributeID}

Purpose

Assigns an attribute to an asset.

Required permissions

Asset Management (Read/Write), Attribute Management (Read/Write).

URL parameters

  • assetID: ID of the asset.
  • attributeID: ID of the attribute Request Body.

Response body

Content-Type: application/json

{
    AttributeID : int, AttributeTypeID : int,
    ParentAttributeID : int, // can be null
    ShortName : string,
    LongName : string,
    Description : string,
    ValueInt : int, // can be null
    IsReadOnly: bool,
}

Response codes

201 – Request successful. Attributes in the response body.

DELETE Assets/{assetID}/Attributes

Purpose

Deletes all asset attributes by asset ID.

Required permissions

Asset Management (Read/Write), Attribute Management (Read/Write).

URL parameters

assetID: ID of the asset.

Request body

None.

Response body

None.

Response codes

200 – Request successful.

DELETE Assets/{assetID}/Attributes/{attributeID}

Purpose

Deletes an asset attribute by asset ID and attribute ID.

Required permissions

  • Asset Management (Read/Write).
  • Attribute Management (Read/Write).

URL parameters

assetID: ID of the asset attributeID and ID of the attribute.

Request body

None.

Response body

None.

Response codes

200 – Request successful.

Attributes

GET AttributeTypes/{attributeTypeID}/Attributes

Purpose

Returns a list of attribute definitions by attribute type.

Required permissions

Attribute Management (Read).

URL parameters

attributeTypeID: ID of the attribute type.

Request body

None.

Response body

Content-Type: application/json

[
    {
        AttributeID : int,
        AttributeTypeID : int,
        ParentAttributeID : int, // can be null
        ShortName : string,
        LongName : string,
        Description : string,
        ValueInt : int, // can be null
        IsReadOnly: bool,
        ChildAttributes :
        [
            {
                AttributeID : int,
                AttributeTypeID : int,
                ParentAttributeID : int,
                ShortName : string,
                LongName : string,
                Description : string,
                ValueInt : int, // can be null
                IsReadOnly: bool,
            },
            …
        ]
    },
    …
]

Response codes

200 – Request successful. Attributes in the response body.

GET Attributes/{id}

Purpose

Returns an attribute definition by ID.

Required permissions

Attribute Management (Read).

URL parameters

id: ID of the attribute.

Request body

None.

Response body

Content-Type: application/json

{
    AttributeID : int,
    AttributeTypeID : int,
    ParentAttributeID : int, // can be null
    ShortName : string,
    LongName : string,
    Description : string,
    ValueInt : int, // can be null
    IsReadOnly: bool,
    ChildAttributes :
    [
        {
            AttributeID : int,
            AttributeTypeID : int,
            ParentAttributeID : int,
            ShortName : string,
            LongName : string,
            Description : string,
            ValueInt : int, // can be null
            IsReadOnly: bool,
        },
        …
    ]
}

Response codes

200 – Request successful. Attributes in the response body.

POST AttributeTypes/{attributeTypeID}/Attributes

Purpose

Creates a new attribute definition by attribute type ID.

Required permissions

Attribute Management (Read/Write).

URL parameters

attributeTypeID: ID of the attribute type.

Request body

Content-Type: application/json

{
    ParentAttributeID : int, // can be null
    ShortName : string,
    LongName : string,
    Description : string,
    ValueInt : int // can be null
}

Request body details

Max string length for ShortName and LongName is 64. Max string length for Description is 255.

Response body

Content-Type: application/json

{
    AttributeID : int,
    AttributeTypeID : int,
    ParentAttributeID : int, // can be null
    ShortName : string,
    LongName : string,
    Description : string,
    ValueInt : int, // can be null
    IsReadOnly: bool,
    ChildAttributes :
    [
        {
            AttributeID : int,
            AttributeTypeID : int,
            ParentAttributeID : int,
            ShortName : string,
            LongName : string,
            Description : string,
            ValueInt : int, // can be null
            IsReadOnly: bool,
        },
        …
    ]
}

Response codes

201 – Request successful. Attributes in the response body.

DELETE Attributes/{id}

Purpose

Deletes an attribute definition by ID.

Required permissions

Attribute Management (Read/Write).

URL parameters

id: ID of the attribute.

Request body

None.

Response body

None.

Response codes

200 – Request successful.

Attribute types

GET AttributeTypes

Purpose

Returns a list of attribute types.

Required permissions

Attribute Management (Read).

Request body

None.

Response body

Content-Type: application/json

[
    {
        AttributeTypeID : int,
        Name : string,
        IsReadOnly: bool
    },
    …
]

Response codes

200 – Request successful. Attribute types in the response body.

GET AttributeTypes/{id}

Purpose

Returns an attribute type by ID.

Required permissions

Attribute Management (Read).

URL parameters

id: ID of the attribute type.

Request body

None.

Response body

Content-type: application/json

{
    AttributeTypeID : int,
    Name : string,
    IsReadOnly: bool
}

Response codes

200 – Request successful. Attribute type in the response body.

POST AttributeTypes

Purpose

Creates a new attribute type.

Required permissions

Attribute Management (Read/Write).

Request body

Content-Type: application/json

{
    Name : string
}

Request body details

Max string length for Name is 64.

Response body

Content-type: application/json

{
    AttributeTypeID : int,
    Name : string,
    IsReadOnly: bool
}

Response codes

201 – Request successful. Attribute type in the response body.

DELETE AttributeTypes/{id}

Purpose

Deletes an attribute type and all related attributes by ID.

Required permissions

Attribute Management (Read/Write).

URL parameters

id: ID of the attribute type.

Request body

None.

Response body

None.

Response codes

200 – Request successful.

Databases

GET Databases

Purpose

Returns a list of databases.

Required permissions

Asset Management (Read).

Request body

None.

Response body

Content-Type: application/json

[
    {
        AssetID: int,
        DatabaseID : int,
        PlatformID : int,
        InstanceName : string,
        IsDefaultInstance : bool,
        Port : int,
        Version : string,
        Template:string
    },
    …
]

Response codes

201 – Request successful. Databases in the response body.

GET Databases/{id}

Purpose

Returns a database by ID.

Required permissions

Asset Management (Read).

URL parameters

id: ID of the database.

Request body

None.

Response body

Content-Type: application/json

{
    AssetID:int,
    DatabaseID : int,
    PlatformID : int,
    InstanceName : string,
    IsDefaultInstance : bool,
    Port : int,
    Version : string
}

Response codes

201 – Request successful. Databases in the response body.

GET Assets/{id}/Databases

Purpose

Returns a list of databases for the given asset.

Required permissions

Asset Management (Read).

URL parameters

id: ID of the asset.

Request body

None.

Response body

Content-Type: application/json

[
    {
        AssetID: int,
        DatabaseID : int,
        PlatformID : int,
        InstanceName : string,
        IsDefaultInstance : bool,
        Port : int,
        Version : string,
        Template:string
    },
…

Response codes

201 – Request successful. Databases in the response body.

POST Assets/{id}/Databases

Purpose

Creates a new database in the asset referenced by ID.

Required permissions

Asset Management (Read/Write).

URL parameters

id: ID of the asset.

Request body

Content-Type: application/json

{
    PlatformID : int,
    InstanceName : string,
    IsDefaultInstance : bool,
    Port : int,
    Version : string,
    Template : string,
}

Request body details

  • PlatformID: (required) ID of the platform
  • InstanceName: Name of the database instance. Required when IsDefaultInstance is false. Max string length is 100.
  • IsDefaultInstance: True if the database instance is the default instance, otherwise false.

ℹ️

Note

Only MS SQL Server and MySQL platforms support setting this value to true.

  • Port: (required) The database port.
  • Version: The database version. Max string value is 20.
  • Template: The database connection template.

Response body

Content-Type: application/json

{
    AssetID: int,
    DatabaseID : int,
    PlatformID : int,
    InstanceName : string,
    IsDefaultInstance : bool,
    Port : int,
    Version : string,
    Template:string
}

Response codes

200 – Request successful. Databases in the response body.

PUT Databases/{id}

Purpose

Updates an existing database by ID.

Required permissions

Asset Management (Read/Write).

URL parameters

id: ID of the database.

Request body

Content-Type: application/json

{
    PlatformID: int,
    InstanceName: string,
    IsDefaultInstance: bool,
    Port: int,
    Version: string,
    Template: string
}

Request body details

  • PlatformID: (required) ID of the platform.
  • InstanceName: Name of the database instance. Required when IsDefaultInstance is false. Max string length is 100.
  • IsDefaultInstance: True if the database instance is the default instance, otherwise false.

ℹ️

Note

Only MS SQL Server and MySQL platforms support setting this value to true.

  • Port: The database port.
  • Version: The database version. Max string length is 20.
  • Template: The database connection template.

Response body

Content-Type: application/json

{
    AssetID: int,
    DatabaseID: int,
    PlatformID: int,
    InstanceName: string,
    IsDefaultInstance: bool,Port: int,
    Version: string,
    Template: string
}

Response codes

200 – Request successful. Databases in the response body.

DELETE Databases/{id}

Purpose

Deletes a database by ID.

Required permissions

Asset Management (Read/Write).

URL parameters

id: ID of the database.

Request body

None.

Response body

None.

Response codes

200 – Request successful.

Deprecated

The content in this section of the guide has been deprecated and is compatible with earlier versions only.

Imports

[deprecated] POST Imports/QueueImportFile

ℹ️

Note

This API has been deprecated and is available for backwards compatibility only. Use POST Imports with Base64FileContents instead.

Purpose

Queues a Password Safe XML import using multi-part form-data content.

Required permissions

Scan Management (Read/Write).

Request body

Content-Type: multipart/form-data

{
    Content-type: application/json
    {
        WorkgroupID: int,
        FileName: string
    }
    application/octet-stream
    {
        <string-encoded byte array representing the file>
    }
}
Request body details
  • WorkgroupID: ID of the Workgroup to import the assets into.
  • FileName: Filename (including extension) of the import file.
Response body

Content-Type: application/json

{
    ImportID: int
}
Response codes
  • 200 – Request successful. Import ID in the response body.
  • 400 – The import file was not found in the body of the request, or a request body validation error has occurred.

Smart Rules

[deprecated] POST SmartRules/FilterSingleAccount

ℹ️

Note

This API has been deprecated and is available for backwards compatibility only. Use QuickRules instead.

Purpose

Specialized action for creating a Managed Account-type Smart Rule for filtering a single Managed Account by System Name and Account Name.

Required permissions

Smart Rule Management - Managed Account (Read/Write).

Request body

Content-type: application/json

{
    AccountID: int,
    Title: string
}
Request body details
  • AccountID: (required) ID of the managed account you want to filter by parent System Name and Account Name.
  • Title: (optional) The title/name of the new Smart Rule. If omitted, a unique title is auto-generated.
Response body

Content-Type: application/json

{
    SmartRuleID: int,
    OrganizationID : string, // can be null
    Title: string,
    Description: string,
    Category: string,
    Status: int,
    LastProcessedDate: datetime,
    IsReadOnly: bool,
    RuleType: string
}
Response codes

201 – Request successful. Smart Rule in the response body.

User Groups

[deprecated] GET UserGroups/{name}

ℹ️

Note

This API has been deprecated and is available for backwards compatibility only. Use GET UserGroups?name={name} instead.

Purpose

Returns a user group by name.

Required permissions

User Accounts Management (Read).

URL parameters

name: Name of the user group.

Request body

None.

Response body

Content-Type: application/json

{
    GroupID : int, Name : string,
    DistinguishedName : string, 
    GroupType : string, 
    AccountAttribute : string, 
    MembershipAttribute : string,
    IsActive : bool
}
Response codes

200 – Request successful. User group in the response body.

[deprecated] DELETE UserGroups/{name}

ℹ️

Note

This API has been deprecated and is available for backwards compatibility only. Use DELETE UserGroups?name={name} instead.

Purpose

Deletes a user group by name.

Required permissions

User Accounts Management (Read/Write).

URL parameters

name: Name of the user group.

Request body

None.

Response body

None.

Response Codes

200 – Request successful.

Workgroups

[deprecated] GET Workgroups/{name}

ℹ️

Note

This API has been deprecated and is available for backwards compatibility only. Use GET Workgroups?name={name} instead.

Purpose

Returns a Workgroup by name.

Required permissions

Current user has permission to the Workgroup Organization. Asset Management (Read) or Scan Management (Read/Write).

Query parameters

name: Name of the Workgroup.

Request body

None.

Response body

Content-Type: application/json

{
    OrganizationID : string,
    ID : int,
    Name : string
}
Response codes

200 – Request successful. Workgroups in the response body.

Entitlements

GET Entitlements

Purpose

Returns user entitlements.

Required permissions

Analytics and Reporting (Read).

URL parameters

None.

Request body

None.

Response body

Content-Type: application/json

[
    {
        GroupID : int,
        Name : string,
        SmartRuleId : int,
        DistinguishedName : string,
        AccessLevel : string, // can be null
        RoleId : int,
        RoleName : string,   
        DedicatedAccountPermissionOverride : string, // can be null
        DedicatedToAppUserID : int, // can be null
        DedicatedToAppUserName : string, // can be null
        IsAdministratorGroup : bool,
        UserID : int,
        UserName : string,
        ManagedAccountId : int,       
        AccountName : string,
        RationalizedSystemName : string,
        ApplicationName : string,
        AccessPolicyName : string
    }
]

GET Entitlements?groupIDs={groupID1,groupID2,groupID3…}

Purpose

Returns user entitlements for the specified group IDs.

Required permissions

Analytics and Reporting (Read).

URL parameters

groupIDs: Comma separated list of group IDs

Request body

None.

Response body

Content-Type: application/json

[
    {
        GroupID : int,
        Name : string,
        SmartRuleId : int, 
        Title : string,
        SmartRuleType : string,
        AccessLevel : string, // can be null
        RoleId : int,
        RoleName : string,   
        DedicatedAccountPermissionOverride : string, // can be null
        DedicatedToAppUserID : int, // can be null
        DedicatedToAppUserName : string, // can be null
        IsAdministratorGroup : bool,
        UserID : int,
        UserName : string,
        ManagedAccountId : int,       
        AccountName : string,
        RationalizedSystemName : string,
        ApplicationName : string,
        AccessPolicyName : string
    }
]

EPM Policies

POST /{id}/epmapplications/add

Purpose

Edits a policy to add an application, and updates this policy in the BeyondInsight database. Touches the LastModifiedDate to indicate that a change is made. Updated policy is deployed to agents per the usual process in BeyondInsight.

Required permissions

EPM (Read/Write)

EPM Policy (Read/Write)

Query parameters (optional)

{id} is a Policy Guid

Request body

Content-Type: application/json

{
        GroupName: string,
        Name: string,
     Path: string,
     Publisher: string,
     ChildrenInheritToken: boolean
    }

Request body details

All fields are required.

Example request

{
        "GroupName":"powershell - Add",
        "Name":"notepad3.exe",
     "Path":"C:\\Windows\\System32\\notepad2.exe",
     "Publisher":"Microsoft2",
     "ChildrenInheritToken":"false"
    }

Response body

Content-Type: application/json

{
        <empty>
    }

Response codes

200 – OK, successful

400 – Invalid Policy ID

Imports

POST Imports

Purpose

Queues a third-party import.

Required permissions

Scan Management (Read/Write).

Request body

Content-Type: application/json

{
    WorkgroupID: int,
    ImportType: string,
    Filter: string,
    FileName: string,
    FileContents: byte[],
    Base64FileContents: string
}

ℹ️

Note

Provide either FileContents or Base64FileContents.

Request body details

  • WorkgroupID: ID of the Workgroup to import the assets into

  • ImportType: (case-senstitive, default: PASSWORDSAFE) Type of import being queued:

    • PASSWORDSAFE:Password Safe import file. Expected file extension: .xml.

    • RETINARTD: Retina© RTD file. Expected file extension: .rtd.

      ℹ️

      Note

      Support for the following file types has been deprecated and will be removed from the product in a future version.

    • NESSUS: Nessus© import file. Expected file extension: .csv.

    • NESSUSSECCEN: NessusSecurityCenter© import file. Expected file extension: .csv.

    • NEXPOSE: Nexpose© import file. Expected file extension: .csv or .xml.

    • QUALYSGUARD: QualysGuard© file. Expected file extension: .csv or .xml.

    • METASPLOIT: METASPLOIT© import file. Expected file extension: .xml.

    • MCAFEEVM: McAfee Vulnerability Management© import file. Expected file extension: .csv.

    • TRIPWIRE: Tripwire© import file. Expected file extension: .csv.

  • Filter: (default: All Assets) Asset selection filter:

    • All Assets: No filter, import all.
    • Single IPv4 address (i.e. 10.0.0.1).
    • IPv4 range (i.e. 10.0.0.1-10.0.0.5).
    • CIDR (i.e. 10.0.0.0/24).
  • FileName: Filename (including extension) of the import file. One of the following is required:

    • FileContents: The array containing the content of the import file.
    • Base64FileContents: Base64 string containing the content of the import file.

Response body

Content-Type: application/json

{
    ImportID: int
}

Response codes

200 – Request successful. Import ID in the response body.

Operating Systems

GET OperatingSystems

Purpose

Returns a list of operating systems.

Required permissions

Asset Management (Read).

Request body

None.

Response body

Content-Type: application/json

[
    {
        OperatingSystemID : int,
        Name : string
    },
    …
]

Response codes

200 – Request successful. Operating systems in the response body.

Organizations

GET Organizations

Purpose

Returns a list of organizations to which the current user has permission.

Required permissions

Asset Management (Read).

Request body

None.

Response body

Content-Type: application/json

[
    {
        OrganizationID : string,
        Name : string,
        IsActive : bool
    },
    …
]

Response codes

200 – Request successful. Organizations in the response body.

GET Organizations/{id}

Purpose

Returns an organization by ID.

Required permissions

  • Current user has permission to the organization.
  • Asset Management (Read).

URL parameters

id: ID of the organization.

Request body

None.

Response body

Content-Type: application/json

{
    OrganizationID : string,
    Name : string,
    IsActive : bool
}

Response codes

200 – Request successful. Organizations in the response body.

GET Organizations?name={name}

Purpose

Returns an organization by name.

Required permissions

  • Current user has permission to the organization
  • Asset Management (Read).

Query parameters

name: Name of the organization.

Request body

None.

Response body

Content-Type: application/json

{
    OrganizationID : string,
    Name : string,
    IsActive : bool
}

Response codes

200 – Request successful. Organizations in the response body.

Permissions

(i.e., Asset Management, User Accounts Management, Scan Management, etc.)

GET Permissions

Purpose

Returns a list of permissions.

Required permissions

User Accounts Management (Read).

Request body

None.

Response body

Content-Type: application/json

[
    {
        PermissionID : int,
        Name : string
    },
    …
]

Response codes

200 – Request successful. Permissions in the response body.

User group permissions

GET UserGroups/{userGroupID}/Permissions

Purpose

Gets all permissions for the user group referenced by ID.

Required permissions

User Accounts Management (Read).

URL parameters

userGroupId: ID of the user group.

Request body

None.

Response body

Content-Type: application/json

[
    {
        PermissionID : int,
        AccessLevelID : int
    },
…]

Response codes

200 – Request successful. Permissions in the response body.

POST UserGroups/{userGroupId}/Permissions

Purpose

Sets permissions for the user group referenced by ID.

Required permissions

User Accounts Management (Read/Write).

ℹ️

Note

  • Adding the Secrets Safe feature/permission to a user group requires the caller to be an administrator.
  • The access level for Secrets Safe cannot be changed to disabled if the group has associated secrets.

URL parameters

userGroupId: ID of the user group.

Request body

Content-Type: application/json

[
    {
        PermissionID : int,
        AccessLevelID : int
    },
    …
]

Response body

None.

Response codes

204 – Request successful. No content in body.

DELETE UserGroups/{userGroupId}/Permissions

Purpose

Deletes all permissions for the user group referenced by ID.

Required permissions

User Accounts Management (Read/Write).

ℹ️

Note

  • Removing the Secrets Safe feature/permission from a user group requires the caller to be an administrator.
  • Permissions for a User Group that has the Secrets Safe feature enabled cannot be deleted if the group has associated secrets.

URL parameters

userGroupId: ID of the user group.

Request body

None.

Response body

None.

Response codes

200 – Request successful.

Smart Rules

GET SmartRules

Purpose

Returns a list of Smart Rules to which the current user has at least read access.

Query parameters

type: (optional, default: all) Type of Smart Rules to return (all, managed account, managed system, and asset).

Request body

None.

Response body

Content-Type: application/json

[
    {
        SmartRuleID: int,
        OrganizationID : string, // can be null
        Title: string,
        Description: string,
        Category: string,
        Status: int,
        LastProcessedDate: datetime,
        IsReadOnly: bool,
        RuleType: string
    },
    …
]

Response codes

200 – Request successful. Smart Rule in the response body.

GET SmartRules/{id}

Purpose

Returns a Smart Rule by ID.

Required permissions

Read access to the Smart Rule referenced by ID.

URL parameters

id: ID of the Smart Rule.

Request body

None.

Response body

Content-Type: application/json

{
    SmartRuleID: int,
    OrganizationID : string, // can be null
    Title: string,
    Description: string,
    Category: string,
    Status: int,
    LastProcessedDate: datetime,
    IsReadOnly: bool,
    RuleType: string
}

Response codes

200 – Request successful. Smart Rule in the response body.

GET UserGroups/{id}/SmartRules/

Purpose

Returns a list of Smart Rules to which the given user group ID has at least read access.

Requirements

User Accounts Management (Read).

URL parameters

id: ID of the user group.

Query parameters

accessLevel: (optional, default: 1,3) User group Smart Rule access level - A single value or comma-delimited list of values:

  • 0: None.
  • 1: Read.
  • 3: Read/Write.

Request body

None.

Response body

Content-Type: application/json

[{
    SmartRuleID: int,
    OrganizationID : string, // can be null
    Title: string,
    Description: string,
    Category: string,
    Status: int,
    LastProcessedDate: datetime,
    IsReadOnly: bool,
    RuleType: string,
    AccessLevelID: int,
}
,...
]

Response codes

200 – Request successful. Smart Rules with user group access level in the response body.

GET SmartRules?title={title}

Purpose

Returns a Smart Rule by title.

In a multi-tenant environment, assumes global organization.

Required permissions

Read access to the Smart Rule referenced by title.

Query parameters

title: Title of the Smart Rule.

Request body

None.

Response body

Content-Type: application/json

{
    SmartRuleID: int,
    OrganizationID : string, // can be null
    Title: string,
    Description: string,
    Category: string,
    Status: int,
    LastProcessedDate: datetime,
    IsReadOnly: bool,
    RuleType: string
}

Response codes

200 – Request successful. Smart Rule in the response body.

GET Organizations/{orgID}/SmartRules?title={title}

Purpose

Returns a Smart Rule by organization ID and title. This is only valid in a multi-tenant environment.

Required ermissions

Read access to the Smart Rule referenced by organization and title.

URL parameters

orgID: ID of the organization.

Query parameters

title: Title of the Smart Rule.

Request body

None.

Response body