You can accomplish a lot by using API calls with Eloqua and it can be a very powerful tool. Here we will show you how to send API requests to Eloqua. For this we will be using Postman which is a free REST client for testing APIs.
First, if you don’t already have it, you will want to download Postman to your computer. To do this just go to www.postman.com and click the appropriate “Download the desktop app” link for your computer.
Once you downloaded Postman, just open it up on your computer. For this exercise we will create a new workspace so just click on the Workspaces menu item in Postman and select “New Workspace”.
On the next screen we will give our Workspace a name and select the Visibility for it. We will just call it “Test Calls” and just select “Personal” for the visibility since we don’t need to share this example with others. Once that info is filled in just click the “Create Workspace” button in the bottom right of that screen.
Our Workspace is now set up so will will now add a “Collection” to it by clicking the “+” link next to Connections as shown below.
Once you create the New Collection you can then see the option to “Add a request” to that collection by clicking the link as shown.
Once you add your request you will want to click on the Authorization tab and then select an authorization method. For our example we will just be using Basic Authorization so will select that from the drop down menu. In the username field you enter your Eloqua Company name, followed by a backslash, and your Eloqua username. For example, in my case I will enter “MarTechHero\mark.meyer” for the username. Then just enter your password in the password field.
Next, click on the “Headers” tab in Postman. Notice that an Authorization header was added for us. You can keep all the Keys and Values that are already listed unchanged but you will need to add one line since in this example we will making a request to the application API. So in an empty Key field type “Content-Type” and for the Value select “application/json”.
This is all the set up that we will need to do in Postman so we are now ready to send a request. The first thing we need to do is determine our Eloqua base URL. To determine our base URL we can just simply perform a GET request to the endpoint: “https://login.eloqua.com/id”. Just put that endpoint in the field next to GET in Postman and click “Send” as shown below.
In the response that will be displayed on the lower half of the Postman screen, you will see the “rest” property displays the base URL’s for Eloqua’s application API and Bulk API. These URLs are what you will use to send API requests. In our example, since we will be sending a request to the application API, we will use the application API URL. The “p01” part of the base URL just signifies which Eloqua pod you are on. For example, if your instance of Eloqua is on Pod 4 then that part of the URL would be “p04” instead.
We will enter the first part of that URL into Postman as the beginning of our request URL so enter “https://secure.p01.eloqua/API/REST/”. Next we need to select the endpoint we will be calling. To learn about all of the supported Eloqua endpoints go to Eloqua’s API documentation.
For this example we will use the application’s API contacts endpoint to retrieve a list of all contacts in our Eloqua database. According to the the Eloqua Documentation, as shown if you click here, the endpoint we will need to enter into Postman for this is “https://secure.p01.eloqua.com/API/REST/1.0/data/contacts” so we will enter that and click Send.
After you click Send you will see in the lower half of the Postman screen the response with a list of all the contacts in the database.
Now let’s try creating a contact. The URL to the resource for creating a contact differs slightly so we will need to modify our request link in Postman accordingly as described in the Eloqua API documentation as shown if you click here. We will first change the method in Postman from GET to POST and then enter the following endpoint: “https://secure.p01.eloqua.com/API/REST/1.0/data/contact”
Now, since this is a POST request, we will need a request body that defines the details of the contact we are going to create. You can see examples of these requests back on the Eloqua API documentation page and I also pasted an example from that page below.
We will just make our example really easy and just use the following JSON that will just add the email address for a new contact:
{
“emailAddress”:”[email protected]”
}
We will copy that JSON and paste it into the request body of Postman. You do this by selecting the “Body” tab in Postman and then select the radio button of “raw” and paste the above JSON in that box as shown below.
Once it is populated, as shown above, you simply click the Send button in Postman to send the request. Once you send the request you will see the success response on the bottom part of Postman showing you that the contact was created.
This should give you a good start on creating your own API requests to Eloqua. Just refer back to the Eloqua API documentation to see more example of endpoints that you can try for yourself. Good luck!
