Introduction

The IntelAgree API is designed to facilitate integrations with IntelAgree. It is a REST API that uses the JSON data format. The IntelAgree development team is actively maintaining and enhancing the API and its associated documentation. If you have a feature request or feedback for the API, please provide it to your IntelAgree Account Manager or Implementation Manager, who will relay it to the development team.

You can download a Postman collection containing all available operations in version 2 of the API here.

API Versions

There are currently two versions of the API, the original version and version 2. The original version remains active to support legacy integrations that use it, but all new enhancements will be applied exclusively to version 2. We recommend using version 2. The remainder of this Getting Started guide will refer to version 2. Some of the information provided will not be applicable to the original version.

To use version 2 of the API, send an ApiVersion header with the value "2.0" in every request, as follows:

"ApiVersion": "2.0"

If you omit the ApiVersion header, you will be using the original version by default.

Authorization

Before you can use the API, you will need an Account Key and a Subscription Key that uniquely identify your subscription and API user to IntelAgree. If you do not have these values, you can contact your IntelAgree Account Manager or Implementation Manager to get them generated for you.

Every request to the API should include the following header with your Subscription Key:

"Ocp-Apim-Subscription-Key": "YourSubscriptionKeyValue"

Before you make any other requests to the API, you must first retrieve a token from the POST /Accounts endpoint. The request should look as follows, using your Account Key:

POST https://apim.intelagree.com/api/Accounts
{
"accountKey": "YourAccountKeyValue"
}

This will respond with a token and its expiration:

{
"token": "YourEncryptedTokenValue"
"expires": "2023-01-01T23:59:59.9999999Z"
}

You should use your token value as the Bearer token in an Authorization header on any other requests to the API until the token expires, which will be 2 hours after the time it is issued.

"Authorization": "Bearer YourEncryptedTokenValue"

If you omit the Authorization header on calls to the API or you provide an invalid or expired token, the API will respond with a 401 (Unauthorized) error.

Business Keys

In the API, entities can be identified directly by their IDs. But, integrations are often built in such a way that they don't know the IntelAgree IDs of the entities that they use. For that reason, the API supports the use of BusinessKeys. BusinessKeys allow an integration to create a relationship between an IntelAgree entity and an entity in an integrated system. Then, the entity's ID in the integrated system can be used to identify the IntelAgree entity in the API. Every BusinessKey has the following properties:

  • Name: The name of the integrated system that the entity is associated with (e.g. "Salesforce", "Workday", "Bullhorn", etc.)

  • Value: The value of the ID of the associated entity in the integrated system.

For instance, if you were creating an integration between IntelAgree and Salesforce, you might create IntelAgree Contracts through the API using information from a Salesforce Opportunity record and associate each Contract to the Opportunity by giving the Contract a BusinessKey. If the Opportunity had the ID "OPP1234" in Salesforce, then you would include the following BusinessKey in your request to create the Contract:

{
 Name: "Salesforce", 
 Value: "OPP1234"
}

The API allows you the flexibility of identifying entities either by their IntelAgree ID or a BusinessKey. For instance, in the example above if the IntelAgree Contract was created with ID 42, the following requests to GET the Contract would be equivalent:

GET https://apim.intelagree.com/api/contracts/42
GET https://apim.intelagree.com/api/contracts/Salesforce/OPP1234

Anywhere in the API where a request includes a BusinessKey, you can optionally use "IntelAgree" as the Name and the IntelAgree ID of the entity as the Value. You might do this if the entity doesn't have an associated BusinessKey or your integration component only knows about the IntelAgree ID of the entity.

BusinessKeys can be used to identify the following IntelAgree entities through the API

  • Attachments

  • Attributes

  • Contracts

  • ContractTypes

  • LegalEntities

  • Parties

  • Users

Impersonation

The Account Key and Subscription Key that you use to authenticate to the IntelAgree API belong to an API user in your IntelAgree subscription. That user has broad permissions within IntelAgree. By default, this API user will be recorded on any action taken from the API. If you are building an integration that responds to actions taken by an IntelAgree user in an integrated system, you may want to enforce that user's permissions and record that user's access within the IntelAgree API. For that, the API supports user impersonation. Impersonation allows you to make a request to the API as a specific IntelAgree user other than the API user. Some actions in the API, for instance creating a Contract, require impersonation. The API documentation for each endpoint will say "Impersonation Required" when this is the case.

To impersonate an IntelAgree user through the API, you include two headers with your request which identify the user you are impersonating by their BusinessKey:

  • AsUserType: This is the Type of the user's BusinessKey. Otherwise known as the Name of the BusinessKey. This should be the name of the integrated system.

  • AsUserKey:: This is the Value of the user's BusinessKey. This should be the ID of the user in an integrated system.

For example, if you were impersonating an IntelAgree user associated with a Salesforce user account with the Salesforce ID "UID1234", you would send the following headers:

"AsUserType": "Salesforce"
"AsUserKey": "UID1234"

As with other BusinessKeys, you can use "IntelAgree" in the AsUserType header if you want to identify your user with an IntelAgree ID in the AsUserKey header. You might do this if the user you're impersonating does not have an associated BusinessKey, or if your integration only knows the user's IntelAgree ID.

Rate Limiting

Your IntelAgree subscription includes up to 50,000 API requests in any 24 hour period. After that limit has been reached, the API will respond to any subsequent requests with at 403 (Forbidden) error. The response body will include a message indicating when requests can be made again.

Error Codes

The API uses the following HTTP error codes:

  • 400 - Bad Request: Your request invalid. Most likely the JSON in the request body is malformed.

  • 401 - Unauthorized: Your API token is invalid or expired.

  • 403 - Forbidden: Either your impersonated user does not have permission to perform the action requested or you may have reached your API request limit.

  • 404 - Not Found: The specified entity or action does not exist.

  • 422 - Unprocessable Entity: The request failed a validation of IntelAgree's business rules.

  • 500 - Internal Server Error: The API encountered a problem on our server.

  • 503 - Service Unavailable: The API is temporarily down for maintenance.

Most errors will include additional information in the response body that can help you troubleshoot the cause of the error.