Retrieving Leads
- Danny Hannah
- Adam Carter
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.jsonld 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.jsonld.
Using the .jsonld extension you'll be able to see more context about the api end point, such as supported filters and ordering options.
For example:
{
"@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+ciscotest1@convertrmedia.net",
"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",
"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/leads.jsonld?access_token=***Get more information for a specific object by id:
GET https://{enterprise}.cvtr.io/api/v4/leads/11001.jsonld?access_token=***The 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.