I# Convertr Publisher API v2
## 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 unconfirmed and should be used merely as
an awareness tool whilst running campaigns on the Convertr platformwhile running a campaign with us.
## 2.0
This version of the API is accessible from the following url, at this point there is a single entry point for all requests.
```
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 assined 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 request must be sent with an authentication token.
This needs to be requested from the following url using a GET `GET` request. Once the token has been returned, it will expire after 60 minutes.
#### Request
...
```
GET
...
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
client_id
Response
Required
Description
Client ID | Required| Description
---------|--------|---------
`client_id`|Yes | Client ID which is supplied on a platform wide bases
`client_secret`|Yes| Client Secret which is supplied on a platform wide basis bases
`api_key`|Yes| API Key that is unique to each user
#### Response
```
{}
access_token:
...
"ODM5NTIwNjk1MjdhNTMzMzk0MTY2Y2ZkYjg2OWFlN2Y5YzZlNTk1NmUwZmVjOGRkMDhhMzllYTA ...
"ODM5NTIwNjk1MjdhNTMzMzk0MTY2Y2ZkYjg2OWFlN2Y5YzZlNTk1NmUwZmVjOGRkMDhhMzllYTA2ZTA0MDI3Zg"
expires_in:
...
3600
...
token_type:
...
"bearer"
...
scope: null
refresh_token:
...
"YTQzODk3MDdiM2FhMGYzODYyOTcyOTBkYWZiZWI3YzJmNmEwYmJkYWJiM2I0NzU1Y2Q5OTcwZDA 0YzhiZGNjYQ" "YTQzODk3MDdiM2FhMGYzODYyOTcyOTBkYWZiZWI3YzJmNmEwYmJkYWJiM2I0NzU1Y2Q5OTcwZDA0YzhiZGNjYQ"
}
```
### 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).
#### Request
```
GET
...
https://{enterprise}.cvtr.io/api/v2/publisher/fields/{CAMPAIGN_ID}?
...
...
```
Parameter
...
| Required
...
Description
...
CAMPAIGN_ID
...
Yes
...
| Description
---------|--------|---------
`CAMPAIGN_ID`| Yes | ID fo the campaign you are wishing to see a list of available forms
...
ACCESS_TOKEN ...
Yes
`ACCESS_TOKEN`| Yes| Access token acquired in 3.2
Response
Yes
Yes
Client Secret which is supplied on a platform wide bases
client_secret api_key
Yes
API Key that is unique to each user #### Response
```
[
{
"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[model][model]",
...
"form[model][model_title]",
...
"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.
#### Request
```
GET
...
https://{enterprise}.cvtr.io/api/v2/publisher/links/{CAMPAIGN_ID}?
...
...
```
Parameter
...
| Required
...
Description
...
CAMPAIGN_ID
...
Yes
...
| Description
---------|--------|---------
`CAMPAIGN_ID`| Yes | ID fo the campaign you are wishing to see a list of available links
...
ACCESS_TOKEN ...
Yes
`ACCESS_TOKEN`| Yes| Access token acquired in 3.2
#### Response
```
[
{
"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?
...
...
"id": 30,
"name":
...
"acme-campaign-display"
...
}
]
```
### 3.5 Campaign lead Endpoint
```
POST https://{enterprise}.cvtr.io/api/v2.1/publisher/{PUBLISHER_ID}/forms/{FORM_ID}/links/{LINK_ID
...
}/leads?access_token={ACCESS_TOKEN}
...
```
Parameter
...
| Required
...
Description
...
LINK_ID
...
Yes
| Description
---------|--------|---------
`PUBLISHER_ID`| Yes | Publisher id sending the request
`LINK_ID`| Yes | Link to associate lead with (see section 3.2 or Publisher Media Kit email)
...
`FORM_
...
ID`| Yes
...
| Form Id to match body to (see section 3.3 or Publisher Media Kit email)
...
ACCESS_TOKEN ...
Yes
`ACCESS_TOKEN`| Yes| Access token acquired in 3.2
#### Example Request Body
Response
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. ```
form%5BfirstName%5D=Danny&form%5BlastName%5D=Hannah&form%5Bemail%5D=
...
tech%40convertrmedia.net&form%5Bsubmit%5D=true
...
```
#### Response
```
{}
"data":
...
367086,
...
"message":
...
"Lead
...
was
...
created
...
successfully",
...
"status":
...
201
}
```
## 4.0 Error Responses
Errors will be returns with a status `code` and `message`. Where applicable additional information will be provided in an `errors` array.
Error Code| Error Body
Description
400
Invalid post data, check your request maps to the form fields in section 3.4
| Description
----------|------------|----------
400|`{"code":400,"message":"Validation
...
Failed","errors":{"errors":["This
...
form
...
should
...
not
...
contain
...
extra
...
fields."],"children":{"firstName
...
Your access token has
401
":[],"email":[],"lastName":[]}}}`| Invalid post data, check your request maps to the form fields in section 3.4
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
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
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"} You have not been added to this campaign by the campaign manager or you have yet to sign your contract. Also check your url parameters match the Pubisher Meida Kit email.