POST leads to the Convertr Platform - Campaign Webhook Follow

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

 

---

 

Overview

The Campaign webhook allows users to post data to a Convertr campaign using a campaign API key to authenticate the request.

This endpoint also allows for cross-origin requests allowing client-side applications to POST data to Convertr.

 

Retrieving your Campaign API Key

1. Within a campaign, navigate to Admin > Setup > Advanced

This is where you will see the Campaign API Key. This will present a code that will function as the access token for the duration of the campaign you have selected.

 

Using the Campaign API Key

Form Fields Endpoint

This API call will supply an array of forms along with the form fields on the campaign.

Example Form Fields GET Request:

https://{enterprise}.cvtr.io/webhook/campaign/v2/{campaign_id}/global-form/fields?apikey={campaign_api_key}

Example Form Fields GET Response:

[
{
"formName": "Form Fields Endpoint",
"formId": 75,
"fields": [
{
"key": "form[firstName]",
"hidden": false,
"required": false
},
{
"key": "form[lastName]",
"hidden": false,
"required": false
},
{
"key": "form[hidden]",
"hidden": true,
"required": true
}
]
}
]

Campaign Links Endpoint

This API call will return an array of available links for the given campaign. The Link ID is optional but it does provide insight into which channel a lead entered the Convertr Platform.

Example Campaign Links GET Request:

https://{enterprise}.cvtr.io/webhook/campaign/{campaign_id}/links?apikey={campaign_api_key}

Example Campaign Links GET Response:

GET response - Campaign Links
[
{
"id": 135,
"name": "Campaign Links Endpoint",
"channel": "Email",
"destination": "https://Campaign-Links-Endpoint.cvtr.io/lp/Campaign-Links-Endpoint"
}
]

Campaign Lead Post Endpoint

The API call will allow you to post leads to the given campaign.

Example Lead Post Request

https://{enterprise}.cvtr.io/webhook/campaign/{campaign_id}/global-form/{global_form_id}/leads?apikey={campaign_api_key}&campaignLinkId={link_id}

Example Lead Post Request with Publisher ID

Additionally, if you would like to pass the publisher id with the lead you can post as below (the publisher ID can be obtained from the platform by going to the publisher section:

 https://[enterprise].cvtr.io/publisher/list).

POST request - Lead Data & Pub ID

https://{enterprise}.cvtr.io/webhook/campaign/{campaign_id}/global-form/{global_form_id}/leads?apikey={campaign_api_key}&campaignLinkId={link_id}&publisherId={publisher_id}

Example Lead Post Payload (Unencoded)

POST request - Lead Data Payload

form[firstName]=Joe&form[lastName]=Bloggs&form[email]=tech@convertr.io&form[telephone]=02036177659

Example Lead Post Response

POST response - Lead Data
{
"code": 201,
"message": "Lead was created successfully",
"data": 55907
}

 

Error Responses

Error Body
500	{"code": 500, "message": ""}	Internal server error.
404	The server returned a "404 Not Found"	Campaign ID incorrect, incorrect URL or Global Form ID does not exist
404	{"code": 404,"message": "Publisher not found"}	Publisher ID incorrect
400	{"code": 400,"message": "Validation failed","data": [{"message": "This form should not contain extra fields."},{"fieldName": "form[field name]","message": ""}]}	The form field(s) submitted is/are incorrect and do not match the correct form mapping
400	{"code": 400,"message": "Validation failed","data": [{"message": "This form should not contain extra fields."}]}	Some form field(s) submitted in your request do not exist on the form
401	{"code": 401,"message": "Access denied."}	Access denied. Incorrect API key
403	{"code": "403","error": "Campaign is inactive"}	Campaign is inactive