/
Quick Start - Convertr API

Quick Start - Convertr API

Owned by Danny Hannah
Last updated: Feb 10, 2022
6 min read

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/leads

Get more information for a specific object by id:

GET https://{enterprise}.cvtr.io/api/v4/leads/11001

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?id=11001 GET https://{enterprise}.cvtr.io/api/v4/leads?id[]=11001&id[]=11000

Changing the ordering of the collection to order the results by id descending.

GET https://{enterprise}.cvtr.io/api/v4/leads?order[id]=desc

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:

GET https://{enterprise}.cvtr.io/api/v4/campaigns

Example response:

{ "@context": "/api/v4/contexts/Campaign", "@id": "/api/v4/campaigns", "@type": "hydra:Collection", "hydra:member": [ { "@id": "/api/v4/campaigns/601", "@type": "Campaign", "status": "Active", "id": 601, "name": "Test Campaign", "startTs": "2021-08-31T23:00:00+00:00", "endTs": "2021-11-30T23:59:59+00:00", "exposePublisher": false, "exposePublisherSub": false, "updatedTs": "2021-09-01T09:55:06+00:00", "defaultThresholdScore": 70, "integrate": true, "callCentre": false, "welcomeEmail": false, "doubleOptin": false, "scoreBaseRouting": false, "defaultSaleValue": "0.01", "defaultSaleCurrency": "GBP", "advertiser": { "@id": "/api/v4/advertisers/319", "@type": "Advertiser", "id": 319, "name": "deployment 2021-09-01" }, "accountManager": null, "subcategory": { "@id": "/api/v4/subcategories/1", "@type": "Subcategory", "id": 1, "name": "Marketing" }, "country": null, "campaignMarket": "b2b", "contractValue": "1000.00", "performanceModel": "full", "internalOnly": false, "defaultPublisherRate": 55, "publisherPayoutType": "CPL", "manualScore": false, "combinedJobScore": 140, "useValueTransforms": true, "campaignManager": null, "pauseTs": null, "publisherTerms": null, "sendVoucher": false, "testMode": false, "sendMediakit": true, "conversionRate": "1.0000", "currency": { "@id": "/api/v4/currencies/1", "@type": "Currency", "id": 1, "name": "GBP", "symbol": "£", "base": true, "rateToBase": "1.0000" }, "baseCurrencyContractValue": "1000.00", "endTsExtension": 0, "unavailableCampaignLogic": "allow_leads", "unavailableCampaignRedirectUrl": null, "holdPublisherOverDelivery": false, "valueBasedRouting": false, "autoSignPublisher": false, "variablePublisherPayout": false, "useScheduledDelivery": false, "uncapped": false, "facebookOfflineEventSetId": null, "facebookSystemUserAccessToken": null, "leadProcessDelay": 0, "apiKey": "0c463164f0d4fcb604d8fd9f80737476", "leadsRequired": 100, "payoutAmount": "10.00", "payout": "CPL", "baseCurrencyPayoutAmount": "10.00", "notes": null, "signName": "Rokas Bartkevicius", "signRole": "super dev", "signTs": "2021-09-01T09:52:56+00:00", "signIoNumber": "7541", "terms": "", "statistics": { "totalLeads": 4, "invalidLeads": 1, "cautionLeads": 1, "validLeads": 3, "billableLeads": 3, "deliveredLeads": 3, "heldLeads": 0, "processingLeads": 0, "impressions": 0, "conversions": 2, "lastConversion": "2021-09-01T10:56:35+01:00", "clicks": 2, "activePublishers": 1, "totalSales": 0, "campaignRevenue": { "revenue": "30.00", "baseCurrencyRevenue": "30.00", "publisherPayout": "16.50", "baseCurrencyPublisherPayout": "16.50" }, "unsignedContracts": 0 }, "signHash": "6640a031859455338d516f3ec6019efc", "allowPublisherImportExport": true, "purchaseOrder": null, "referenceNumber": null, "purchaseOrderFile": null } ], "hydra:totalItems": 479, "hydra:view": { "@id": "/api/v4/campaigns?itemsPerPage=1&page=1", "@type": "hydra:PartialCollectionView", "hydra:first": "/api/v4/campaigns?itemsPerPage=1&page=1", "hydra:last": "/api/v4/campaigns?itemsPerPage=1&page=479", "hydra:next": "/api/v4/campaigns?itemsPerPage=1&page=2" }, "hydra:search": { "@type": "hydra:IriTemplate", "hydra:template": "/api/v4/campaigns{?id,id[],name,order[id],order[name],createdTs[before],createdTs[strictly_before],createdTs[after],createdTs[strictly_after],updatedTs[before],updatedTs[strictly_before],updatedTs[after],updatedTs[strictly_after],startTs[before],startTs[strictly_before],startTs[after],startTs[strictly_after],endTs[before],endTs[strictly_before],endTs[after],endTs[strictly_after],order[statistics.invalidLeads],order[statistics.validLeads],order[statistics.cautionLeads],order[statistics.heldLeads],order[statistics.processingLeads],order[statistics.billableLeads],order[statistics.impressions],order[statistics.conversions],order[statistics.clicks],status[],order[advertiser.name],order[startTs],order[endTs],order[country.id],order[country.iso],order[statistics.activePublishers],order[statistics.totalSales],order[statistics.campaignRevenue.revenue],order[statistics.campaignRevenue.baseCurrencyRevenue],idName,campaignProcessrJobs.processrJob.id,campaignProcessrJobs.processrJob.id[],campaignPublishers.publisher.id,campaignPublishers.publisher.id[],advertiser.id,advertiser.id[],advertiser.name,campaignManager,accountManager,country.id,country.id[],country.iso,country.iso[]}", "hydra:variableRepresentation": "BasicRepresentation", "hydra:mapping": [ { "@type": "IriTemplateMapping", "variable": "id", "property": "id", "required": false }, { "@type": "IriTemplateMapping", "variable": "id[]", "property": "id", "required": false }, { "@type": "IriTemplateMapping", "variable": "name", "property": "name", "required": false }, { "@type": "IriTemplateMapping", "variable": "order[id]", "property": "id", "required": false }, { "@type": "IriTemplateMapping", "variable": "order[name]", "property": "name", "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 }, { "@type": "IriTemplateMapping", "variable": "startTs[before]", "property": "startTs", "required": false }, { "@type": "IriTemplateMapping", "variable": "startTs[strictly_before]", "property": "startTs", "required": false }, { "@type": "IriTemplateMapping", "variable": "startTs[after]", "property": "startTs", "required": false }, { "@type": "IriTemplateMapping", "variable": "startTs[strictly_after]", "property": "startTs", "required": false }, { "@type": "IriTemplateMapping", "variable": "endTs[before]", "property": "endTs", "required": false }, { "@type": "IriTemplateMapping", "variable": "endTs[strictly_before]", "property": "endTs", "required": false }, { "@type": "IriTemplateMapping", "variable": "endTs[after]", "property": "endTs", "required": false }, { "@type": "IriTemplateMapping", "variable": "endTs[strictly_after]", "property": "endTs", "required": false }, { "@type": "IriTemplateMapping", "variable": "order[statistics.invalidLeads]", "property": "statistics.invalidLeads", "required": false }, { "@type": "IriTemplateMapping", "variable": "order[statistics.validLeads]", "property": "statistics.validLeads", "required": false }, { "@type": "IriTemplateMapping", "variable": "order[statistics.cautionLeads]", "property": "statistics.cautionLeads", "required": false }, { "@type": "IriTemplateMapping", "variable": "order[statistics.heldLeads]", "property": "statistics.heldLeads", "required": false }, { "@type": "IriTemplateMapping", "variable": "order[statistics.processingLeads]", "property": "statistics.processingLeads", "required": false }, { "@type": "IriTemplateMapping", "variable": "order[statistics.billableLeads]", "property": "statistics.billableLeads", "required": false }, { "@type": "IriTemplateMapping", "variable": "order[statistics.impressions]", "property": "query", "required": false }, { "@type": "IriTemplateMapping", "variable": "order[statistics.conversions]", "property": "statistics.conversions", "required": false }, { "@type": "IriTemplateMapping", "variable": "order[statistics.clicks]", "property": "statistics.clicks", "required": false }, { "@type": "IriTemplateMapping", "variable": "status[]", "property": "status", "required": false }, { "@type": "IriTemplateMapping", "variable": "order[advertiser.name]", "property": "advertiser.name", "required": false }, { "@type": "IriTemplateMapping", "variable": "order[startTs]", "property": "startTs", "required": false }, { "@type": "IriTemplateMapping", "variable": "order[endTs]", "property": "endTs", "required": false }, { "@type": "IriTemplateMapping", "variable": "order[country.id]", "property": "country.id", "required": false }, { "@type": "IriTemplateMapping", "variable": "order[country.iso]", "property": "country.iso", "required": false }, { "@type": "IriTemplateMapping", "variable": "order[statistics.activePublishers]", "property": "statistics.activePublishers", "required": false }, { "@type": "IriTemplateMapping", "variable": "order[statistics.totalSales]", "property": "statistics.totalSales", "required": false }, { "@type": "IriTemplateMapping", "variable": "order[statistics.campaignRevenue.revenue]", "property": "statistics.campaignRevenue.revenue", "required": false }, { "@type": "IriTemplateMapping", "variable": "order[statistics.campaignRevenue.baseCurrencyRevenue]", "property": "statistics.campaignRevenue.baseCurrencyRevenue", "required": false }, { "@type": "IriTemplateMapping", "variable": "idName", "property": "idName", "required": false }, { "@type": "IriTemplateMapping", "variable": "campaignProcessrJobs.processrJob.id", "property": "campaignProcessrJobs.processrJob.id", "required": false }, { "@type": "IriTemplateMapping", "variable": "campaignProcessrJobs.processrJob.id[]", "property": "campaignProcessrJobs.processrJob.id", "required": false }, { "@type": "IriTemplateMapping", "variable": "campaignPublishers.publisher.id", "property": "campaignPublishers.publisher.id", "required": false }, { "@type": "IriTemplateMapping", "variable": "campaignPublishers.publisher.id[]", "property": "campaignPublishers.publisher.id", "required": false }, { "@type": "IriTemplateMapping", "variable": "advertiser.id", "property": "advertiser.id", "required": false }, { "@type": "IriTemplateMapping", "variable": "advertiser.id[]", "property": "advertiser.id", "required": false }, { "@type": "IriTemplateMapping", "variable": "advertiser.name", "property": "advertiser.name", "required": false }, { "@type": "IriTemplateMapping", "variable": "campaignManager", "property": "campaignManager", "required": false }, { "@type": "IriTemplateMapping", "variable": "accountManager", "property": "accountManager", "required": false }, { "@type": "IriTemplateMapping", "variable": "country.id", "property": "country.id", "required": false }, { "@type": "IriTemplateMapping", "variable": "country.id[]", "property": "country.id", "required": false }, { "@type": "IriTemplateMapping", "variable": "country.iso", "property": "country.iso", "required": false }, { "@type": "IriTemplateMapping", "variable": "country.iso[]", "property": "country.iso", "required": false } ] } }

Related content