The Simplest Approach

Once you have content created in Aprimo DAM, lets turn to the Aprimo REST API to retrieve it. We can break this section into 3 parts. Getting Metadata, Getting Download Orders, and Getting Public Links.

Before anything else you will need to know how to get an access token. Head to our authorization documentation to learn about getting an Aprimo access token.

Making Your First Request

Lets take a look at a simple Aprimo DAM request: Getting a Record.

curl --location -g --request GET 'https://{{tenant}}.dam.aprimo.com/api/core/record/{{recordID}}' \
--header 'Authorization: Bearer {{token}}' \
--header 'Accept: application/json' \\
--header 'API-VERSION: 1'

var client = new RestClient("https://{{tenant}}.dam.aprimo.com/api/core/record/{{recordID}}");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "application/hal+json";);
request.AddHeader("Authorization", "Bearer {{token}}");
request.AddHeader("API-VERSION", "1");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

In the Curl or C# example provided, you will need to replace the variables {{tenant}} and {{recordID}} with the appropriate values. To get the Record ID of the record you just created, navigate to the Aprimo DAM and find your record, either by searching for it or browsing for it. The record ID will be the last value in the URL.

https://{{tenant}}.dam.aprimo.com/dam/spaces/123456789ancdef987654321/items/{{recordID}}

Additionally, lets break down each header:

• Authorization – You will need to use the Bearer token you obtained in the previous section
• API-VERSION – this headers value shoud always be ‘1’
• Accept – Aprimo accepts the following values:
  •  application/hal+json
  •  application/json
  •  text/json
  •  */*.

The HTTP response to your Get Record request will look like the below example

{
"_links": {
"fields": {
"href": "https://productstrategy1.dam.aprimo.com/api/core/record/f71fd1028eaa4f82b277ad1100ff370a/fields",
"select-key": "fields"
},
"files": {
"href": "https://productstrategy1.dam.aprimo.com/api/core/record/f71fd1028eaa4f82b277ad1100ff370a/files",
"select-key": "files"
},
"preview": {
"href": "https://productstrategy1.dam.aprimo.com/api/core/record/f71fd1028eaa4f82b277ad1100ff370a/image/preview",
"select-key": "preview"
},
"thumbnail": {
"href": "https://productstrategy1.dam.aprimo.com/api/core/record/f71fd1028eaa4f82b277ad1100ff370a/image/thumbnail",
"select-key": "thumbnail"
},
"masterfile": {
"href": "https://productstrategy1.dam.aprimo.com/api/core/record/f71fd1028eaa4f82b277ad1100ff370a/masterfile",
"select-key": "masterfile"
},
"masterfilelatestversion": {
"href": "https://productstrategy1.dam.aprimo.com/api/core/record/f71fd1028eaa4f82b277ad1100ff370a/masterfilelatestversion",
"select-key": "masterfilelatestversion"
},
"classifications": {
"href": "https://productstrategy1.dam.aprimo.com/api/core/record/f71fd1028eaa4f82b277ad1100ff370a/classifications",
"select-key": "classifications"
},
"accesslists": {
"href": "https://productstrategy1.dam.aprimo.com/api/core/record/f71fd1028eaa4f82b277ad1100ff370a/accesslists",
"select-key": "accesslists"
},
"permissions": {
"href": "https://productstrategy1.dam.aprimo.com/api/core/record/f71fd1028eaa4f82b277ad1100ff370a/permissions",
"select-key": "permissions"
},
"locks": {
"href": "https://productstrategy1.dam.aprimo.com/api/core/record/f71fd1028eaa4f82b277ad1100ff370a/locks",
"select-key": "locks"
},
"modifiedby": {
"href": "https://productstrategy1.dam.aprimo.com/api/core/user/b849a21959ec4994ac3aa9f8012f87ae",
"select-key": "modifiedby"
},
"createdby": {
"href": "https://productstrategy1.dam.aprimo.com/api/core/user/2dd66657db834b579a12a96c00ed6522",
"select-key": "createdby"
},
"self": {
"href": "https://productstrategy1.dam.aprimo.com/api/core/record/f71fd1028eaa4f82b277ad1100ff370a"
}
},
"id": "f71fd1028eaa4f82b277ad1100ff370a",
"status": "Released",
"contentType": "Record",
"title": null,
"tag": null,
"modifiedOn": "2021-12-02T15:29:59.857Z",
"createdOn": "2021-04-21T15:29:12.563Z"
}

Lets break down this response. We received some good data from this request, including the ID, current status and the title, but this probably isn’t everything you need. The _links attribute contains a series of objects that are related to the object you just made a GET request on, in this case a Record. You can use these ‘select-key’ values to request additional data from your Get Record request. In the following section we’ll use the fields select key to get all the different custom metadata fields on your record.

Getting Record Metadata

If you’ve been following along, you probably have a GET Record response that you feel doesn’t contain all the data you need. We can expand this request using select headers to request that Aprimo returns more data than just the base data of a Record. As an example, lets get all the custom metadata fields on a record.

curl --location --request GET 'https://{{tenant}}.dam.aprimo.com/api/core/record/{{recordID}}'
--header 'Authorization: Bearer {{token}}'
--header 'API-VERSION: 1'
--header 'select-record: fields'
--header 'Accept: application/hal+json'

{
"id": "f71fd1028eaa4f82b277ad1100ff370a",
"status": "Released",
"contentType": "Record",
"title": null,
"tag": null,
"modifiedOn": "2021-12-02T15:29:59.857Z",
"createdOn": "2021-04-21T15:29:12.563Z",
"_embedded": {
"fields": {
"_links": {
"self": {
"href": "https://productstrategy1.dam.aprimo.com/api/core/record/f71fd1028eaa4f82b277ad1100ff370a/fields"
}
},
"items": [
{
"_links": {
"self": {
"href": "https://productstrategy1.dam.aprimo.com/api/core/record/f71fd1028eaa4f82b277ad1100ff370a/field/7be712d7dcea45cc81cca832013fabd1"
},
"definition": {
"href": "https://productstrategy1.dam.aprimo.com/api/core/fielddefinition/7be712d7dcea45cc81cca832013fabd1",
"select-key": "definition"
}
},
"dataType": "SingleLineText",
"fieldName": "Record Title",
"label": "Title",
"id": "7be712d7dcea45cc81cca832013fabd1",
"localizedValues": [
{
"value": "multi-colored umbrella",
"languageId": "00000000000000000000000000000000",
"readOnly": null,
"modifiedOn": "2021-04-21T15:29:42.693Z"
}
],
"inheritanceState": null,
"inheritable": null
},
{
"_links": {
"self": {
"href": "https://productstrategy1.dam.aprimo.com/api/core/record/f71fd1028eaa4f82b277ad1100ff370a/field/aa5c4a0e6ea94d44892da84900931f40"
},
"definition": {
"href": "https://productstrategy1.dam.aprimo.com/api/core/fielddefinition/aa5c4a0e6ea94d44892da84900931f40",
"select-key": "definition"
}
},
"dataType": "MultiLineText",
"fieldName": "Description",
"label": "Description",
"id": "aa5c4a0e6ea94d44892da84900931f40",
"localizedValues": [
{
"value": "colored umbrellas in the air",
"languageId": "00000000000000000000000000000000",
"readOnly": null,
"modifiedOn": "2021-11-18T23:15:07.443Z"
}
],
"inheritanceState": null,
"inheritable": null
}
]
}
}
}

There we go! Now our response has all of the custom metadata fields on your Record and you can use this response to pull that data into any external system you’re looking to integrate with.

Lets break down that new {select-record: fields} header. The header name, select-record, is derived from the fact that we trying to get data associated to the record object; and the value fields is the value of the select-key for the fields object in GET Record’s _links attribute. You can do this with any of those objects in _links. Play around with it and see what record data can be obtained from this simple request.

You can learn more about Aprimo select headers over at this article (Link to select header article)

Next up we’re going to look at a scenario where you want to get the raw file binary and need to place a Download Order.

One of most common pieces of an integration with Aprimo DAM involves copying the asset from Aprimo into an external system. In this section were going to walk through one way to do this, by placing a Download Order. A download order is a request to Aprimo to get a temporary URL that will contain the the requested file binary. See the below example request.

curl --location --request POST 'https://{{tenant}}.dam.aprimo.com/api/core/orders'
--header 'Authorization: Bearer {{token}}'
--header 'accept: application/json'
--header 'content-type: application/json'
--header 'API-VERSION: 1'
--data-raw '
{
"type":"download",
"disableNotification":true,
"targets":[
{
"recordId": "{{recordID}}",
"targetTypes":["Document"],
"assetType": "LatestVersionOfMasterFile"
}
]
}'

You will need to replace some of the variable in the above example with your Aprimo tenant name, and the ID of the record you want to place a download order for. The download URL will be found in the deliveredFiles attribute of the response. If the deliveredFiles attribute is empty, that means Aprimo is currently processing the order. Instead, get the id attribute and make a follow up request to check the status of your order. Download orders are an asychronous process, which is why deliveredFiles may be empty originally.

curl --location --request GET 'https://{{tenant}}}}.dam.aprimo.com/api/core/order/{{orderID}}'
--header 'Authorization: Bearer {{token}}'
--header 'accept: application/json'
--header 'content-type: application/json'
--header 'API-VERSION: 1' \

This request will get the status of your previously placed order. If the deliveredFiles attribute is still empty, check the status attribute. When building a full integration with this method, it is recommended to stagger your status check requests. Wait 5 seconds before the first status check, then 10, then 20, and so on. The returned URL to deliver the file binary is valid for 24 hours.

Using Download Orders to deliver the file binary is not the only way to deliver assets stored in Aprimo DAM. Aprimo Public Link Orders work similarly, but instead of a download URL that returns the file binary, you receive a URL to the file on a public CDN. Unlike a download order, a Public Link Order is not asynchronous. If the file is already on the public CDN, then the URL is delivered. If the file is not currently published on the public CDN, then it is automatically published to the CDN and the URL is delivered instantly.

curl --location --request POST 'https://{{tenant}}.dam.aprimo.com/api/core/orders'
--header 'Authorization: Bearer {{token}}'
--header 'accept: application/json'
--header 'content-type: application/json'
--header 'API-VERSION: 1'
--data-raw '{
"type": "publicCdn",
"targets": [{
"recordId": {{recordID}},
"renditionName": "full"
}]
}'

The response to this request will look a lot like the previous download order request you made, but the deliveredFiles attribute will always contain a URL. See the below example response.

{
"deliveredFiles": [
{
"deliveredPath": "https://p1.sb.aprimocdn.net/productstrategy1/c2ed4395-7e67-4f93-89ca-ad41013fed9d/Umbrella%20Asset%20For%20Google%20Analytics_Original%20file.jpg",
"recordId": "c2ed43957e674f9389caad41013fed9d",
"renditionName": "Original file",
"status": "Success"
}
],
"orderType": "publicCdn",
"totalFileSize": 0,
"targets": null,
"creatorEmail": "integrations@aprimo.com",
"disableNotification": false,
"earliestStartDate": null,
"executionTime": "00:00:00",
"id": "123456789anbcdegh987654321",
"type": "PublicCdnOrder",
"priority": 0,
"startedOn": null,
"status": "Success",
"message": null,
"failedTargetsCount": 0,
"createdOn": "2023-04-06T19:12:04.72112Z",
"createdBy": null
}

Another common use case is the ability to update metadata on an Aprimo asset with data from an external system. The best way to accomplish this is to use the Aprimo REST API. Make a PUT request against the assets URL to edit metadata.

curl --location --request PUT 'https://{{tenant}}.dam.aprimo.com/api/core/record/{{recordID}}'
--header 'Authorization: Bearer {{token}}'
--header 'API-VERSION: 1'
--header 'User-Agent: Postman'
--header 'Content-Type: application/json'
--data-raw '{
"fields":{
  "addOrUpdate":[  
     {  
        "id":"{{fieldID}}",
        "localizedValues":[  
           {  
              "languageId":"00000000000000000000000000000000",
              "value":"{{value}}"
           }
        ]
     }
  ]
}
}'

There are a few new things in this request, so lets go over them. First the fieldID, this is the unique identifier for the specific field you are trying to edit and it can be retrieved from a previous request we made: GET Record With Metadata. Use the response of that previous request to find the ID of the field you wish to edit. For the purposes of learning, we recommend using a Text field to start.

This request also contains a “languageId” attribute. Aprimo supports multiple lanugages, but for the purposes of learning you should just use “00000000000000000000000000000000” which Aprimo refers to as a the default language. In your partner environment, that will most likely be English.

The last piece is the new value of the field. Replace the {{value}} variable with the new value of the field.

There is a lot more to know about fields. When you start to expand your integration into different types of fields or look to support multiple language, check out this article [Link to Fields Article]

This article contains the very start of learning how to build an integration with Aprimo; but we do have some additional articles covering specific use cases that might be useful for your learning. The Common Integration Patterns section details our recommended approach to a list of common integration types.

If you’d like to continue through the Integration Tutorial, check out some of the following articles:

• Environment Access
• DAM Functional Concepts
  • Select Headers
  • Creating Fields