API Overview

The Ungerboeck REST API (Ungerboeck API) provides you with a secure, powerful, and simple web services API for interacting with your Ungerboeck database. You can use it to power various integrations with Ungerboeck to make your business processes more efficient and connected.

Requirements

• Access to programming language that can make HTTP calls (.NET, PHP, Python, JavaScript, etc...). If using .NET, you can use the Ungerboeck SDK.
• v20/v30 user specifically set up for API use. You receive 1 API user with the purchase of the API module.
• Ungerboeck API module purchased through your Account Manager.

Security & Authentication

The Ungerboeck API is bundled within each v20/v30 installation.

The Ungerboeck API communicates using the HTTPS protocol. Any requests coming from HTTP are not serviced.

You authenticate using credentials from a v20/v30 user and password using Basic Authentication. You are then returned a bearer token to make all subsequent API requests. 

Data Limits / Data Rates

There are no data, request, or size limits using the Ungerboeck API. 

With great power comes great responsibility. We do want you to exercise caution in your requests to the API. If you request 100,000 accounts through the API, the performance may not be what you want. We have provided a paging mechanism which can help with the larger datasets, which is discussed in detail in the Searching the API article. Also, keep in mind, you are hitting a production v20/v30 server, so you can affect its performance with sub-optimal requests.

Request Format

The Ungerboeck API is a JSON API. You must supply a "Content-Type: application/json" header in PUT and POST requests. You must set an "Accept: application/json" header on all requests. You may get a text/plain response in case of an error like a bad request. You should treat this as an error you need to fix.

Response Format

The Ungerboeck API responds to successful requests with HTTP status codes in the 200 or 300 range. When you create or update a resource, the API renders the resulting JSON representation in the response body.

Data Types

The API returns and accepts JSON values, which can be strings in double quotes, numbers, objects, arrays, true or false, or null. Most programming languages have tools to parse this data.

Time Stamps

Time stamps are formatted as ISO 8601 strings. Example: 2015-04-16T09:14:57.

Searching

Most of the endpoints give you searching capabilities. Using those, you can refine your search against various properties of the subject to get only those records you want using OData notation. Also, a powerful paging engine allows you to specify your page size. As part of the search process, we also cache the search results for quick navigation through the pages of results. More specifics regarding searching including OData and pagination are detailed in the Searching Using the API article.   

Status Codes and Error Handling

The status code provided in the response object from the API gives insight on what happened in the API process. They follow the standard status code usage found in most RESTful services. Listed below are the various statuses you can see.

• OK (200) - The operation completed successfully.
• Request Failed (400) - Information submitted to the API is invalid or otherwise unable to compute. Look at the ReasonPhrase property on the response object to see specifically what is wrong.
• Unauthorized (401) - This occurs if the API user’s credentials are invalid, or if the information submitted to the Initialization is otherwise incorrect. This can occur in the initialization, or in the normal API process if the token is invalid or expired. The ReasonPhrase property on the response object often reveals what is wrong. Otherwise, ensure your credentials are working and try to reinitialize.
• Not Found (404) - This occurs if the resource cannot be located, whether if the item doesn’t exist, or if the URL is invalid. The ReasonPhrase property on the response object often reveals what went wrong. Otherwise, double check your URL and ensure the item exists.
• Method Not Allowed (405) - The requested URL does not allow the verb in the http call. For example, this would occur if PUT was used on the “…/api/Accounts” url, since that URL is only used for GET requests. Check the verb and URL and try again.
• Internal Server Error (500) - An exception happened on the Ungerboeck server. This indicates that it is not your fault and that you should try again. Ungerboeck uses logging alerts to detect these and, if it happens, there is someone notified and looking what caused it and how to ensure it does not happen again.