The Momentus REST API (Momentus API) provides you with a secure, powerful, and simple web services API for interacting with your database. You can use it to power various integrations with Momentus 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 Momentus SDK.
- v30 user specifically set up for API use. Create an API User in the API User screen. This serves as your service account.
- Momentus API module purchased from your Account Manager.
Security & Authentication
The Momentus API is bundled within each v30 installation.
The 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 Momentus SDK, but any standard JWT library can do this.
Data Limits and Data Rates
There are no data, request, or size limits using the API. However, Momentus asks that you not abuse your API with too many requests as this results in poor performance for both you and other Momentus 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.
Momentus 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.
Request Format
The Momentus 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.
Response Format
The Momentus 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.
Data Types
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
Time stamps are formatted as ISO 8601 strings. Example: 2015-04-16T09:14:57.
Searching
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 Momentus 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 Support Services team.
Comments
20 comments
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
1 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
Hi,
I tried to make an api test call, but got below error, could you please help?
0 upvotes
Hi Qi,
This happens when the token used to do API calls gets out of date between versions or corrupted somehow. Reload the page, authenticate again in the top right, then try another call. If it still doesn't work, there's a deeper problem in your system and a ticket would be in order.
Thanks,
Rudy
0 upvotes
I believe there have been some changes recently around authentication and how to setup API users.
Is there an article with the latest details/instructions please?
0 upvotes
On a separate note... I am trying for the first time to use JWT authentication using the /api/help link. Authorization is successful, but hitting basic endpoints (like get accounts with a vague search like Class eq 'O' returns an empty array. Any ideas?
0 upvotes
There will be updates and/or new articles in the next 1-2 weeks regarding authentication changes.
0 upvotes
Last, but not least- are USI aware of a bug with authentication on /api/help often incorrectly reporting success?
Looking at the network I can see the API returns my username instead of a token- it's getting confused somewhere?
0 upvotes
Hey Lee,
That's the first I heard of this. If you can recreate it, can you send it in as a support ticket? I'd love to take a look.
Edit: The new articles are up! Take a look:
https://supportcenter.ungerboeck.com/hc/en-us/articles/4417892599063-JWT-Authentication-and-the-Refreshed-SDK-Overview
0 upvotes
Rudy Scoggins sorry for the delay- i'm not sure if you were referring to the JWT issue or the other...
We have finally got round to raising the JWT issue via one of our clients MCCC and will possibly also raise via ETC shortly too.
0 upvotes
Thanks Lee!
0 upvotes
We've been trying to set the Heading of Documents imported via the API but have been unsucessful.
The documents are imported just fine, but no heading is assigned.
I even tried to update the heading via PUT with the following values
"SecondaryHeading": 0,
0 upvotes
Hi Elisabeth,
All Document Heading fields are Read Only.
This is intentional as they are the Document Heading design isn't a great fit for API use since there's no way to edit or delete headers in Ungerboeck.
0 upvotes
Please sign in to leave a comment.