Quick Start - Convertr API
- Danny Hannah
Authenticating
Please see: API v4.0.0 - API Login this also details resetting your password over the API API v4.0.0 - Reset User Password
Lead Data
Once you've requested an access token, you'll be able to start making calls to the API.
Requests & Responses
A collection is a listing of objects, for example /api/v4/leads will show you a list of available leads on the enterprise. You can then request more information about a specific object by making an item request, simply by adding the id to the end of the parent request, e.g. /api/v4/leads/11001.
Example response:
{
"@context": "/api/v4/contexts/Lead",
"@id": "/api/v4/leads",
"@type": "hydra:Collection",
"hydra:member": [
{
"@id": "/api/v4/leads/53284",
"@type": "Lead",
"id": 53284,
"publisherSubId": null,
"formHash": "129",
"createdTs": "2018-06-21T08:52:48+00:00",
"postcode": "",
"addressLine1": "",
"addressLine2": "",
"addressLine3": "",
"addressLine4": "",
"firstName": "Danny",
"lastName": "Hannah",
"email": "danny@convertr.io",
"telephone": "07702695392",
"integration": false,
"overAllocation": false,
"visible": true,
"processrStatus": 1000,
"score": 100,
"hardfail": false,
"maxScore": 100,
"baseCurrencyPublisherPayout": "0.00",
"publisherPayout": "0.00",
"baseCurrencyAdvertiserPayout": "0.00",
"advertiserPayout": "0.00",
"advertiserBillable": false,
"publisherBillable": false,
"leadData": [
{
"@id": "/api/v4/lead-datas/1528942",
"@type": "LeadData",
"name": "emailDomain",
"value": "@convertrmedia.net"
},
{
"@id": "/api/v4/lead-datas/1528943",
"@type": "LeadData",
"name": "createdDate",
"value": "2018-06-21"
},
{
"@id": "/api/v4/lead-datas/1528944",
"@type": "LeadData",
"name": "country",
"value": "United Kingdom"
},
{
"@id": "/api/v4/lead-datas/1528950",
"@type": "LeadData",
"name": "leadHash",
"value": "27cb08764a6e16099ace1d580c5e4d5d"
}
...
],
"leadNotes": [
"/api/v4/lead-notes/90628",
"/api/v4/lead-notes/90629",
"/api/v4/lead-notes/90632",
"/api/v4/lead-notes/90633"
],
"campaign": "/api/v4/campaigns/44064",
"qaResult": {
"@id": "/api/v4/lead-qa-results/1",
"@type": "LeadQaResult",
"name": "Valid"
},
"leadFlag": {
"@id": "/api/v4/lead-flags/1",
"@type": "LeadFlag",
"name": "Valid"
},
"leadProcessrJobs": [
"/api/v4/processr-job-leads/517719",
"/api/v4/processr-job-leads/517720",
"/api/v4/processr-job-leads/517722"
]
},
...
],
"hydra:totalItems": 21,
"hydra:view": {
"@id": "/api/v4/leads?createdTs%5Bafter%5D=2018-06-20&access_token=ZmI2ZjE4OGVkMDhjYjBkZjNjZmZjOTU0ZWY4MGQ4OGU5ODYxODk3N2RhYTA1NWE0ZWRmN2ZiYTVmMzUyZTFhMQ&page=1",
"@type": "hydra:PartialCollectionView",
"hydra:first": "/api/v4/leads?createdTs%5Bafter%5D=2018-06-20&access_token=ZmI2ZjE4OGVkMDhjYjBkZjNjZmZjOTU0ZWY4MGQ4OGU5ODYxODk3N2RhYTA1NWE0ZWRmN2ZiYTVmMzUyZTFhMQ&page=1",
"hydra:last": "/api/v4/leads?createdTs%5Bafter%5D=2018-06-20&access_token=ZmI2ZjE4OGVkMDhjYjBkZjNjZmZjOTU0ZWY4MGQ4OGU5ODYxODk3N2RhYTA1NWE0ZWRmN2ZiYTVmMzUyZTFhMQ&page=3",
"hydra:next": "/api/v4/leads?createdTs%5Bafter%5D=2018-06-20&access_token=ZmI2ZjE4OGVkMDhjYjBkZjNjZmZjOTU0ZWY4MGQ4OGU5ODYxODk3N2RhYTA1NWE0ZWRmN2ZiYTVmMzUyZTFhMQ&page=2"
},
"hydra:search": {
"@type": "hydra:IriTemplate",
"hydra:template": "/api/v4/leads{?id,id[],email,campaign.id,campaign.id[],order[id],createdTs[before],createdTs[strictly_before],createdTs[after],createdTs[strictly_after],updatedTs[before],updatedTs[strictly_before],updatedTs[after],updatedTs[strictly_after]}",
"hydra:variableRepresentation": "BasicRepresentation",
"hydra:mapping": [
{
"@type": "IriTemplateMapping",
"variable": "id",
"property": "id",
"required": false
},
{
"@type": "IriTemplateMapping",
"variable": "id[]",
"property": "id",
"required": false
},
{
"@type": "IriTemplateMapping",
"variable": "email",
"property": "email",
"required": false
},
{
"@type": "IriTemplateMapping",
"variable": "campaign.id",
"property": "campaign.id",
"required": false
},
{
"@type": "IriTemplateMapping",
"variable": "campaign.id[]",
"property": "campaign.id",
"required": false
},
{
"@type": "IriTemplateMapping",
"variable": "order[id]",
"property": "id",
"required": false
},
{
"@type": "IriTemplateMapping",
"variable": "createdTs[before]",
"property": "createdTs",
"required": false
},
{
"@type": "IriTemplateMapping",
"variable": "createdTs[strictly_before]",
"property": "createdTs",
"required": false
},
{
"@type": "IriTemplateMapping",
"variable": "createdTs[after]",
"property": "createdTs",
"required": false
},
{
"@type": "IriTemplateMapping",
"variable": "createdTs[strictly_after]",
"property": "createdTs",
"required": false
},
{
"@type": "IriTemplateMapping",
"variable": "updatedTs[before]",
"property": "updatedTs",
"required": false
},
{
"@type": "IriTemplateMapping",
"variable": "updatedTs[strictly_before]",
"property": "updatedTs",
"required": false
},
{
"@type": "IriTemplateMapping",
"variable": "updatedTs[after]",
"property": "updatedTs",
"required": false
},
{
"@type": "IriTemplateMapping",
"variable": "updatedTs[strictly_after]",
"property": "updatedTs",
"required": false
}
]
}
}Under the "hydra:search" property, you'll you'll see a template result which shows all available options which can be passed through to the end point.
Under "hydra:mapping", you'll notice a detailed breakdown of each of the template items, whether it's required and what property it applies too. Some example requests are as follows:
Get full collection:
GET https://{enterprise}.cvtr.io/api/v4/leadsGet more information for a specific object by id:
GET https://{enterprise}.cvtr.io/api/v4/leads/11001The following request will filter the collection by a single id, or the second example will filter by multiple lead ids.
Changing the ordering of the collection to order the results by id descending.
You can, of course, combine both multiple ordering options and filters to make your request very specific.
You can also request more items per page by passing the ?itemsPerPage=x property in your request. The maximum number of results per page is 100.
Campaigns
Retrieving a list of campaigns:
Example response: