Publisher API (Global Forms)
Publisher API v2.4
- 1 Publisher API v2.4
- 1.1 1.0 Scope
- 1.2 2.0 Enterprise URL
- 1.3 3.0 Usage & Examples
- 1.3.1 3.1 Prerequisites
- 1.3.2 3.2 Authentication Token
- 1.3.3 3.3 Form Fields Endpoint
- 1.3.4 3.4 Campaign Links Endpoint
- 1.3.5 3.5 Campaign lead Endpoint
- 1.3.5.1 Example Request Body
- 1.3.5.2 Response
- 1.3.6 3.6 Get Lead Result
- 1.4 4.0 Error Responses
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 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 URL, at this point, there is a single entry point for all requests.
|
3.0 Usage & Examples
3.1 Prerequisites
All Publisher users by default have access to the Convertr Publisher API. Your access credentials are available from the Convertr Dashboard.
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 |
|
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 Multifactor 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.
Response
{
"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:
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 |
|
Parameter | Required | Description |
|---|---|---|
campaign_id | Yes | ID for the campaign you are wishing to see a list of available forms |
Response
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.
Request
GET |
|
Parameter | Required | Description |
|---|---|---|
campaign_id | Yes | ID for the campaign you are wishing to see a list of available links |
Response
3.5 Campaign lead Endpoint
POST |
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
|
Response
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 defined by the client. You can monitor the status of the lead being processed by performing the following request:
Request
GET |
|
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 | 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 |