Hi and welcome to this guide.
In this guide we'll go through a couple of normal scenarios to help you get up and running as fast and simple as possible.
The guide is a work in progress and feedback is very welcome.
This guide focuses on the API in it's raw form, which is REST over HTTP with JSON as the wire-format. It may also help to look at some of the code examples.
Throughout the guide, we'll link to services in the API exploration tool or directly. When you call services through the exploration tool, the results are returned as json, since the requests are made with "Accept: application/json" in the header. Linking directly to the service means that the browser will send "Accept: text/html" in the header and the service framework will then attempt to render the result as html. Displaying the result as html is great for inspecting your account and a few other cases, but in general we recommend using the tool to see the results in json.
Once you start calling services, through the exploration tool or directly, the browser will request your credentials. Read more about authentication.
The first thing you should do is to take a look at your account and see if it configured to match your needs. You can see it directly in html form or via the API exploration tool (you need to click "Try it out!").
You should now see something like this:
{
"username": "myaccount@example.com",
"logRequestData": false,
"projectRights": [
"A project name",
"B2B*",
],
"resourceRights": {
"Account": [
"GET"
],
"Calls": [
"GET"
],
"Campaigns": [
"GET"
],
"Leads": [
"GET",
"POST"
],
"Organization": [
"GET"
]
}
}
In this case the account has access to GETting calls, campaigns, leads, organization resources such as users and its own account details. It also has the right to upload (POST) leads. If, on your account, you don't see all the rights you need then contact support and have them added.
This account also has access to all campaigns in the "A project name" project and all campaigns whose project starts with "B2B". Project rights can have wildcards character in them and in this case "B2B*" gives access to all projects whose names starts with, "B2B".
In order to be able to upload leads you need the "POST Leads" right. You'll also need project rights to whatever campaign you'll be uploading to.
Leads are grouped into campaigns, so the first thing you'll need to know is what campaign to import to. The web api uses campaign unique ids or campaign codes to identify campaigns, so you'll need to get the relevant id or code (you should prefer ids even though the following mostly refers to codes). We recommend that a test campaign is created for getting import up and running without interferring with normal production.
Depending on how your account is set up, you may or may not have access to seeing campaigns. In case you do, now would be a great time to go and check them out (Remember that if you think you should be able to see campaigns, but don't have the right, please contact support to have it corrected) . In case you don't and won't have access to seeing campaigns, someone should give you the campaign id or code to upload to.
Once you know the campaign you should head on over to the import example request service. Once there, type in the campaign code and click "Try it out!". Now you should have something like this:
{
"campaignCode": "ExampleCampaignCode",
"data": {
"name": "example name, type is varchar, regex used for validation .*",
"description": "example description, type is text, regex used for validation .*",
"phone": "example phone, type is phone, regex used for validation ^\\s*((\\+|00)?[\\s\\-\\(\\)]*)?(\\d[\\s\\-\\(\\)]*){5,25}\\s*$"
}
}
{
"campaignCode": "ExampleCampaignCode",
"data": {
"name": "Ian M. Banks",
"description": "Possibly the best sci-fi author ever",
"phone": "+44 1234567890"
}
}
There's probably more data entries defined that you can upload to, but they are not shown in the default example view. To get an example body which includes more entries set "ShowAllDataEntries" to 1 or true.
Once you have this working, your next step should probably be to read more about lead pools.
In order to be able to export leads you need the "GET SimpleLeads" or "GET Leads" right. SimpleLeads is quite simple, you can read more about it here. SimpleLeads is recommended unless you need data in tabular format.
In the following we'll go over "GET Leads" in more detail.
Exporting leads is based on the lead search, which you should read about before continuing.
To get started with exporting leads you should check out which searches you have access to. You can do that here or here.
Once you found the name of the search you want to export from you have two options: To export the leads as csv or to export them as objects.
To export the leads as csv simply go here, type in the name of the search, a 'from' date and optionally a 'to' date. Click 'Try it out!'. Done.
The csv export is also super easy to test in the browser. Simply insert subdomain, appropriate search name and 'from' date in the url below and insert it into a browser bar:
https://{yoursubdomain}.herobase.com/api/leads/csv?SearchName=ExampleSearchName&ModifiedFrom={todaysdate}
There are some other parameters to tweak, if you want something other than the default format. Particularly if the response is for human consumption, rather than computer processing, it might be a good idea to set useSystemHeaders=false and maybe encoding=windows-1252, depending on where you are in the world. Changing the culture to one of the supported language types will translate some of headers into that language.
Exporting leads as objects is almost as simple as exporting as csv. The response isn't really suitable for human consumption, but ideally suited for computer processing.
To try it out go here and, as before, type in the name of the search and the 'from' date. Click 'Try it out!'. Done.