Publisher API v2.3

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 request 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

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
}

You can also authenticate via OAuth2.0. This needs to be requested from the following URL using a GET request. Once the token has been returned, it will expire after 60 minutes.

Request

Response

{
    "access_token": "ODM5NTIwNjk1MjdhNTMzMzk0MTY2Y2ZkYjg2OWFlN2Y5YzZlNTk1NmUwZmVjOGRkMDhhMzllYTA2ZTA0MDI3Zg",
    "expires_in": 3600,
    "refresh_token": "YTQzODk3MDdiM2FhMGYzODYyOTcyOTBkYWZiZWI3YzJmNmEwYmJkYWJiM2I0NzU1Y2Q5OTcwZDA0YzhiZGNjYQ",
    "scope": null,
    "token_type": "bearer"
}

Additionally, a token can be requested using user credentials. In order to do that, you need to send a POST request to

Request

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

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.

Request

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

https://[enterprise].cvtr.io/api/v2.3/publisher/[publisher_id]/forms/[form_id]/leads?linkId=[link_id]&access_token={ACCESS_TOKEN}

Example Request Body

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:

3.6 Get Lead Result

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

Request

Responses

{
    "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"
    }
}

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.