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.
GET https://{enterprise}.cvtr.io/api/v4/leads.jsonld?id=11001&access_token=***
GET https://{enterprise}.cvtr.io/api/v4/leads.jsonld?id[]=11001&id[]=11000&access_token=***Changing the ordering of the collection to order the results by id descending.
GET https://{enterprise}.cvtr.io/api/v4/leads.jsonld?order[id]=desc&access_token=***
You can, of course, combine both multiple ordering options and filters to make your request very specific.