Using Postman

These instructions will guide you through using the Postman application with Aprimo.

Before connecting to Aprimo with Postman, or other application, you will need to set up an integration user and client registration in Aprimo. Please follow steps 1 and 2 of the REST API article on Authorization for services and daemons.

Postman is a third party tool that helps you easily create HTTP Requests to execute them and see the HTTP Responses. If you are having trouble with the REST API, it is a good idea to use a tool like Postman to ensure your request is working properly, as other development tools make it difficult to see the actual HTTP Request and Response, making troubleshooting more difficult. Postman is not provided by Aprimo and Aprimo does not provide any support for Postman, it is simply a common developer tool used to work with REST APIs. 

Postman is a Google Chrome application, however you do not need to sign in to Google or anywhere to download or use Postman. Anywhere you are prompted to sign in you can ignore it and close the login prompt.

Step 1: Install Postman

1. Download and install Postman from https://www.getpostman.com/
2. Start the Postman app

Step 2: Request an Aprimo Access Token

Before making requests to Aprimo you need to request an access token. To do so, please follow steps 3 and 4 of the REST API article on Authorization for services and daemons.

Step 3: Save the Request Configuration in Postman

Tip: It’s best to save API configurations that you will use more than once. In Postman you may save the API call to a collection. so that you can use it again later.

1. In Postman on the top bar rename the configuration to something meaningful (e.g. “Aprimo – Get Access Token)
2. On the top right drop down the Save button and select Save As
3. Create a collection if you don’t have one yet
4. Name the collection something meaningful (e.g. “Aprimo REST API”)
5. Save the request configuration to that collection
6. It’s recommended you do this for any REST API operations that you might need to do more than once

Step 4: Request a Record

1. In Postman select GET and enter a URL like this: https://[your Aprimo domain]/api/{ object name }/{ record ID }
   1. Example: To get user ID 18404 you would enter https://[your Aprimo domain]/api/users/18404
2. Header: X-Access-Token: [the accessToken value from step 2]
3. Header: Content-Type: application/json
4. Click Send and in the body of the response you should receive back the record in JSON format.
5. Save the request per the instructions in step 3 using “Save As”. This will allow you to reuse the same request configuration later by simply updating the access token.

Step 5: Create a New Record

1. In Postman select POST and enter a URL like this: https://[your Aprimo domain]/api/{ object name }
   1. Example: To create a new user you would enter https://[your Aprimo domain]/api/users
2. Header: X-Access-Token: [the accessToken value from step 2]
3. Header: Content-Type: application/json
4. Enter the request body with the record information in JSON format.
   1. Tip: If you are only testing, it might be easiest to copy the information from the response body returned in step 4 into the request body, remove the record ID, and then update fields as desired.
5. Click Send and in the body of the response you should receive back the new record in JSON format.
6. Save the request per the instructions in step 3 using “Save As”. This will allow you to reuse the same request configuration later by simply updating the access token.

Step 6: Update a Record

Tip: Generally speaking PUT will overwrite all fields in the record. In this case it’s a good idea to query the record first and update fields as needed.

1. In Postman select PUT and enter a URL like this: https://[your Aprimo domain]/api/{ object name }/{ record ID }
   1. Example: To update user ID 18404 you would enter https://[your Aprimo domain]/api/users/18404
2. Header: X-Access-Token: [the accessToken value from step 2]
3. Header: Content-Type: application/json
4. Enter the request body with the record information in JSON format.
   1. Tip: If you are only testing, it might be easiest to copy the information from the response body returned in step 4 into the request body and then update fields as desired.
5. Click Send and in the body of the response you should receive back the updated record in JSON format.
6. Save the request per the instructions in step 3 using “Save As”. This will allow you to reuse the same request configuration later by simply updating the access token.

Step 7: Search for a Record

1. Select POST and enter a URL like this: https://[your Aprimo domain]/api/{ object name }/search
   1. Tip: For searching multiple records add optional paging parameters to the end
      1. Example: To query the second set of 250 users sorted ascending order by user ID you would enter https://[your Aprimo domain]/api/users/search?limit=250&sortField=userId&sortAscending=true&offset=250
2. Header: X-Access-Token: [the accessToken value from step 2]
3. Header: Content-Type: application/json
4. Enter the request body with the search information in JSON format. Please refer to the REST API article on Searching for examples of what to include in the POST body
5. Click Send and in the body of the response you should receive back the record in JSON format.
6. Save the request per the instructions in step 3 using “Save As”. This will allow you to reuse the same request configuration later by simply updating the access token.

Step 8: Get Object Metadata

Tip: Object REST API metadata can be very helpful during development when you need to get object and field information, including field picklist options, whether the field is required or read only, field type, field max length, extended attribute metadata, etc

1. Select GET and enter a URL like this: https://[your Aprimo domain]/api/metadata/{ object name in singular form }
   1. e.g. to get user object metadata you would enter https://[your Aprimo domain]/api/metadata/user
2. Header: X-Access-Token: [the accessToken value from step 2]
3. Header: Content-Type: application/json
4. Click Send and in the body of the response you should receive back the record in JSON format.
5. Save the request per the instructions in step 3 using “Save As”. This will allow you to reuse the same request configuration later by simply updating the access token.