Versions Compared

Version Old Version 1 New Version Current
Changes made by

Adam Carter

Adam Carter

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Publisher API v2

Table of Contents

1.0 Scope

This document contains the technical information required for accessing the RESTful API provided offered by Convertr. Currently, the main goal of the Publisher this API is to feedback live stats to our network and facilitate the delivery of new customer records.

It should be noted that all reporting information gathered from the use of this API are is unconfirmed and should be used merely as an awareness tool whilst running campaigns on the Convertr platformwhile running a campaign with us.

2.0 Enterprise URL

This version of the API is accessible from the following urlURL, at this point there is a single entry point for all requests.

Code Block
https://{enterprise}.cvtr.io/api/v2/3.0 Usage & Examples

3.1 Prerequisites

All Publisher users by default have access to the Convertr Publisher API. Your access credentials are supplied with your campaign assets once after you have been assigned to a campaign, but are also available from the Convertr Dashboard. The Convertr Publisher API implements the OAuth2.0 authentication protocol.

3.2 Authentication Token

In order for you to query the API, all requests must be sent with an authentication token.

This needs to be requested from the following url URL using a GET request. Once the token has been returned, it will expire after 60 minutes.

GET Request

https://{enterprise}.cvtr.io/api/v2/

...

Code Block
https://{enterprise}.cvtr.io/oauth/v2/token?

...

grant_type=https://convertr.cvtr.io/grants/api_key&client_id=

...

{CLIENT_ID}&client_secret={CLIENT_SECRET}&api_key={API_KEY}

...

Parameter
Required
Description
1
client_id
Response 
Required 
Description 
...
Yes
Client ID which is supplied on a platform wide bases
2
client_secret
Yes
Client Secret which is supplied on a platform wide 
...
{ 
} 
bases
3
api_key
Yes
API Key that is unique to each user
Response
 Code Block
{
    access_token: 
...
"ODM5NTIwNjk1MjdhNTMzMzk0MTY2Y2ZkYjg2OWFlN2Y5YzZlNTk1NmUwZmVjOGRkMDhhMzllYTA 
2ZTA0MDI3Zg" 
"ODM5NTIwNjk1MjdhNTMzMzk0MTY2Y2ZkYjg2OWFlN2Y5YzZlNTk1NmUwZmVjOGRkMDhhMzllYTA2ZTA0MDI3Zg"
    expires_in: 3600
  
...
  token_type: "bearer"

...
    scope: null
...

    refresh_token: 
...
"YTQzODk3MDdiM2FhMGYzODYyOTcyOTBkYWZiZWI3YzJmNmEwYmJkYWJiM2I0NzU1Y2Q5OTcwZDA0YzhiZGNjYQ"
...


...
}
Additionally, a token can be requested using user credentials. In order to do that, you need to send a POST request to
 Code Block
https://{enterprise}.cvtr.io/oauth/v2/token
Parameter
Required
Description
1
client_id
Yes
Client ID which is supplied on a platform wide bases
2
client_secret
Yes
Client Secret which is supplied on a platform wide bases
3
api_key
Yes
API Key that is unique to each user
4
grant_type
Yes
Must be set to "password"
5
username
Yes
Your username
6
password
Yes
Your password

3.3 Form Fields Endpoint
This API call will supply an array of forms which are available to POST `POST` leads to (see section 3.5) on a given campaign. 
The response will allow you to see which form fields are available to populate per form (each campaign can have multiple forms).
GET Request
...
 Code Block
languagejson
https://{enterprise}.cvtr.io/api/v2/publisher/fields/{CAMPAIGN_ID}?
...
access_token={ACCESS_TOKEN}
...
Parameter
Required
Description
1
CAMPAIGN_ID
Yes
ID 
 of 
for the campaign you are wishing to see a list of available forms
2
ACCESS_TOKEN
 
Yes
Access token acquired in 3.2
Response
...
 Code Block
Yes 
Client Secret which is supplied on a platform wide bases 
client_secret 
api_key 
Yes 
API Key that is unique to each user 
[ 
{ 
languagejson
[{
	"fields": [
...
}, 
], 
"form[firstName]", 
...
"form[email]", 
...
"form[lastName]", 
...
"form[submit]"],

...
	"formId": 35,

...
	"formName": "Acme Campaign - Simple Form"
}, 
...
{
...

	"fields": [
...
"form[promotion]", 
...
"form[title]", 
...
"form[firstName]", 
...
"form[lastName]", 
...
"form[email]", 
...
"form[lookup][addressLine1]", 
...
"form[lookup][addressLine2]", 
...
"form[lookup][addressLine3]", 
...
"form[lookup][addressLine4]", 
...
"form[lookup][postcode]", 
...
"form[telephone][countryCode]", 
...
"form[telephone][telephone]", 
...
"form[submit
...
]
...
"
...
]
...
"form[dealerLookup][dealerLookupPostcode]", 
"form[dealerLookup][brandId]", 
"form[dealerLookup][marketId]", 
"form[dealerLookup][radius]", 
"form[dealerLookup][sincom]", 
"form[dealerLookup][siteCode]", 
"form[dealerLookup][dealerAddress]", 
"form[dealerLookup][dealerMarket]", 
"form[dealerLookup][dealerCity]", 
"form[dealerLookup][dealerProvince]", 
"form[dealerLookup][dealerEmail]", 
"form[dealerLookup][dealerZipCode]", 
"form[dealerLookup][dealerName]", 
"form[dealerLookup][dealer]", 
"form[IsPrivacyConsentGiven]", 
"form[IsPrivacyConsentGiven]", 
"form[IsThirdPartyConsentGiven]", 
"form[IsThirdPartyConsentGiven]", 
"form[IsProfilationConsentGiven]", 
"form[IsProfilationConsentGiven]" 
], 
...
,
	"formId": 23,

...
	"formName": "Acme Campaign - Advanced Form"

...
}
...
]
3.4 Campaign Links Endpoint
This API method will return an array of available links for the given campaign. Links are required as they it provides insight into which channel a lead entered the Convertr Platform or was captured.
GET Request
 Code Block
...
https://{enterprise}.cvtr.io/api/v2/publisher/links/{CAMPAIGN_ID}?
...
access_token={ACCESS_TOKEN}
...
Parameter
Required
Description
1
CAMPAIGN_ID
Yes
ID 
 of 
for the campaign you are wishing to see a list of available links
2
ACCESS_TOKEN
 
Yes
Access token acquired in 3.2
Response
 Code Block
[
...
{
...

	"channel": "Email",

...
	"destination": "https://convertrforms.cvtr.io/acme-campaign-email",

...
	"id": 25,
...
}, 

	"name": "acme-campaign-email"
}, 
...
{
...

	"channel": "Social",

...
	"destination": "https://convertrforms.cvtr.io/acme-campaign-social",

...
}, 
	"id": 26,
...

	"name": "acme-campaign-social"

...
{ 
}, {
	"channel": "Display",

...
	"destination": "https://convertrforms.cvtr.io/acme-campaign-display?
...
template=1&wp=4",

...
	"id": 30,
...

	"name": "acme-campaign-display"

...
}
...
]
3.5 Campaign 
...
Lead Endpoint
POST REQUEST
 Code Block
https://{enterprise}.cvtr.io/api/v2.1/publisher/{PUBLISHER_ID}/forms/{FORM_ID}/links/{LINK_ID
...
}/leads?access_token={ACCESS_TOKEN}
...
Parameter
Required
Description
1
PUBLISHER_ID
Yes
Publisher id sending the request
2
LINK_ID
Yes
Link to associate lead with (see section 3.2 or Publisher Media Kit email)
3
FORM_ID
Yes
Form Id to match body to (see section 3.3 or Publisher Media Kit email)
4
ACCESS_TOKEN
 
Yes
Access token acquired in 3.2
Example Request Body
Response 
4.0 Error Responses 
...
 Code Block
languagehtml
form%5BfirstName%5D=Danny&form%5BlastName%5D=Hannah&form%5Bemail%5D=
...
tech%40convertrmedia.net&form%5Bsubmit%5D=true
...
...
Response
...
 Code Block
{
	"data": 367086,

...
	"message": "Lead was created successfully",

...
	"status": 201
}
4.0 Error Responses
Errors will be returned with a status `code` and `message`. Where applicable additional information will be provided in an `errors` array.
Error Code
Error Body
Description
1
400
Invalid post data, check your request maps to the form fields in section 3.4 
{"code":400,"message":"Validation 
...
 Failed","errors":{"errors":["This 
...
 form 
...
 should 
...
 not 
...
 contain 
...
 extra 
...
 fields."],"children":{"firstName":[],"
...
email":[],"lastName":[]}}}
Invalid post data, check your request maps to the form fields in section 3.4
2
401
{"error":"invalid_grant","error_description":"The 
...
 access 
...
 token 
...
 provided 
...
 has 
...
 expired."}
...
Your access token has expired and you must request a new token, see section 3.2
3
403
{"code":403,"message":"Campaign 
...
 has 
...
 not 
...
 started 
...
 yet"}
...
The requested campaign hasn't started yet. Enquire with your campaign manager as to when it will be available
4
403
{"code":403,"message":"Campaign 
...
 is 
...
 fulfilled"}
...
The requested campaign has already been successfully fulfilled and no more leads are being accepted
...
403 
{"code":403,"message":"You do not have permissions to access this campaign"} 
...