Support : API Guide
API Requests

CoreTRM allows external systems to interface with it. External systems are able to request or update CoreTRM using the API of CoreTRM provided they have the necessary security access.

There is a built-in API builder in CoreTRM to help users generate API request urls based on data needed and filter criteria.

The data return can be either in JSON or CSV format.

To access the API Builder for generating API requests, go to System Admin and then to the API Builder->API Requests tab.

Example of Sort Item Refs
Example of Summary Item Refs
Example of Grouping Filter
Testing API Request using Postman
API Requests

API Guide API Requests

To start building API request, from API Requests view:

  1. Click on New Button to create a new line.
  2. In API Request Name enter the name for the API request.
  3. In Object select the base object from which the data should be retrieved from. This is similar to writing an SQL query where you would choose the most appropriate table to start from.
  4. In Per Page Num indicated how many data results to be displayed per page. This is defaulted to 12 per page.
  5. In Page Num indicate the page number to be display. This is defaulted to page 1.
  6. In Return CSV check the box if the data return should be in CSV format.
  7. In Item Refs select the Item Refs to be included as part of the data to be retrieve from the API.
  8. *Detail steps on how to select Item Refs. can be found here.*

  9. In Sort Item Refs indicate if the results should be sorted by selected Item Refs.
  10. *Example of Sort Item Refs can be found here.*

  11. In Summary Item Refs indicate if the results should be summarized by selected Item Refs.
  12. *Example of Summary Item Refs can be found here.*

  13. In Include Key Items? check the box if Key Items will be included in the data results.
  14. In Include Foreign Key Items? check the box if Foreign Key Items will be included in the data results.
  15. In Include TimeStamp? check the box if the Timestamp item will be included in the data results.
  16. In Include Additional Meta? check the box if additional meta will be included in the data results.
  17. The following additional meta will be included in the data results: "isKeyItemInd","isTimeStampItemInd","canChangeOnUpdateInd","canIncludeOnInsertInd","canIncludeOnDeleteInd".

  18. Click Save Button to confirm creation.
  19. To edit API requests details after creation Click Edit Button to edit.

Use the Filters panel to add filters to the request:

API Guide API Requests Filters

  1. Click on New Button to create a new line.

  2. In Order indicate the order number of the filter criteria.

  3. In And Or if there is more than 1 filter criteria, "And" or "Or" can be used to indicate the filter crieria relationship.

  4. In Left Brackets left brackets should be included when there are "Or" conditions present.

    API Guide API Requests Example Brackets

  5. In Left Item Ref. select the Left Item Ref to be used for this filter criteria.

  6. In Condition select the condition to be used for this filter criteria.

    *Conditions available are "contains", "equals", "greater than", "greater than or equal to", "in", "less than", "less than or equal to", "not contains", "not equals" and "not in".

  7. In Right Item Ref. select the Right Item Ref if the condition is comparing with another Item Ref value. Either Right Item Ref. or Right Value is to be used.

  8. In Right Value enter a Right Value if the condition is to compare with a fixed value. Either Right Item Ref. or Right Value is to be used.

  9. In Right Brackets right brackets should be included when there are "Or" conditions present.

  10. In Grouping Filters? check the box if the filter criteria is involved a function that requirs grouping. Example of functions: fnSum, fnMax, fnMin, etc. Grouping filters work in a similar way to SQL Having clauses.

    *Example of Grouping Filters can be found here.*

  11. In Active? check the box if this line of filter criteria is to be active.

  12. Click Save Button to confirm creation.

  13. To edit filter details after creation, Click Edit Button to edit.

After the required data and filters are indicated in API requests and Filters view, CoreTRM will generate the appropriate syntax and a API URL that can be used to retrieve the data from the system.

The API URL can be used by external systems as the API End Point to call the API in order to retrieve data from CoreTRM.

API Guide API Requests URL

Once the API URL is created as above click on API Get Button to preview the data results as shown below.

API Guide API Requests Preview Data Results

As part of the JSON data results the system will provide additional information on the Item Refs. Below is the default information provided.

API Guide API Requests Preview Data Results

In addition, as part of the JSON data results, the system will also provide information on paging as shown below.

API Guide API Requests Preview Data Results

Item Refs

To start selecting Item Refs to be included in the data results:

  1. From the Item Refs click on Magnifier Button to open the Item Refs browser pop up.
  2. From the "Object" section, select the object from which the Item Ref you wish to be included in the API data results. After selecting the "Object", from the "Object ITem Refs" section, select the Item Refs that you wish to use.
  3. For Example, below we are selecting the contractdate item ref from Contract object.

    API Guide API Requests Select Item Refs

  4. To add more Item Refs click on Add Item Refs Button to add the next item ref.
  5. For Example, below we are selecting the contractreference item ref from Contract object.

    API Guide API Requests Select Item Refs 2

  6. It is also possible to add item refs from other objects other than the base object that you have selected in API Requests -> Object column from above as long as the destination object has a relationship with the base object.
  7. For Example, below we are selecting counterpartyname item ref from Counterparty object.

    a. From the "Object" section select Counterparty.

    b. From the "Object Item Refs." section select Counterparty Name.

    API Guide API Requests Select Item Refs 3

  8. Once all the Item Refs are selected click on Apply Button to confirm the selection.
  9. More information about Item Refs can be found in Understanding Item References.

Item Refs Using Functions

In addition, API functions can also be used as part of the Item Refs selection.

For example, to include the fnIsNull function. If contract description is null, True: set value to "Description is empty" and False: set value to contract description.

  1. From the Item Refs click on Magnifier Button to open the Item Refs browser pop up.
  2. From the popup screen click on Function.
  3. API Guide API Requests Select Function

  4. Click on fnNew_button.png and select fnIsNull.
  5. API Guide API Requests fnIsNull

  6. The system will suggest the required parameters needed for this function.
  7. API Guide API Requests fnIsNull Function

  8. Click on i:Value1 and select contractdescription.
  9. API Guide API Requests fnIsNull Contractdescription

  10. Click on i:True and then click on Value. Enter text value and click ok
  11. API Guide API Requests fnIsNull True Value

  12. Click on i:False, select contractdescription and click ok.
  13. API Guide API Requests fnIsNull False Value

  14. Click on Apply Button to confirm the selection.
  15. Once apply button is clicked. The Item Ref will be as per below.
  16. API Guide API Requests fnIsNull Final results

More information about API functions can be found in API Functions.

Example of Sort Item Refs

For Example, using Contract object, sort by contractseqnum.

API Guide API Requests Example of Sort

The data result returned from the API will be sorted by contractseqnum as shown below.

API Guide API Requests Example of Sort Results

Example of Summary Item Refs

For Example, using Valuation object, summarized profitandlossvaluetodate and valuecurrencycode.

API Guide API Requests Example of Summary

The data result returned from the API will display a summary value as shown below.

API Guide API Requests Example of Summary Result

Example of Grouping Filter

For Example, using Valuation object, returning Strategy book, Strategy Name and Sum of totalchangevalue.

API Guide API Requests Example of Grouping Filter

When a filter criteria involves a grouping function, such as fnSum(i:totalchangevalue) > 0. The filter citeria will have to have "Grouping Filter" checked.

API Guide API Requests Example of Grouping Filter

The API will return data with fnSum(i:totalchangevalue) > 0 as shown below.

API Guide API Requests Example of Grouping Filter Results

If "Grouping Filter" is not checked, the system will return an error as shown below:

API Guide API Requests Example of Summary Result

Testing API Requests using Postman

Once the API Request URL is generated, the data can also be retrieved by an external system from CoreTRM API.

One of the ways to simulate an external system retrieving data from CoreTRM API is to use the Postman application.

Below are the steps to simulate retrieving data from CoreTRM API using Postman:

  1. In order to retrieve data from CoreTRM API you have to obtain an API token first.
  2. The API token can be obtained by following the steps here.
  3. Once you have obtained the API token you have to include the token in the header of your API Call in Postman.
  4. In Postman open a new tab and navigate to the Headers tab.
  5. From the Headers tab add a new Key: Authorization and Value: Bearer XXXXX. XXX is the token that you have obtained in step 2.
  6. API Guide API Request Postman header

    *The API token will typically expire in 18 to 24 hours depending on the Tenant Settings.*

  7. Next we will need the API endpoint for your environment. The API endpoint of your environment can be found in your API updates "Execute Update" view.
  8. The endpoint will be typically be similar to https://XXXX.coretrm-app.com/api/tenantid/dataobjectdata/core_contract?itemrefs=contractdate,contractreference,contract.core_counterparty.counterpartyname,commoditieslist,contractdescription,contractapprovalstatus.dm_dataobject_item_lookup.itemdescription,otherpartytype&filter=contractapprovalstatus.dm_dataobject_item_lookup.itemdescription.eq.Proposed.and.otherpartytype.eq.T&perpage=12

    API Guide API Requests Postman Endpoint

  9. After obtaining the API endpoint this can be entered in the URL section in Postman.
  10. The action will stay as "GET" since we are retrieving data from the API endpoint.
  11. API Guide API Requests Postman Post URL

  12. Finally when you click on the "Send" button in Postman, this will retrieve the data from CoreTRM as shown below.
  13. API Guide API Requests Postman Send

Back to top
Need More Assistance?

Please get in touch.

Chat with

CoreTRM