Make Your First API Call

If using a .NET language, it is recommended to use the Momentus Enterprise SDK. Momentus provides you with the package Ungerboeck.Api.Sdk on NuGet, which is a complete API client with pre-made API calls, options and models with pre-made properties that represent the various subjects in the software. You can include it as a reference in your project and take advantage of the objects.  Essentially, most of the API coding work is done for you.

There are many benefits to using the SDK, including:

• Less coding for you.
• When you upgrade software versions and the SDK, the SDK also gets new models and wrapper functions with the new SDK version.
• Token management. Set how the JWT is generated and the client maintains it from there.
• Easy options to control validations and searching in API calls.

Install the SDK

You can find the SDK on the NuGet. If you only want the collection of subject models and properties, that is available as well, though the SDK is the full package to start a project. You can install either of these directly into your .NET project using the Visual Studio Package Manager or NuGet commands.

Make sure the second value in the SDK package version matches your software version. Momentus always recommends the latest package version within your software version. See below for an example match. 

Example Project

You can also find an example project on GitHub. This shows you all the various ways to use the API via code. Select your software version to find the correct project and get started with looking through examples!

The code with and without wrappers is shown below.

Make Your First Call 

To use the API, you need to first generate a JWT using your API User information. See API Users for details on creating API users. After you create an API user, you need the API User ID, secret and a key from its list of API User Keys.

To get that token, you generate locally using JWT libraries.

With the SDK

Retrieve a Token

Below is an example call to retrieve the token and a sample response.

var auth = GetApiClientAuth();
var apiClient = new Ungerboeck.Api.Sdk.ApiClient(auth);

private static void GetApiClientInfoAuth()
{
  return new Ungerboeck.Api.Models.Authorization.Jwt()
  {
    APIUserID = “MYUSERID”
    Key = “GET-THIS-GUID-FROM-API-USERS-WINDOW”
    Secret = “GET-THIS-GUID-FROM-API-USERS-WINDOW”
    UngerboeckURI =“http://mydomain.ungerboeck.net/test“,
    Expiration = System.DateTime.Now.AddMinutes(1) //Instead of a static DateTime, you can set the AutoRefresh ability (see below)
   };
}

Your API client is now ready to make calls.

Search Request

This example shows how to find all events matching a certain description.  

SearchResponse<EventsModel> myEventResults = apiClient.Endpoints.Events.Search(orgCode, $"{nameof(EventsModel.Description)} eq '{searchValue}'");

Without the SDK

Create JWT

First, you must generate a JWT. You can use the list of suggested libraries found on jwt.io for your language. If you use Javascript, here is a Javascript example to follow.

Once you have your JWT, you want to retain that in memory.

Retrieve an Account

Now that you have the token (JWT), you can make a call to the API, such as GET, POST, PUT, and DELETE.

Try a GET to retrieve an account.

Request (in C#):

Use HttpClient for the http connection. Start by adding the package for Microsoft.AspNet.WebApi.Client. Then add the code:

using System.Net.Http.Headers;
...
string url = "https://YourSite.ungerboeck.net/api/v1/Accounts/10/ACCTCODE"; //Replace ACCTCODE with an account code from your Ungerboeck.  This also assumes organization code 10.
using (var client = new HttpClient())
{
  using (var requestMessage = new HttpRequestMessage(HttpMethod.Get, url))
  {
    requestMessage.Headers.Authorization = new AuthenticationHeaderValue("Bearer", "qyJhb4ciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJKV0VMTEVTIiwia2V5IjoiOWFjN2Y2MzItMjcyNC00MDk4LTgyYjktMzhiYjg5YzcyNDdlIiwiZXhwIjoiMTY0MjQ0MDgxNCIsImlhdCI6IjE2NDI0NDA3NTQiLCJzdWIiOiIifQ.b8xeIbDABNbhdLC8TFHXUN1GEBA54ZjorNN3VTdi9rQ");
    requestMessage.Headers.Add("Accept", "application/json");

    var response = await client.SendAsync(requestMessage).ConfigureAwait(false);
    string account = await response.Content.ReadAsStringAsync();
  }
}

You can see that the token is passed as an HTTP Header inside the request. Do this for all calls to the API. 

Your response content body appears as a JSON object representing the output from your call. In this case, the output is a single account like this:

[
    {
        "Organization": "10",
        "AccountCode": "0002225",
        "MiddleInitial": "",
        "FirstName": "",
        "LastName": "",
        "Name": " ",
        "Search": "",
        "Salutation": "",
        "Title": "",
        "Address1": "",
        "Address2": "",
        "Address3": "",
        "Address4": "",
        "Address5": "",
        "Address6": "",
        "City": "",
        "State": "",
        "PostalCode": "",
        "Country": "",
        "Region": "",
        "Keyword": "",
        "Keyword2": "",
        "LegalName": "",
        "Nickname": "",
        "Class": "O",
        "Phone": null,
        "Fax": null,
        "Mobile": null,
        "Direct": null,
        "MarketSegmentMajor": "",
        "MarketSegmentMinor": "",
        "Email": null,
        "Website": null,
        "Company": "",
        ...}

Now you have completed the cycle of setting up an API call.