Getting Started
- Danny Hannah
- Michael Konomanyi
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/campaigns.jsonld will show you a list of available campaigns. 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/campaigns/44001.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/Campaign",
"@id": "/api/v4/campaigns",
"@type": "hydra:Collection",
"hydra:member": [
{
"@id": "/api/v4/campaigns/44001",
"@type": "Campaign",
"id": 44001,
"name": "B2B Demo Q2 2017",
"startTs": "2016-04-01T00:00:00+00:00",
"endTs": "2017-11-30T23:59:59+00:00",
"statistics": {
"total_leads": "4",
"invalid_leads": "2",
"valid_leads": "2",
"billable_leads": "2"
}
},
{
"@id": "/api/v4/campaigns/44004",
"@type": "Campaign",
"id": 44004,
"name": "B2B Demo Q1 2018",
"startTs": "2017-01-01T00:00:00+00:00",
"endTs": "2018-12-31T23:59:59+00:00",
"statistics": {
"total_leads": "1116",
"invalid_leads": "437",
"valid_leads": "679",
"billable_leads": "673"
}
}
],
"hydra:totalItems": 2,
"hydra:view": {
"@id": "/api/v4/campaigns.jsonld?id%5B%5D=44001&id%5B%5D=44004&access_token=YmFkMGNiNWI0N2Q1YjQyY2M3YzI2YjY5MjkzNTAyZmI4Nzg0YjA5NWM5YzIyZjIzOWU0ODE2NDUwZGQ5NWRmNw",
"@type": "hydra:PartialCollectionView"
},
"hydra:search": {
"@type": "hydra:IriTemplate",
"hydra:template": "/api/v4/campaigns.jsonld{?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]}",
"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
}
...
]
}
}
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/campaigns.jsonld?access_token=***
Get more information for a specific object by id:
GET https://{enterprise}.cvtr.io/api/v4/campaigns/44001.jsonld?access_token=***
The following request will filter the collection by a single id, or the second example will filter by multiple campaign ids.
GET https://{enterprise}.cvtr.io/api/v4/campaigns.jsonld?id=44001&access_token=***
GET https://{enterprise}.cvtr.io/api/v4/campaigns.jsonld?id[]=44001&id[]=44000&access_token=***
Changing the ordering of the collection to order the results by id descending.
GET https://{enterprise}.cvtr.io/api/v4/campaigns.jsonld?order[id]=desc&access_token=***
You can, of course, combine both multiple ordering options and filters to make your request very specific.