Unity API Toolkit

Welcome to Unity’s API Toolkit! You’ll find important information and links about our API to help you and your team get the most out of Unity. 

Have questions or need help? Please contact [email protected] for assistance.

Introduction

Purpose of the API Toolkit

At a high level, the Unity API allows the customer to request approved invoices from Unity and Unity API provides that data back. The customer then updates the invoice status to “Sent to AP” in Unity. Once the invoice is paid, the Customer updates invoice status to “Paid” and provides payment details (optional) in Unity.

On a technical level, the Unity API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website’s client-side code). JSON is returned by all API responses, including errors.

Our formal documentation at developer.simplelegal.com uses PATCH methods throughout, however, POST can be used instead of PATCH to accommodate systems that can’t utilize the PATCH method.

How to use the API Toolkit

Step 1 / Customer

Send your IT team or IT consultant the link to our API development page. This provides all the details of building an API to Unity.

Step 2 / Customer

Confirm which business process/workflow steps will be needed for your integration, for example for finance integration:

• Required: Retrieve Invoices to be paid
• Optional: Retrieve Unity PDF copy
• Optional: ACK/Payment confirmation
  • Record payment information
  • Update invoice status to Paid

Step 3 / Customer

Reach out to your Finance team to understand accounting and data requirements to post invoices into your finance system and pay an invoice.

Step 4 / Customer & Unity

Discuss attributes/data that needs to be in Unity for payment (see FAQ below: “What are the most common attributes and their definition?”)

Step 5 / Unity

Configure Unity with required attributes

Step 6 / Unity

Provide customer with Unity base URL and API Authorization token. Will be in the following format:

• API base URL: https://<>.simplelegal.com
  • e.g. http://app.simplelegal.com or http://abccompany.simplelegal.com
• API Authorization Token: <auth_token>

Step 7 / Customer

Test connection to Unity API

Step 8 / Customer

Build necessary integration calls and configuration based on integration needs

Step 9 / Customer & Unity

Test your connection by calling an endpoint and make sure you were able to retrieve data, and the relevant information is generated. For example, for finance integration, you should approve an invoice in Unity and make sure it can be retrieved, with the necessary information sent back to Unity.

Getting Started

The Unity API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website’s client-side code). JSON is returned by all API responses, including errors. We’ve documented PATCH methods throughout, however, POST can be used instead of PATCH to accommodate systems that can’t utilize the PATCH method.

Prerequisites

• Determine API user details (first name, last name, email)
  • Typically, the API user has a generic name (e.g. first name: Oracle Integration, last name: Finance Integration, email: [email protected])
• Provide API user details to Unity
• Unity to generate API key
• Unity to provide Unity API toolkit & API developer
• Schedule and conduct API requirements and mapping (Client and Unity)
• Schedule and conduct API development (Client)
• Testing (Client and Unity)

Authentication

API authentication is a combination of technology and process that proves or verifies the identities of users who want access to an API. Specifically, API authentication involves the use of a software protocol to verify that users are who they claim to be when a client makes an API call.

Sandbox vs Production

Our sandbox APIs emulate the live environment and give you the opportunity to send test API calls and to receive a simulated response. Sandbox APIs are perfect for working with the client before the production API is available, allowing front-end progress to continue, even though there’s no real data or database backing it yet. The production APIs work with our live systems and data. Your application will run in this environment after you go live.

The Multi-tenant Sandbox data is refreshed monthly on the third Friday of the month. Your team can create or update data in the sandbox, and any alterations made will be reset and replaced with the data from the production environment during the monthly refresh.

API Basics

Understanding RESTful APIs

The basic function of a RESTful API is the same as browsing the internet. The client contacts the server by using the API when it requires a resource. API developers explain how the client should use the REST API in the server application API documentation. These are the general steps for any REST API call:

• The client sends a request to the server. The client follows the API documentation to format the request in a way that the server understands.
• The server authenticates the client and confirms that the client has the right to make that request.
• The server receives the request and processes it internally.
• The server returns a response to the client. The response contains information that tells the client whether the request was successful. The response also includes any information that the client requested.

The REST API request and response details vary slightly depending on how the API developers design the API.

HTTP Methods (GET, POST, PATCH)

The HTTP verbs comprise a major portion of our “uniform interface” constraint and provide us the action counterpart to the noun-based resource. The primary or most-commonly-used HTTP verbs (or methods, as they are properly called) are POST, GET, PUT, PATCH, and DELETE. These correspond to create, read, update, and delete (or CRUD) operations, respectively. There are a number of other verbs, too, but are utilized less frequently. Of those less-frequent methods, OPTIONS and HEAD are used more often than others.

Below is a table of recommended return values of the primary HTTP methods in combination with the resource URIs

Call / Type	Entire Collection	Specific Item
POST / Create	201 (Created), ‘Location’ header with link to /customers/{id} containing new ID.	404 (Not Found), 409 (Conflict) if resource already exists.
GET / Read	200 (OK), list of customers. Use pagination, sorting and filtering to navigate big lists.
PUT / Update/Replace	405 (Method Not Allowed), unless you want to update/replace every resource in the entire collection.	200 (OK) or 204 (No Content). 404 (Not Found), if ID not found or invalid.
PATCH / Update/Modify	405 (Method Not Allowed), unless you want to modify the collection itself.	200 (OK) or 204 (No Content). 404 (Not Found), if ID not found or invalid.
Delete / Delete	405 (Method Not Allowed), unless you want to delete the whole collection—not often desirable.	200 (OK). 404 (Not Found), if ID not found or invalid.

API Endpoints

In summary, an API endpoint is a specific location within an API that accepts requests and sends back responses. It’s a way for different systems and applications to communicate with each other, by sending and receiving information and instructions via the endpoint.

Response Formats (JSON, XML)

JSON supports numbers, objects, strings, and Boolean arrays. XML supports all JSON data types and additional types like Boolean, dates, images, and namespaces. JSON has smaller file sizes and faster data transmission. XML tag structure is more complex to write and read and results in bulky files.

JavaScript Object Notation (JSON) is a standard text-based format for representing structured data based on JavaScript object syntax. It is commonly used for transmitting data in web applications (e.g., sending some data from the server to the client, so it can be displayed on a web page, or vice versa)

An XML response message is sent by the SDS XML provisioning client in response to an XML request. Each response message consists of a 4-byte binary length value, followed by the XML response in ASCII characters. The length value contains the number of bytes in the XML response, excluding the 4-bytes for the length.

API Calls

An API call allows one application to request data or services from another application. Our API developer page is a comprehensive API document, containing all available API calls, their respective arguments, filters, and examples.

Request Parameters

API request parameters are options that can be passed with the endpoint to influence the response. Refer to request parameters located in the API developer page.

Response Structure

When you send a REST request, the appliance responds with a structured response in JSON format. The exact structure of the response depends on the resource and URI of the request, but all responses are similar. The response includes all available resources from any point within the API.

Common Workflows

API workflows are server-side workflows that you can schedule/trigger in your application and/or expose to be triggered from an external application or system through an API request.

Below are the most commonly requested calls for typical integration scenarios:

Finance Integration (Unity <> AP System)

Step 1: Retrieve all approved invoices

The first step is to fetch all approved invoices. This can be achieved with the invoices end point, filtering on Approved status. Refer to “What are the valid invoice statuses in Unity?” in the Q&A section for other supported statues.

View API Documenter for GET List All Invoices details.

Optional – Retrieve Unity PDF copy

If necessary to your integration, pull the PDF copy of the invoice (either summary or the full pdf). Retrieving the PDF is done on a per invoice basis, so a valid Invoice ID is required. Please note the PDF is base64 encoded so would require a decoder to view.

View API Documenter for GET Retrieve an Invoice Detail PDF and GET Retrieve an Invoice Summary PDF details.

Optional – Retrieve additional details

If necessary to your integration, pull additional details from the matter, vendor, or accounting fields:

• GET Retrieve a matter
• GET Retrieve a vendor
• GET Retrieve an entity
• GET Retrieve a cost code
• GET Retrieve a custom attribute

Step 2: Update invoice status

After retrieving the invoices, best practice is to record the invoice id, and update all invoices that are to be processed to Sent to AP status. This way, application users, and vendors will see that invoices have been submitted for payment. Optionally, you can use Posted to AP – the flow is dependent on your organizational needs.

View API Documenter for PATCH Update an Invoice details.

Optional – Record acknowledgement of successful invoice posting

After successful posting of invoices, best practice is to record the invoice id, and update all invoices that are to be processed to Posted to AP status. This way users will see that invoices have been successfully posted without error. 

View API Documenter for PATCH Update an Invoice details.

Optional – Record Payment Details

Once payments are made to Vendors, two separate calls will be made for each invoice:

1. Record payment information for an invoice.

Create a Payment record on the individual Invoice endpoint. The required fields are payment_method (which can be defined by your organization; example: check, wire, ach, etc.), amount, currency, and payment date in YYYY-MM- DD format.

View API Documenter for POST Create Payment for an Invoice details.

2. Update Invoice Status

After paying / submitting payment for invoices, you should update the invoice status to Paid. This way, application users, and vendors will see that invoices have been marked Paid.

View API Documenter for PATCH Update an Invoice details.

Matter Integration (Unity <> Matter Management System)

Step 1: List All Matters

The first step is to fetch a list of all matters. The matters are returned sorted by matter name alphabetically. Available modifiers can be added onto the end of a search string joined by a double dash and are generally shorthands for more advanced searches that can be done:

• lt -> less than
• lte -> less than equal to
• gt -> greater than
• gt -> greater than equal to
• icontains -> contains, case insensitive

View API Documenter for GET List All Matters details.

Step 2: Create New Matters

First, compare the list of new matters against the existing list of matters from Step 1 to ensure no duplicate matters are created. For additional confirmation, you may pull the Client Matter ID associated with the matter for your records.

Second, create any new matters in Unity. Three fields are required for creating a new matter:

• name
• matter_lead_email
• matter_lead_is_approver

The following optional fields are also recommended when creating a new matter:

• description
• status
• matter_group
• open_date (if differing from the creation date)

View API Documenter for POST Create a Matter details.

Other Common Data Requests

Retrieve All Legal Entities

The entities are returned sorted by entity name alphabetically.

View API Documenter for GET List All Entities details.

Create New Legal Entities

One field is required for creating a new legal entity:

• name

The following optional fields are also recommended when creating a new legal entity:

• description
• accounting_code

View API Documenter for  POST Create an Entity details.

Retrieve All Cost Codes

The cost codes are returned sorted by entity name alphabetically.

View API Documenter for GET List All Cost Codes details.

Create New Cost Codes

One field is required for creating a new cost code:

• name

The following optional fields are also recommended when creating a new cost code:

• description
• accounting_code

View API Documenter for POST Create a Cost Code details.

List All Custom Attributes

The attributes are returned sorted by attribute name alphabetically. Attributes can only be filtered based on the ‘name’ field.

View API Documenter for GET List All Attributes details.

List All Custom Attribute List Values

Returns the list values for a specific custom attribute. The custom attribute id (e.g. attr_1234567890) is required to pull. The options are returned sorted by name alphabetically.

View API Documenter for GET Retrieve an Option for <list> Attribute details.

Create New Custom Attribute List Values

Creates a new list value for a custom attribute. The custom attribute id (e.g. attr_1234567890) is required to create.

The following fields are required for creating a new custom attribute list value:

• name
• description
• accounting_code

View API Documenter for POST Create an Option for <list> Attribute details.

Update Existing Custom Attribute List Values

Updates an existing list value for a custom attribute. The custom attribute id (e.g. attr_1234567890) and the list value id (e.g. attr_opt_1234567890) is required to update.

The following optional fields are available to be updated:

• name
• description
• accounting_code

View API Documenter for PATCH Update an Option for <list> Attribute details.

Retrieve Users

The users are returned sorted by created_date, with the most recently created user first.

View API Documenter for GET Retrieve All Users details.

Retrieve Audit Logs

The logs are returned sorted by created_date, with the most recently created log first.

Supported categories are:

• added, edited, deleted, uploaded, downloaded, viewed, sent, escalated, exporte, updated, renamed, adjusted, approved, unapproved, rejected, unrejected, ‘requested changes on’, ‘resolved changes on’, paid, assigned, received, merged, split, activated, deactivated

Available modifiers can be added onto the end of a search string joined by a double dash and are generally shorthands for more advanced searches that can be done:

• lt -> less than
• lte -> less than equal to
• gt -> greater than
• gt -> greater than equal to
• icontains -> contains, case insensitive
• range -> two dates, everything between the dates matches (inclusive for the first, exclusive for second)

View API Documenter for GET Retrieve all logs details.

Retrieve Accruals for a Period

For a given period, retrieve all submitted accruals. The “period” argument is required to pull and must be in the YYYY-MM-DD format.

If a range of dates period can be specified with the range operator. For example, if only the accruals in the first three months are desired, the filter ?period__range=2018-01-31,2018-03-31 would display all relevant accruals. (Note that range is inclusive on both the beginning and the ending date)

View API Documenter for GET Retrieve Accruals for a Period details.

Common API Errors

Missing API key/token or Require new API key/token

1. Contact your implementation manager or our Unity support team ([email protected]) to identify if you have an API user already configured and which environment the key is needed for (production or sandbox).
2. Unity will either confirm a key exists or create a new key to send the key via personal email to a designated drop location.

What is the id/hash for this object?

1. The id or hash for an object will be dependent on what call(s) your team is making. First, determine the call(s) and end points within the API Documenter.
2. To obtain the id/hash for an object (e.g. a matter), retrieve all matters and locate the “id” key associated with that object. The hash follows a consistent format, where the first 3-4 characters represent the type of object (e.g., “mat” for matter), followed by an underscore (_) and the numerical ID. For instance, a matter hash could be represented as “mat_1234567890.”

API Call is Returning an Error

1. Contact our Support Team ([email protected]) or your Implementation Manager (if you are still in Implementation). Provide the full call and response you are attempting.
2. Our team will confirm if the object being called exists, and whether or not the API user has permission to see it.
3. If GET, Unity can test the call to determine if we get the same error.
4. If POST, Unity may test the call parameters in a demo environment.

API Call Returns No Results

1. Log into Unity and verify that there is at least one object for the call (e.g. matters, vendors, etc) and verify the parameters of the call are applicable to the data within Unity.
2. If the objects exist, this implies the API user has access to the database via API but does not have sufficient privileges to retrieve the data
3. Customers can reach out to the implementation manager or Unity Support ([email protected]) team to verify which email address is associated with their API token.
4. Unity will validate the user has a role which is sufficient in accessing the objects in question. API users should have a user role = “Administrative Role”.

Error Handling

In any integration process, encountering errors is a common scenario. Effective error handling is crucial to maintain the integrity and efficiency of the integration between Unity API and your corporate ERP system. Here are some best practices for monitoring and maintaining your system and errors that may arise:

Real Time Monitoring: Set up real-time monitoring and alerts for your API integration. This will enable immediate detection of errors as they occur.
Utilize logging systems to record detailed error information, which can be invaluable for troubleshooting.

Designated Response Team: Identify a designated response team within your organization. This team should include members who are well-versed in both the Unity API and your ERP system.

Notification Procedures: Establish a clear procedure for notifying the designated response team when an error is detected. This can be automated through your monitoring systems or manually initiated by the team monitoring the integration.

Root Cause Analysis: Once the immediate issue is resolved, conduct a thorough root cause analysis to understand why the error occurred. This step is crucial to prevent similar issues in the future. Document the findings and update your integration processes and error-handling protocols accordingly.

Continuous Improvement: Treat every error as a learning opportunity to improve your integration setup. Regularly review your error-handling procedures and update them as needed. Encourage open communication and feedback within the team regarding the handling of integration errors. This collaborative approach can lead to more resilient and reliable integration.

General Unity API Features and Q&A

What features can the Unity API support for each team or process?

Finance	Legal Ops	Reporting
Paying invoicesUpdating invoice payment status on Unity. Pulling a specific invoices by created date, invoice date, modified date, or statusCreating and updating cost codes	Creating and updating mattersCreating and updating most vendor dataCreating and updating custom attributesCreating and updating legal entitiesCreating, updating, and deactivating users including setting roles	Access matters, invoices, vendors by created date, modified date, closed datesSearch and filter via statusesEasily pull all custom attributes associated with matters, vendors, invoices

What features are not supported by the Unity API?

• Access to timekeepers data
• Access to budgets data
• Cannot access contacts or vendor contacts / CounselGO users
• Cannot set permissions/teams via API
• Cannot set invoice intake rules or approver escalation rules via API

What are the most common invoice attributes and their definitions?

While this varies per customer, below are some common attributes used to retrieve invoice details and pay an invoice:

Field Name	Definition
Invoice_date	Invoice Date on the header (defined by the vendor)
Received_date	Date invoice was received into the Unity system
Invoice_number	The number or name as listed on the invoice, the main invoice identifier
Entity.id	Ent_123; unique identifier for legal entity
Cost_code.id	Cos_12345; unique identifier for the cost code
Custom_attributes.id	Attr_opt_12345; unique identifier for custom attribute
Native_currency	The currency the invoice was submitted in. (If null, the submitted currency is your base currency)
Native_total	The amount the vendor billed (as well as final amount as adjustments cannot be made on international currencies) on the invoice in the submitted currency.
Total	The amount the vendor billed on the invoice in the base currency of your environment.
Final_amount	Final amount of the invoice (after any adjustments) in the system/base currency.
Status	E.g. “Approved”, ”Paid”
id	Unity invoice reference number (e.g. inv_1234567890)
obj_id	On the invoice end point, this is the unique invoice id of the specific invoice, and is visible on the PDF and approver email

 Can PDF attachments come through the API

Yes. You can retrieve invoice attachments through Retrieve an Invoice. You can also pull the Unity generated PDF through either Retrieve an Invoice Detail PDF or Retrieve an Invoice Summary PDF.

View API Documenter for GET Retrieve an Invoice Detail PDF and GET Retrieve an Invoice Summary PDF details.

How do we know which invoices to pull from Unity to our finance system?

In a standard finance API integration, you will want to pull any invoiced in an “Approved” status. These are invoices that have been approved in Unity by all approvers and are ready for payment. As part of the API integration, you will want to update the status of the imported invoices to “Sent to AP” using PATCH. If the patch function isn’t available, you can also update the status using POST.

Is there anything else we can do with the API besides retrieve and update invoice information?

Yes. Through the API, you can access most components of Unity including matters, vendors, cost codes and legal entities. You can streamline your vendor intake process by pushing new vendors from your financial system into Unity. You can integrate with your patent software to push new patent & trademark matters into Unity. You can even use the API to update cost codes and legal entities.

Can you provide examples of how other partners have handled their integrations or technical references if we need additional help?            

Our Implementation team can offer guidance if you have specific questions on how to get started, but unfortunately, we do not share client data or integration specifics.

What are the valid invoice statuses in Unity?

• Received
• Rejected
• Approved
• Paid
• Sent to AP
• Posted to AP
• On Hold

How can I see an export of all the sample JSon? 

You can download Postman and pull the full JSON export.

 For the ‘Update an Invoice’ API the documentation states either a PATCH or POST could be used. Is this also true for the ‘Create Payment for an Invoice’ or must a POST be used?

Payment information can only be posted right now, it cannot be patched. We treat it as a log so you can only add to it.

How long would it take our team to integrate with the Unity API and how will Unity help? 

This depends largely on the degree of integration in terms of what is required by the finance team, and the resources available on your development team to build it out. Unity can provide guidance in terms of understanding the documentation and in terms of what has been successful in the past. 

What is the difference between the Reference Number and Batch Number in the ‘Create a Payment for Invoice’ API? 

The reference number is unique per payment, whereas a batch number is used to group payments.

What is the difference between invoice_number and id and which should we use? 

The id is a unique number that Unity assigns to each invoice and should serve as its unique identifier. Invoice_number is the number associated on the invoice itself, but this is not always.

Can you accommodate custom object IDs in the API? 
Currently we cannot support customization in the object IDs. However, depending on business needs, we may have recommendations for different ways to proceed to achieve the same result. We also support custom attributes with our platform, which may aid in capturing the information you require. Reach out to your implementation manager for guidance. 

How do you recommend we update matters or vendors most efficiently?

For example, if your matter has 15 attributes and all attributes on a single matter need to be updated, that would be 15 calls. One method of reducing the number of calls is to check if the attribute values have changed. So instead of updating every single attribute value regardless if there was a change or not, you’ll want to validate if a change was made to the attribute value. Specifically, here is a step by step process recommendation:

1. Obtain the id of the vendor/and or matter you wish to update
2. Navigate to the attribute URL associated with that vendor/matter
3. Check what attribute values are associated, ideally with the `page_size` value set equal to the `count` value
4. Before deciding to update, compare the new value against the one seen on the page If different, then PUT, otherwise don’t PUT

Please note we do not recommend ‘page_size’ values over 100 as it may cause a timeout. 

How are foreign (non-USD) invoice adjustments handled in the API?

Unity currently does not allow adjustments on foreign invoices because it has tax implications for vendors in most countries. Since foreign vendors are required to submit tax data to their respective governments, any adjustments made to invoices would result in a mismatch in reporting numbers vs actual numbers for your vendors. Instead we require that foreign invoices requiring adjustment be rejected with comments so that vendors can re-submit with the required corrections.

How do you get the final invoice amount? 
There are three options to get the final amount depending on the currency used to bill.

Is there a limit on any of the APIs for how many results are fetched?

By default the maximum number of items on a paginated list page is 25. This can be configured by post fixing a URL with ?page_size=100 if a page size of 100 is desired but it may timeout depending on the endpoint you hit and how much data comes through.

Can a customer create a matter and assign matter attributes in a single API call, or is it necessary to create the matter first and then update the attributes separately?

The API does not support creating and assigning matter attributes in a single call. To accomplish this, you will need to make multiple API calls. First, create the matter, and then make separate API calls for each attribute update.

Additional Resources

Unity Support is here to assist with your team’s product questions. Contact our Support team ([email protected]) when you have technical questions, would like assistance with functionality, or answering ‘how,’ ‘what,’ or ‘where,’ within your products.