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.
Can the API be used to insert e-mails into Ungerboeck?
1 upvotes
Lee,
Thanks for your question. At this time the API does not have an e-mail endpoint.
Can you comment more on your use case?
Thanks,
Craig
0 upvotes
We wanted to build an app to allow drag and drop of files into Ungerboeck. It would have been awesome if we could have used the app to drag and drop emails from outlook too (essentially replacing the outlook add-in).
Thanks
0 upvotes
Lee - did you successfully build a drag and drop application to add files into ungerboeck?
0 upvotes
We have started a proof of concept but don't currently have budget for it so it's taken a bit of a back seat. I will see if we can bump it back up the priority list a little.
Would you be prepared to share your requirements so we can see if they align with ours and how quickly we may be able to get something to you to play around with?
L
0 upvotes
I was just intrigued by your idea, if you do complete it would be curious to see a demo.
0 upvotes
Guys,
i just stumpled upon this thread, and i might have a prototype for u. We had a students groupd realizing a interface between alfresco and ungerboeck. I believe this is the way to go, as alfresco brings dms features ungerboeck has still a long way to guy. unfortunately for our needs, alfresco would be cool, but is too large for our needs - but maybe someone else could take this up?
any alfresco experts around?
cheers, Oliver from Vienna
1 upvotes
Hello,
We use API tools like postman and httpmaster to test your API calls but getting 401 response code. With the same user/pass and request, your sandbox returns successfully with 200 code. See below (data omitted with *).
using postman:
curl -X GET --header 'Accept: application/json' --header 'Authorization: Basic *******************************' 'https://****.ungerboeck.com/prod/api/v1/Events/**?search=All'
401 {"Message":"Authorization has been denied for this request."}
using https://****.ungerboeck.com/prod/api/help/index :
curl -X GET --header 'Accept: application/json' --header 'Authorization: Basic *******************************' 'https://****.ungerboeck.com/prod/api/v1/Events/**?search=All'
200 and data
Do we miss something here? Do we need a special user or API module?
Any help or direction is appreciated, thanks!
William
0 upvotes
Hi William,
To use the API, you perform two steps:
1. Initialize to get a token
2. Use that token to do additional calls.
The sandbox somewhat abstracts this since the first step is done in the top right of the page, but the 'Try It Now' calls includes a token with the calls (The curl commands were made more straightforward in 20.95).
Include the initialization token in on the Events search and you should get a 200 response.
Read more about it here:
https://supportcenter.ungerboeck.com/hc/en-us/articles/115010462527-Getting-Started-with-the-API
0 upvotes