How much apidocs.agilityblue.com is worth?

Agility Blue OData REST API

The Agility Blue OData REST API offers a way for you to manage Agility Blue resources in a programmatic way using conventional verb-driven HTTP requests. The endpoints are intuitive and powerful, allowing you to make calls to create, retrieve, update, or delete (CRUD) data housed within the Agility Blue platform. Most of the resource endpoints implement the [OData v4 specification](https://www.odata.org/documentation/) to allow for filtering, sorting, expanding, and paging within a single resource call making it simple and fast to drill into data. The surface area of the API is highly inclusive. All official Agility Blue client applications are built using it. Anything you can do on the management site can be done programatically with the API - and more. This allows you to create powerful extensions and integrations that can extend far beyond the reaches and capabilities of the official applications. Typical examples of extensibility include connecting Agility Blue to other systems to automate pushing or pulling data (such as case management or billing systems), creating custom import/export tools, or authoring power business intelligence (BI) documents to gain additional metric insights. This document will start with a general overview about the design and implementation technology, followed by the entity reference information for specific resources. # Authorization and Authentication In order to utilize the API, you need an active Agility Blue user account (Authorization) and a valid Agility Blue API Key (Authentication). Every request made to the API needs a valid Api Key, or you will probably get a `401 Unauthorized` response. The only exception to this is the versions endpoint ({{base_url}}/versions). You can check this endpoint using your browser or a `GET` call without any authentication to receive a list of name-key value pairs containing versions to the various platform builds. This information may be useful to check from time to time as some resources may not be available in earlier versions of the API. Once you have a valid user account, you can go to your account page within the main application and click on the **developer** tab. From there, you can generate new API keys or revoke keys you are no longer using. API Keys run in the same context as the user they are generated for, so be careful with how you store or expose them! # Making API Requests Any tool that is fluent in HTTP can communicate with the API by requesting a resource endpoint. For testing, we recommend using Postman, PowerShell, Fiddler, or cURL. Requests must be made using the HTTPS protocol so that traffic is encrypted. The API responds to different methods depending on the action required based on the following schema. ``` METHOD protocol://baseApiUrl/odata/route/resource/entityId/action?queryParams HTTP/1.1 ``` _Not every request requires the full schema unless the endpoint you're trying to access requires it. The schema is meant to be a conceptual model to help you understand how URIs are consumed._ ## Examples of API requests Get a single matter entity from the `workspace` route: ``` GET {{base_url}}/odata/workspace/matters/1 ``` _This example shows a simple API request to retrieve a single matter entity from the API. The OData convention for requesting a single entity requires that you place the id within parenthesis on the entity collection (the entity collection is "matters" in this case)._ --- Get a collection of projects from the `workspace` route, ordered by when the projects were created by descending sort order and returning the top 10 results ``` {{base_url}}/odata/workspace/projects?$orderby=CreatedOn desc&$top=10 ``` _This example shows an API request directly on the entity collection ("projects") with OData query parameters used to help order and limit the number of results returned. It's considered good practice to shape and limit the number of collection results you want through_ `_$filter_`_**,_ `_$orderby_`_**,_ `_$top_`_**, and_ `_$skip_` _query parameters because the less you ask for, the faster the request. Please note that the API imposes an internal limit on the number of entities it will return for each collection (typically around 2000 entities). If you need to return more than the API will provide, you will need to make subsequent API calls utilizing the paging query parameters_ `_$top_` _and_ `_$skip_` ## Method The method in the URI schema is the desired http verb used in each request. Each resource will document what methods are accepted (typically `GET`, `POST`, `PUT`, and `DELETE`). Be mindful of what method you use when you make API requests because the actionable URI for many resources is identical other than the method being used. For example, making a single entity `GET` request is the same URI schema for making a single entity `DELETE` request. | Method | Usage | | --- | --- | | GET | For retrieving entities. `GET` requests typically involve retrieving sets of data or retrieving individual entities by supplying an id parameter surrounded by parenthesis. `GET` methods do not alter data and should be considered as read-only access. Note that entity collections are almost always plural (such as "workspaces", "clients", "projects", "tasks", etc) and data is always returned as [JSON-formatted content](https://www.json.org/json-en.html). | | POST | For creating new entities or performing actions that generally result in mutating data. `POST` requests typically involve sending a JSON-formatted payload (the body of the request) to the API using entity-specific properties to create new instances of the entity. | | PUT | For updating existing entities. `PUT` requests involve sending a JSON-formatted payload (the body of the request) to the API with entity-specific properties to update existing entities. **Important:** `PUT` requests are _not_ partial updates. This means that all properties must be supplied, even if the caller did not alter specific properties. Properties that are blank or not present in the payload will update the entity with a blank or null value (or throw an error if the property was required). Typical workflows for updating entities involve retrieving an entity using the `GET` method, altering a few properties, and then submitting a `PUT` request using the altered entity. | | PATCH | For updating existing entities. `PATCH` requests are are similar to `PUT` requests with the exception that the entire entity is not required to update it. This is a partial request, so only the properties provided in the request body will be updated on the entity. | | DELETE | For removing or deleting existing entities. `DELETE` requests typically involve supplying an id parameter surrounded in parenthesis, meaning that a payload (the body of the request) is not necessary. In most cases, dependent entities will be removed automatically. | ## Protocol Unless you are using a development environment, the protocol is always `https`. The API will not accept unsecure requests. ## Base API URL The base API URL token used in this documentation is: ``` {{base_url}} ``` _Replace the Base API URL token with the API used by your organization:_ > **U.S. Pro Instance:** [https://api.agilityblue.com](https://api.agilityblue.com) **Canada Pro Instance:** [https://agilityblue.com/ca/api](https://agilityblue.com/ca/api) **Enterprise Instance:** https://{organizationSubDomain}.agilityblue.com/api _Please consult your organization administrator or_ [support@sadiebluesoftware.com](https://mailto:support@sadiebluesoftware.com) _if you're unsure what base API URL you should be using._ ## Rate limits The API imposes rate limits to the number of requests that can be performed per second. This limit is different depending the environment and the request. For example, Enterprise accounts have more freedom to make many more requests per second because their environment is isolated. In addition to the environment, specific resource endpoints may have limit restrictions. ## Request Timeouts If a request takes longer than 30 seconds, it runs the risk of being timed out by the system depending on the environment and the current load. If you experience frequent request timeouts, you should try to alter the scope of your requests by using less `$expand` nodes or leveraging the `$top` and `$skip` odata paging query parameters on collections of entities. ## Request Headers There are a few headers that you will need to provide in order for the API to process your request. | Header | Description | | --- | --- | | Accept | While the Accept header is not required, it may be helpful to eliminate some extra OData property information. The API will always return content in the JavaScript Object Notation (JSON) format. `application/json; odata.metadata=none` | | Authorization | The Authorization header is required for every request to the API. If you attempt to access the API without a valid API Key defined in the Authorization header, you will be met with a `401 Unauthorized` response. You can retrieve your API Key by visiting your account profile page, navigating to the **developer** tab, and clicking on the Generate Key button. **Head's up!** Your API Key is unique to your account and should not be shared with anyone. If you feel that your API Key has been compromised, revoke it in the developer tab on your user account page within Agility Blue. Example: `ApiKey 00a6af7ff3344c389bd402770b035000` _Please note that the "ApiKey" schema at the beginning is needed in the header value, followed by a space, followed by your API Key_ | | Content-Type | The Content-Type header tells the API what format the request body is in when using the `POST` and `PUT` methods. In almost all cases, this should be `application/json` unless specified otherwise in the documentation. | | X-Workspace-Id | A workspace id must be supplied when attempting to access any `workspace` route resources (explained further below under "Routes"). The workspace id can be found by either querying the workspaces entity collection using the `master` route or within Agility Blue by adding the id column to the workspaces grid and looking it up. Attempting to use the `workspace` route without a valid `X-Workspace-Id` header that you don't have access to will result in a `403 Forbidden` response. Example: `1` _Tip: You can also find your workspace id when on the Agility Blue management site by looking at the URL. For instance, the URL_ `_{{base_url}}/workspace/1/dashboard/allProjects_` _here shows a one (1) after the "workspace" route indicating that the id of this workspace is 1._ | # Receiving API Responses When a `GET`, `POST`, or `PUT` request is successful, a response body will include the content in JSON format and either a status code of `200 OK` or `201 Created`. `DELETE` requests will return an empty response body with a status code of `204 No Content` to indicate a successful request. If a response body contains content, the content will either be a single object or an OData collection object wrapper. A single object is simply a JSON object. A collection response, however, will also be a single JSON object, but it will always contain a property named `value` that holds the array of JSON entities. A total count parameter can be added to a collection object wrapper by supplying the OData query parameter `$count=true` (useful in situations where you may want to implement a paging strategy). For example, if you send a GET request to `{{base_url}}/odata/workspace/clients/1` you will get back a single client entity (specifically, a client that has the ClientId of 1 in this example). However, if you send the GET request to the collection of clients at `{{base_url}}/odata/workspace/clients`, you will get back a collection wrapper with a parameter named `value` containing a collection of all client entities. ## Example Response Types Single Entity Response: ``` HTTP/1.1 200 OK { "Id": 1, ... } ``` --- Entity Collection Response: ``` HTTP/1.1 200 OK { "@odata.count": 2, "value": [ { "Id": 1, ... }, { "Id": 2, ... } ] } ``` # HTTP Statuses and Errors Along with the HTTP methods that the API responds to, it will also return standard HTTP statuses, including error codes. In the event of a problem, the status will contain the error code, while the body of the response will usually contain additional information about the problem that was encountered. In general, if the status returned is in the `200` range, it indicates that the request was fulfilled successfully and that no error was encountered. Return codes in the `400` range typically indicate that there was an issue with the request that was sent. Among other things, this could mean that you did not authenticate correctly, that you are requesting an action that you do not have authorization for, that the resource you are requesting does not exist, or that your request was malformed or incorrect (such as missing required entity properties when trying to create an entity). If you receive a status in the `500` range, this generally indicates a server-side problem. This means that we are having an issue on our end and cannot fulfill your request. If you receive a `500` response, you should report it to [support@sadiebluesoftware.com](https://mailto:support@sadiebluesoftware.com) so we can investigate the issue. ## Error Response Examples Unauthroized Error Response Example: ``` HTTP/1.1 401 Unauthorized { "error": "invalid_request", "error_description": "The request requires authorization" } ``` --- Forbidden Error Response Example: ``` HTTP/1.1 403 Forbidden { "error": { "code": "InvalidWorkspaceException", "message": "Invalid Workspace", "target": "{{base_url}}/odata/workspace/tasks", "details": [ { "code": "Method", "message": "GET" }, { "code": "Timestamp", "message": "2017-09-09T19:30:33-05:00" } ] } } ``` # Routes The API provides two major routes depending on your needs: `workspace` and `master`. ## The Workspace Route The `workspace` route is the most common since it houses all of the resources that live within a specific workspace instance. Workspace instances are essentially separate databases that hold their own references to clients, matters, projects, and tasks. In order to access the workspace route, the account you are using must have proper access permissions to the specific workspace you're calling on. Organization administrator accounts have the ability to grant workspace access permissions to user accounts (typically done through Agility Blue using a browser). Once workspace access has been established, the API needs to know _which_ workspace resources you want. To do that, you will need to supply a special header named `X-Workspace-Id` using the workspace id as the value. Workspace ids can be located through the `master` route by querying the workspaces entity collection, or from Agility Blue by including the **id** column when viewing the list of workspaces you have access to when you log in. This header needs to be present for every request that uses the `workspace` route. If the header is missing, the API won't know what you want and will simply respond with an error. The `workspace` route implements the following uri schema where **{resource}** is a collection of entities. ``` {{base_url}}/odata/workspace/{resource} ``` ## The Master Route The `master` route resources do not require workspace-level access and thus do not need the `X-Workspace-Id` header. These resources are generally used for administration, such as managing users, single sign-on identity providers, or getting a list of workspaces you have access to. Please note that many of the `master` route resources require elevated permissions, generally the root or organization administrator roles, and as such, most of the scope is limited to the general user account role. The `master` route implements the following uri schema where **{resource}** is a collection of entities. ``` {{base_url}}/odata/master/{resource} ``` # Custom Fields Framework Some entities support defining custom fields by adding field definitions through the workspace objects resource allowing end users to add information to fields that are otherwise not part of the stock application. Custom fields are stored using the Entity-Attribute-Value paradigm (EAV), meaning that the fields are not actual columns added to the underlying database. Because the field values aren't stored on their respective database tables, it is necessary to tell the API that custom fields should be included in a response through the use of the odata `$expand` query parameter. Entities that support custom fields consists of a Fields navigation property that holds an array of object fields. Each object field provides schema information about the field and a Value navigation property that contains the field value. To retrieve custom fields with their values during a request, add the following query parameter: `$expand=Fields($expand=Value)`. Refer to specific endpoint sections for request examples. ``` json { // other object properties omitted for clarity "Fields": [ { "FieldId": 1, // unique field id "ObjectId": 1, // the object id the field is defined for "DataTypeId": 1, // the data type id that defines the storage type needed "DataTypeName": "Basic Text", "Label": "Custom Field 1", // displayed in the ui as the field name "IsRequired": true, // if a field is marked as required, validation will fail if a value is omitted or null "Position": 0, // the order the field is displayed on the ui "Guid": 1234567890, "IsSystemField": false, "DefaultValue": null, "CopyPreviousValueOnSave": false, "Value": { "ObjectFieldValueId": 1, "ObjectFieldId": 1, "ObjectId": 1, "PrimaryKeyId":, 1, // the foreign key id that this field value is attached to "ValueAsString": null, // value stored as text, "ValueAsBoolean": null, // value stored as true/false, "ValueAsNumber": null, // values stored as int32, "ValueAsDecimal": null, // value stored as decimal(17, 4), "ValueAsDate": null // value stored as datetimeoffset }, ... // other custom fields } ] } ``` ##### Object Field Entity Model | Property | Type | Required | Notes | | --- | --- | --- | --- | | FieldId | `Int32` | ✓ | `Primary Key` | | ObjectId | `Int32` | | `Read-Only` | | DataTypeId | `Int32` | | `Read-Only` | | DataTypeName | `String` | | `Read-Only` | | Label | `String` | | `Read-Only` | | IsRequired | `Boolean` | | `Read-Only` | | Position | `Int32` | | `Read-Only` | | Guid | `Int64` | | `Read-Only` | | IsSystemField | `Boolean` | | `Read-Only` | | DefaultValue | `String` | | `Read-Only` | | CopyPreviousValueOnSaveAndNew | `Boolean` | | `Read-Only` | ##### Object Field Navigation Properties | Property | Type | Required | Notes | | --- | --- | --- | --- | | Value | `ObjectFieldValue` | ✓ | | ##### Object Field Value Entity Model | Property | Type | Required | Notes | | --- | --- | --- | --- | | ObjectFieldValueId | `Int32` | ✓ | `Primary Key` `Read-Only` | | ObjectFieldId | `Int32` | | `Read-Only` | | ObjectId | `Int32` | | `Read-Only` | | PrimaryKeyId | `Int32` | | `Read-Only` | | ValueAsString | `String` | | | | ValueAsBoolean | `Boolean` | | | | ValueAsNumber | `Int32` | | | | ValueAsDecimal | `Decimal` | | | | ValueAsDate | `DateTimeOffset` | | | ## Field Cache Resources Entities that support custom fields also have a secondary resource available that allows retrieving collection data faster and more efficiently. Field cache resources are named `{entityName}FieldsCache` where the {entityName} token represents the singular form of the entity, such as "client", or "matter" (clientFieldsCache and matterFieldsCache respectively). The field cache resources contain all of the field properties that their source entity defines but also includes the custom fields on the top level of the object response in the format `CF_{customFieldId}` where the {customFieldId\] token represents the field id property on the object field entity model. Custom field ids can be discovered by querying the Objects resource with an expanded Fields property. Alternatively, field ids can be located within the application by editing the object and looking at the top left of an existing field. If the intent is to query a collection of data on an entity that defines custom fields, consider using the field cache resource, particularly if there is no need to include the full field definitions. ``` json { "value": [ { "MediaLogEntryId": 58, "MediaTypeId": 8, "MediaTypeName": "FTP", "From": "Delta Advisors", "To": "Jennie Scott", "Date": "2022-01-27T17:10:08.091Z", // other system properties omitted for clarity "Id": 58, // custom field foreign key - same as the entity id "CF_16": "2022-01-26T06:00:00Z", // custom field id 16 "CF_23": "In Storage", // custom field id 23 "CF_24": null, // custom field id 24 "CF_25": "Myself...", // custom field id 25 "CF_26": null, // custom field id 26 "CF_30": "n/a", // custom field id 30 "CF_31": null // custom field id 31 }, ... ] } ``` # Metadata Some entities allow you to provide custom properties in a dynamic property named `Metadata`. Metadata properties are special data types that let you define mixed data types on a specific instance of an entity. This allows you to programmatically attach structured bits of information to specific entities unique to a variety of scenarios where you may not otherwise be able to put within the predefined properties of the entity. For example, the Agility Blue notification manager places email header information (to, from, cc, message-id) into task and task comment metadata fields when emails are sent into the system. Custom metadata properties should be thought of as "light-weight" and cannot contain arrays or objects (strings, booleans, numbers, and dates only). The app will display metadata information to the end-user when metadata is present on an entity. ## Filtering Metadata Metadata can be filtered on collection endpoints where metadata properties exist for an entity. Because of the dynamic nature of metadata, they cannot be queried using the general OData query parameters and instead utilize a special query parameter named `metadata`. Metadata property names are case-sensitive (the left side), however, filtering for values (the right side) are not. _For the examples in the table below, assume that there are metadata properties named_ `_Source_` _(string) and_ `_Size_` _(number) that exist on some entities._ | Filter Operator | Description | Query Example | | --- | --- | --- | | `exists` | Filter for the existence of metadata. | `metadata=exists` | | `not exists` | Filter for the absence of metadata. | `metadata=not exists` | | `eq` | Filter for a specific metadata property to equal a value. | `metadata=Source eq 'Email'` | | `ne` | Filter for a specific metadata property to not equal a value. | `metadata=Source ne 'Email'` | | `con` | Filter for a specific metadata property to contain a value. | `metadata=Source con 'Email'` | | `ncon` | Filter for a specific metadata property to not contain a value. | `metadata=Source ncon 'Email'` | | `le` | Filter for a specific metadata property to be less than or equal to a value. | `metadata=Size le 100` | | `ge` | Filter for a specific metadata property to be greater than or equal to a value. | `metadata=Size ge 100` | | `lt` | Filter for a specific metadata property to be less than a value. | `metadata=Size lt 100` | | `gt` | Filter for a specific metadata property to be greater than a value. | `metadata=Size gt 100` | _It's important to note that if you combine metadata filtering with OData_ `_$filter_` _filters, metadata filters are executed first._ The property names for metadata are case-sensitive and may contain special characters, such as spaces or dashes. If you add properties that contain special characters, you need to surround the property name with single quotes when attempting to filter for those properties and an additional set of double-quotes when handling spaces. Example with no special characters in the metadata property name: ``` metadata=MessageId con 'abc123' ``` Example with hyphens in the metadata property name: ``` metadata='Message-Id' con 'abc123' ``` Example with spaces in the metadata property name: ``` metadata='"Message Id"' con 'abc123' ``` _Some special characters are reserved and not allowed as property names, such as the single quote character_ `_'_`_**._ _Concatenating/combining metadata filters or sorting by specific metadata properties are not available at this time._ # Entity Resource Reference Entity-specific resource references are documented from here on out. The panel on the right (or below each reference if viewing on a smaller device) includes examples of how to make requests that can be configured to provide "stubs" in a variety of languages at the top. The example requests and responses will be aligned with the resource to the left. Below the example requests are example responses from the API so you can get an idea of what information is returned based on the request. Be sure to fill in the information specific to you when making your own calls, particularly when you see the tokens `{yourApiKey}`, `{yourWorkspaceId}`, and `{entityId}`.