...
Campaign Webhook
Scope
The campaign web-hook allows the user to post data to a Convertr campaign using a campaign API key to authenticate the request.
Setup Process
1. Go to ‘Setup’ under the ‘Admin’ tab on the Convertr campaign overview dashboard
...
2. Once you are on the setup page, scroll down to the ‘Campaign API’ section. 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 Request
| Code Block |
|---|
| language | js |
|---|
| title | GET request - Campaign Form Fields |
|---|
|
https://[enterprise].cvtr.io/webhook/campaign/[CampaignID]/global-form/fields?apikey=[campaignAPIkey] |
Example Form Fields Response
| Code Block |
|---|
| title | GET response - Campaign Form Fields |
|---|
|
[
{
"formName": "Form Fields Endpoint",
"formId": 75,
"fields": [
"form[firstName]",
"form[lastName]",
"form[email]",
"form[telephone]"
]
}
] |
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 Request
| Code Block |
|---|
| language | js |
|---|
| title | GET request - Campaign Links |
|---|
|
https://[enterprise].cvtr.io/webhook/campaign/[CampaignID]/links?apikey=[campaignAPIkey] |
Example Campaign Links Response
| Code Block |
|---|
| title | 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
| Code Block |
|---|
| language | js |
|---|
| title | POST request - Lead Data |
|---|
|
https://[enterprise].cvtr.io/webhook/campaign/[CampaignID]/global-form/[GlobalFormId]/leads?apikey=[campaignAPIkey]&campaignLinkId=[linkid] |
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).
| Code Block |
|---|
| language | js |
|---|
| title | POST request - Lead Data & Pub ID |
|---|
|
https://[enterprise].cvtr.io/webhook/campaign/[CampaignID]/form/[GlobalFormId]/leads?apikey=[campaignAPIkey]&campaignLinkId=[linkid]&publisherId=[publisherId] |
Example Lead Post Payload (unencoded)
| Code Block |
|---|
| language | js |
|---|
| title | POST request - Lead Data Payload |
|---|
|
form[firstName]=Joe&form[lastName]=Bloggs&form[email]=tech@convertr.io&form[telephone]=02036177659 |
Example Lead Post Response
| Code Block |
|---|
| title | POST response - Lead Data |
|---|
|
{
"code": 201,
"message": "Lead was created successfully",
"data": 55907
} |
Error Responses
| Error code | Error Body | Description |
|---|
| 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 |
...