Publisher API v2
| Table of Contents |
|---|
1.0 Scope
This document contains the technical information required for accessing the RESTful API offered by Convertr. Currently, the main goal of 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 while 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 after you have been assigned to a campaign, but are also available from the Convertr Dashboard.
...
In order for you to query the API, all request 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
...
| 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 | 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: "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` 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 | |
|---|---|
|
...
| |
https://{enterprise}.cvtr.io/api/v2/publisher/fields/{CAMPAIGN_ID}?access_token={ACCESS_TOKEN} |
Parameter | Required | Description | |
|---|---|---|---|
| 1 | CAMPAIGN_ID | Yes | ID 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 | ||
|---|---|---|
| ||
[ |
...
{ |
...
"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]" |
...
], |
...
"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 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 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
| Code Block | ||
|---|---|---|
| ||
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 returns 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 |
| 2 | 401 |
| Your access token has expired and you must request a new token, see section 3.2 |
| 3 | 403 |
| The requested campaign hasn't started yet. Enquire with your campaign manager as to when it will be available |
| 4 | 403 |
| The requested campaign has already been successfully fulfilled and no more leads are being accepted |