Authentication
Convertr uses OAuth for its API authentication. All end points (unless explicitly detailed) require an access_token to be passed through in a header with each request. Tokens expire after 60minutes and need to either be refreshed or a new one generated.
Beware that if your password is expired you will still receive an access token, but will receive the following error on any other API requests.
You can see the status password_expired property which is returned along with your access token - if it’s true then you will need to reset your password.
Requesting a token
Request:
POST /api/login HTTP/1.1
Host: {enterprise}.cvtr.io
Content-Type: application/x-www-form-urlencoded
username={your_email}&
password={your_password}
Response:
{
"access_token": "YjJmYmExOGRhNjk5MzlmNDU1ZmM3OGI2ZjEwMTkwMTA0YzU3YmY4MzU4MjI3Yjg1Y2VlZDlkYmY0ZmRiOTg4MA",
"expires_in": 3600,
"token_type": "bearer",
"scope": null,
"refresh_token": "ZDRiZWViZDQxOGZmMWE4MDE5ODRjODNlOGUxOWQyZDRkNmZiYzZkNzU3ZGI2NGI2MTEwYTAzZmU5YzIxZTQ2Ng",
"client_id": "4_50bb9wpfmj8cwgw8kk8s848ck8s0gkc8wok0wogockwcdd88o8",
"client_secret": "zfiacn1uttcsogc0w4wocowgkk0socsggkoo88k8sskskws8gc",
"user_id": 123,
"password_expired": false
}
Once you've requested an access token, you'll be able to start making calls to the API by passing the access token through as a Bearer token header:
curl --location --request GET 'https://{enterprise}.cvtr.io/api/v4/campaigns' \
--header 'Authorization: Bearer {access_token}'
In order for you to see additional context about the API end points, it's recommended that you use the .jsonld url extension. This will provide you additional information about the response, such as pagination, total records and next and previous urls.
Example expired password response:
{
"type": "https://tools.ietf.org/html/rfc2616#section-10",
"title": "An error occurred",
"detail": "Password expired"
}
Getting and Adding Contact Responses
Now you have an access token, you can start logging contact responses against leads.
To do this you will need the Convertr Lead ID.
To see a list of all the contacts you can call the following endpoint:
Request
GET /api/v4/lead-contact-histories
You can then filter this with the ?lead.id= property to see only contacts for a specific lead in Convertr.
Response:
{
"@context": "/api/v4/contexts/LeadContactHistory",
"@id": "/api/v4/lead-contact-histories",
"@type": "hydra:Collection",
"hydra:member": [
{
"@id": "/api/v4/lead-contact-histories/40",
"@type": "LeadContactHistory",
"id": 40,
"status": "Confirmed",
"note": "Contacted and confirmed details",
"createdBy": "/api/v4/users/157",
"createdTs": "2020-12-21T15:20:38+00:00",
"lead": {
"@id": "/api/v4/leads/27099",
"@type": "Lead",
...
}
},
...
To add a new contact attempt to a lead, you must POST to the endpoint:
POST /api/v4/lead-contact-histories
{
"status": "Unconfirmed",
"note": "This is a descriptive note of the contact",
"lead": "/api/v4/leads/{LEAD_ID}"
}
Property | Required | Description | Options |
|---|---|---|---|
|
| Contact status of the record | Can be either:
|
|
| Description of the contact status | |
|
| Linked Lead | Must be IRI string |
You can only add 5 contact status' per lead, you will receive a 400 message if you try and add more than than number:
{
"code": 400,
"message": "This lead has already been confirmed"
}