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.
- v30 user specifically set up for API use. Create an API User in the API User screen. This serves as your service account.
- Ungerboeck API module purchased from your Ungerboeck Account Manager.
Security & Authentication
The Ungerboeck API is bundled within each v30 installation.
The Ungerboeck API communicates using the HTTPS protocol. Any requests coming from HTTP are not serviced.
You use an API user to generate a JWT to use as a bearer token. The easiest way is to use the Ungerboeck SDK, but any standard JWT library can do this.
Data Limits and Data Rates
There are no data, request, or size limits using the Ungerboeck API. However, Ungerboeck asks that you not abuse your API with too many requests as this results in poor performance for both you and other Ungerboeck users if you are in the Cloud. What qualifies as abuse? Actual numbers depends on factors such as call frequency within a process, response quantity, response model size and how often a process happens so it is determined on a case-by-case basis. For example, if you request 100,000 accounts through the API, that's a large quantity and the default Accounts model is large, so you can expect slow performance. Another example is if you request 10,000 events every second for days at a time. That is a large quantity in a very frequent hit on the server, resulting in a hard churn. This also might result in a negative effect.
Ungerboeck does provide provide a paging mechanism which can help with the larger datasets, which is discussed in detail in Searching the API.
If you are concerned that your call volume is too much, you can review it with our Client Care Team. Generally, a too high call volume is rare in normal API use and usually happens when accidental loops or misuse occurs.
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 resolve.
The Ungerboeck API responds to successful requests with HTTP status code 200. When you create or update a resource, the API renders the resulting JSON representation in the response body.
The API returns and accepts JSON values, which are strings in double quotes, numbers, objects, arrays, true or false, or null. Most programming languages have tools to parse this data.
Time stamps are formatted as ISO 8601 strings. Example: 2015-04-16T09:14:57.
Most of the endpoints provide 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 Searching Using the API.
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 is not 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 the error is not your fault. You can try again to see if it was a temporary issue, or try modifying your data. If the error persists, submit a ticket with the Ungerboeck Client Care Team.