Entities Reports API

Entities Reports API is the developer interface for Diligent Entities that you can use to integrate Diligent Entities with other systems in your company.

For Entities Reports API documentation, refer to Diligent Developer Portal.

Setting up access to Entities Reports API

Before you start interacting with the Reports API, you must complete the following steps required for access:

1. Request site configuration for API calls.

2. Create a user for API access.

3. Generate the access token.

Request site configuration for API calls

Each Entities site you want to make API calls to requires internal network configuration. Site configuration can take between 5 and 10 business days.

To request API configuration for your sites, contact your Customer Success Manager and provide the URL of each site you want to configure for API calls, including test sites.

Download API values

After each site is configured, you receive an email with a link to an API configuration values file.

1. Select View Content in the email to access the file shared with you.

2. In Secure File Sharing, select Download from the document menu to save the Entities API Values document to your computer.

Create a user for API calls

Only users with relevant access permissions can access Entities Reports API. We recommend creating an Entities user that you will use only for API access.

The user for accessing Entities Reports API needs the following:

• Read-only access to Entities

• The API Key Management user role right

• A contact email address your organization can access

Create a new user role

Create a new user role for accessing the API. To do this, you can clone an existing read-only user role.

For detailed instructions, go to New User Role.

When setting up a new user role, configure the following for the API user:

1. Clone or create a role with read-only access permissions.

2. In User Role Rights, select API Key Management.

Additional access permissions

You may need to adjust the user role rights or permissions. Configure the user account for API access with all access permissions you need to perform API calls. For example, if you want to retrieve data through the Companies endpoint, your API user must have permission to access company data.

To find out which permissions are needed, send a Get metadata request to each endpoint you want to retrieve the data from. The requiredAccessRight field in the response contains the information about the necessary user permissions. Add them to the user role.

Create a new user

1. Create a new user account. For detailed instructions, go to Create User Accounts.

2. For API access, configure the following:

   • From Default User Role, select the user role you created in the previous step.

   • Make sure that no groups are selected in Security Groups.

   • Provide a contact email that your organization can access.

   • Turn off multi-factor authentication.

Once you create the user account, use the password setup link to create a password for the API user.

Generate the API access token

1. Use the new API user credentials to log in to Entities.

2. Select Admin Hub > Manage API Access Tokens.

3. On the Manage API Access Tokens page, select Add.

4. In the New Access Token window, enter a description for the token. This description will be used to identify the token.

5. In the Token expires in field, enter the number of days for the token to remain active. Enter a number between 1 and 365.

6. Select Generate.

7. Select Copy to save the token.

   You will need the token for authenticating to Entities Reports API. After you close the window, the token will not be shown again.

8. Select Close.

   The token description is displayed in the table on the Manage API Access Tokens page. Tokens are listed in the order of their expiration dates. For expired tokens, the expiration date is shown in red text.

Manage access tokens

You can change the token's description or permanently delete the token.

Find the token in the table and select the three vertical dots icon to display the options: Edit and Delete.

Accessing Entities Reports API

Follow instructions in Diligent Developer Portal to authenticate to Entities Reports API and start making calls.