/
Retrieving Leads

Retrieving Leads

Owned by Danny Hannah
Last updated: Feb 10, 2022

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.

Related content