Sending leads to the Convertr Platform (Publisher API) - V3.0 Follow

Using Convertr APIs? Subscribe here to receive email notifications for development changes that may impact your implementation.

 

---

 

1.0 Overview

This article contains all the technical information you'll need to access the Convertr REST API. The goal of this API is to feedback live stats to our network and facilitate the delivery of new customer records.

Documentation about API Rate Limits can be found here: Convertr API Rate Limits

Please note: All reporting information gathered from the use of this API are unconfirmed and should be used as an awareness tool while running a campaign with us.

Contents:

• 2.0 Enterprise URL
• 3.0 Usage & Examples
  • • 3.1 Prerequisites
    • 3.2 Authentication Token
      • • Request
        • Response
    • 3.3 Form Fields Endpoint
      • • Request
        • Response
    • 3.4 Campaign Links Endpoint
      • • Request
        • Response
    • 3.5 Campaign Lead Endpoint
      • • Example Request Body
        • Response
    • 3.6 Get Lead Result
      • • Request
        • Responses
• 4.0 Error Responses

Related documents:

• POST Leads To The Convertr Platform (Campaign Webhook)
• Convertr API Rate Limits

2.0 Enterprise URL

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

 

3.0 Usage & Examples

3.1 Prerequisites

All Publisher users have access to the Convertr Publisher API by default.

These can be found by logging into the Convertr Platform and selecting View next to your Publisher Name, selecting the Tracking Icon  under the Actions column, and selecting the API Credentials Tab. This will bring up the Tracking Modal which contains all the information you will need to set up your API.

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 using a POST request. Once the token has been returned, it will expire after 60 minutes.

GET Request

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
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 bases
api_key	Yes	API Key that is unique to each user

 

Response

{
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

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

Parameter	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 bases
api_key	Yes	API Key that is unique to each user
api_key	Yes	API Key that is unique to each user
grant_type	Yes	Must be set to "password"
username	Yes	Your username
password	Yes	Your password

 

3.3 Form Fields Endpoint

This API call will supply an array of forms that 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 each form (each campaign can have multiple forms).

GET Request

https://{enterprise}.cvtr.io/api/v2/publisher/fields/{CAMPAIGN_ID}?access_token={access_token}

Parameter	Required	Description
campaign_id	Yes	ID for the campaign you are wishing to see a list of available forms
access_token	Yes	Access token acquired in 3.2

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]"],
"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 from.

 

GET Request

https://{enterprise}.cvtr.io/api/v2/publisher/links/{CAMPAIGN_ID}?access_token={ACCESS_TOKEN}

Parameter	Required	Description
CAMPAIGN_ID	Yes	ID for the campaign you are wishing to see a list of available links

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?template=1&wp=4",
"id": 30,
"name": "acme-campaign-display"
}]

 

3.5 Campaign Lead Endpoint

POST Request

https://{enterprise}.cvtr.io/api/v2.1/publisher/{PUBLISHER_ID}/forms/{FORM_ID}/links/{LINK_ID}/leads?access_token={ACCESS_TOKEN}

Parameter	Required	Description
PUBLISHER_ID	Yes	Publisher id sending the request
LINK_ID	No	Link to associated 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 acquired in 3.2

 

Example Request Body

form%5BfirstName%5D=Danny&form%5BlastName%5D=Hannah&form%5Bemail%5D=tech%40convertr.io&form%5Bsubmit%5D=true

Response

{
"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
400	{"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
401	{"error": "invalid_grant","error_description": "The access token provided is invalid."}	Your access token is incorrect 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