Convertr Help Centre Help Center home page
Submit a request
Sign in
  1. Convertr Help Centre
  2. Other

Sending leads to the Convertr Platform (Publisher API) - Global Forms Follow

Alice Jaeb
  • October 08, 2021 22:40
  • Updated
Using Convertr APIs? Subscribe here to receive email notifications for development changes that may impact your implementation.

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.

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.

In this document we will cover:

  • 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

 

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:

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

 

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  Screen_Shot_2021-10-07_at_4.23.58_PM.png  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.

Screen_Shot_2021-10-07_at_4.24.10_PM.png

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.

Request

POST:https://{enterprise}.cvtr.io/api/login
Parameter Required Description
Username Yes Your username
password Yes Your password
mfa_token No MFA token supplied if MFA is enabled on your account.
mfa_code No Your MFA SMS code if MFA is enabled on your account.

Example Post:

POST:https://{enterprise}.cvtr.io/api/login
username: {USERNAME}
password: {USER_PASSWORD}

curl -X POST \
https://{enterprise}.cvtr.io/api/login \
-d 'username={USERNAME}&password={PASSWORD}'

If Multi Factor Authentication (MFA) is active on your account, you will receive the mfa_token and mfa_code by making the above request with only the required parameters. This will return the below response, with the mfa_code sent via SMS to the number listed on the user account:

Response

{
"error": "Mfa Required",
"error_description": "Multifactor authentication required",
"mfa_token": "MmE3Mzk0ODk0ODU4OWQ0MTAxNDBmNGE0YzExZDdlYjYzMzhhZDFlM2MzNDBiNjU4NzFlZTM1MzcxNTZkZThhNw"
}

You can then use these parameters to make a second complete request and retrieve the token.

{
"access_token": "MDU1OGViMzJhNmNiYWVhODdjZjA3M2EwNTQ1NDQ5ZjQ0YTJhNDQxMzNhZTcyNWIxNDJjMjJjZmM5YjhhNmU0Mw",
"expires_in": 3600,
"token_type": "bearer",
"scope": null,
"refresh_token": "N2QwYWZlOTliYThmZmQwNDRhNDcyMGQwZGU0ZjlhODlkMGI4OGQwODIzYjNlMDUzYWMxY2RlZWI0MmVlZTMwNw",
"client_id": "xxxxxxxxxxxxxxxxxxxxxx",
"client_secret": "xxxxxxxxxxxxxxxx",
"user_id": 167,
"password_expired": false,
"expires_ts": 1621853938
}

For all subsequent requests you must pass through the access token as a bearer token in the Authorization header. For example:

curl --location --request GET 'https://{enterprise}.cvtr.io/api/v2.4/publisher/fields/{publisher_id}' \
--header 'Authorization: Bearer {access_token}'

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).

Request

GET: /api/v2.4/publisher/fields/{campaign_id}
 Parameter  Required  Description
 campaign_id  Yes  ID for the campaign you are  wishing to see a list of  available forms

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.

Request

GET:/api/v2.4/publisher/links/{campaign_id}
 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: /api/v2.4/publisher/{publisher_id}/forms/{form_id}/campaign/{campaign_id}/leads?linkId={link_id}
 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)

 

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
}

When passing leads through the API, the form data must be passed in the body of the request. In addition, in the header you need to pass the following to encode the data:

  Name   Value
 Content-Type  x-www-form-urlencoded

 

3.6 Get Lead Result

After leads are saved to Convertr, they are queued and processed through the campaign's rules as defined by the client. You can monitor the status of the lead being processed by performing the following request:

Request

GET: /api/v2.1/publisher/{publisher_id}/lead-result/{lead_id}

Responses

Scenario  Response code  Response Body Detail
 Valid   200  ""

 If the lead is deemed valid by Convertr we will return a 200 response with no body.

 Pending   202  "The lead has not been processed yet. Please try again later."

If the lead is still being processed or is waiting in the queue to be processed a 202 response code will be returned. You can retry again shortly.

 Invalid  200
{

"qaReasons": "",

"failedJobs": [

"2017-02-15 17:05:56 - Value Transforms Failed. No values found for field - industry (industry)",

"2017-02-15 17:05:58 - The lead was submitted for Social Enrichment but no data was found in the past 24 hours.",

"2017-02-15 17:05:58 - No whitepaper downloads found for this company name."

],

"leadData": {

"title": "",

"firstName": "Sarah",

"lastName": "Simpson",

"postcode": "",

"addressLine1": "",

"addressLine2": "",

"addressLine3": "",

"email": "sarah.simpson@yahoo.co.uk",

"telephone": "",

"job_title": "Project Manager",

"industry": "Automotive & Transportation.",

"company_size": "101 to 500",

"linkedinUserId": "",

"companyCountryLookup": "",

"duns": "",

"companyCountryCode": "",

"companyName": "Anderson, Robertson and Murphy",

"companyAddressLine1": "544 Miller Parkway",

"companyAddressLine2": "Gordon Brooks",

"companyCity": "Evansfort",

"companyCountry": "United Kingdom",

"companyPostcode": "P2 4RI",

"companyPhone": "05675 69507",

"companyUrl": "http://anderson.com/totam-dolor-sint-rerum-veniam-iusto-excepturi-placeat",

"whitepaperId": "11",

"whitepaperName": "The Engineering feat of the Helicarrier",

"campaignWhitepaperRef": "8",

"whitepaperLocale": "1",

"emailDomain": "@yahoo.co.uk"

}

}

If the lead is invalid and belongs to a B2B campaign then you'll receive a response detailing the reasons it was invalidated, along with the associated data submitted.

 

 

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  {"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
 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
 404  {"code": 404,"message": "Not Found"}  The incorrect Publisher ID/Form ID/Campaign ID has been entered
 404  {"code": 404,"message": "Campaign Link not found"}  The incorrect campaign link id has been submitted

Articles in this section

  • Global Search Bar
  • Fair Usage Policy
  • Status on Apache Log4j Vulnerability
  • The Advertiser Report User
  • Sending leads to the Convertr Platform (Publisher API) - Global Forms
  • How to POST Leads to the Convertr Platform (Campaign webhook) - Global Forms
  • Publisher Lead Import Authorisation
  • Publisher Overdelivery: Overview
  • Monthly Publisher Cap
  • Adding a Video to a White Paper's 'Thank you' Page
See more

Related articles

  • How to POST Leads to the Convertr Platform (Campaign webhook) - Global Forms
  • Publisher API and Campaign Webhook API FAQs - Global Forms
  • Convertr Connect: Integration
  • Value Transforms: Regex Find and Replace
  • Convertr Connect: Retrieving Your API Key
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request
Return to top

Related articles

  • How to POST Leads to the Convertr Platform (Campaign webhook) - Global Forms
  • Publisher API and Campaign Webhook API FAQs - Global Forms
  • Convertr Connect: Integration
  • Value Transforms: Regex Find and Replace
  • Convertr Connect: Retrieving Your API Key