Relenta API v3
The API is built on the principles of REST. The URLs are resource-oriented, so that they are easily guessable and was designed to be easy to explore and use.
The transmission of all API requests and responses need to be made over HTTPS (Hypertext Transfer Protocol over Secure Socket Layer - SSL).
The root API Endpoint base url for all requests using the v3 API is:
https://{account_name}.relenta.com/api/v3/
Example: https://mycompany.relenta.com/api/v3/
Accessing the Relenta API requires an API department key. Every request will require the submission of a department key in request header “X-Relenta-Department-Key”.
To obtain your Department API key, go to the account dashboard (click on Relenta logo in the top left corner) and choose the "API" tab.
You can configure your requests with standard HTTP parameters. Just add them to HTTP query string for any request:
GET contact.list.json?page=2&page_size=10
Or as part of HTTP request body for POST requests.
Response is sent in JSON format. Each response is a hash.
Name | Type | Comments |
id | integer | Contact ID |
full_name | string | Full name |
first_name | string | First name |
last_name | string | Last name |
dt_created | datetime | Contact object creation timestamp |
dt_modified | datetime | Timestamp of last update |
emails | string | |
title | string | |
company | string | |
comment | string | |
phone | string | |
url | string | |
fax | string | |
messenger | string | |
string | ||
string | ||
string | ||
text | string | |
address | string | |
do_no_mass_email | boolean | |
groups | string | |
tags | string | |
string | Custom fields |
Name | Type | Comments |
id | integer | Activity ID |
activity_type | string | Activity type |
label | string | |
calendar_id | string | |
all_day | boolean | |
dt_created | datetime | |
dt_modified | datetime | |
dt_start | datetime | |
dt_end | datetime | |
rrule | string | Recurrence rule https://tools.ietf.org/html/rfc2445 |
status | string | |
author | string | |
users | string | |
contacts | string | |
subject | string | |
body | string |
Name | Type | Comments |
id | integer | Custom field ID |
type | string | Field type: Number, Text, Date, Single choice, Multiple choice |
key | string | Escaped name |
label | string | Field name |
choices | array | Allowed values if applicable |
URL | Method | Comments |
contact.list.json | GET | Get a list of contacts |
contact.save.json | POST | Create or update a contact |
activity.list.json | GET | Get a list of activities |
activity.save.json | POST | Create or update an activity |
custom_field.list.json | GET | Get a list of custom fields |
/contact.list.json
The following parameters are supported when fetching a list of contacts:
Name | Type | Description |
page | int | Page number |
page_size | int | Page size |
curl -X GET -H "X-Relenta-Department-Key: 8e222f0167df75f78449921176c570ca" https://mycompany.relenta.com/api/v3/contact.list.json
{
"status": true,
"code": 200,
"data": [{
"id": "33103982",
"full_name": "James Bond",
"first_name": "James",
"last_name": "Bond",
"dt_created": "2016-01-05T12:03:32Z",
"dt_modified": "2016-01-05T14:03:33Z",
"emails": "james.bond@mi6.gov.uk",
"title": null,
"company": "British Secret Service",
"comment": null,
"phone": "",
"url": "",
"fax": "",
"messenger": "",
"twitter": "",
"linkedin": "",
"facebook": "",
"text": "",
"address": "",
"do_not_mass_email": false
}, {
"id": "33077973",
"full_name": "Dr. Evil",
"first_name": "Dr.",
"last_name": "Evil",
"dt_created": "2013-07-08T12:38:11Z",
"dt_modified": "2016-01-03T00:12:22Z",
"emails": "ceo@virtucon.biz",
"title": "CEO",
"company": "Virtucon",
"comment": "Claims that he's the Princess of Canada.",
"phone": "800-VIRTUCON7 (toll-free);703-123-4567 (Cell)",
"url": "virtucon.biz",
"fax": "",
"messenger": "drevil8387 (Skype)",
"twitter": "AbsoluteEvil",
"linkedin": "",
"facebook": "https://www.facebook.com/pages/Dr-Evil/351058975168 (personal)",
"text": "",
"address": "(Secret Lair)\nUnderground in the Nevada desert\r\nSomewhere outside Las Vegas",
"do_not_mass_email": false,
"groups": "Cold;Qualified;Beyond evil;Absolute evil",
"tags": "Good guys;New tag for evil guys;Very evil",
"Occupation": "Evil doctor and a nice guy",
"T-shirt_size": "XL",
"Featured_in": "The Spy Who Shagged Me;Austin Powers 4",
"Skills": "Startups and Entrepreneurship"
}]
}
/contact.create.json
/contact.save.json
To create or update a contact the body of POST needs to contain the data structure identical to that of contact list.
curl -X POST -H "X-Relenta-Department-Key: 8e222f0167df75f78449921176c570ca" https://mycompany.relenta.com/api/v3/contact.save.json --data @contact.json
contact.json - file that contains object data in json format
{
"status": true,
"code": 200,
"data": {
"id": 33104663
}
}
/activity.list.json
The following parameters are supported when fetching a list of contacts:
Name | Type | Description |
page | int | Page number |
page_size | int | Page size |
curl -X GET -H "X-Relenta-Department-Key: 8e222f0167df75f78449921176c570ca" https://mycompany.relenta.com/api/v3/activity.list.json
{
"status": true,
"code": 200,
"data": [{
"id": "33104113",
"activity_type": "default",
"label": "Lunch",
"calendar_id": "1",
"all_day": true,
"dt_created": "2016-01-09T15:05:29Z",
"dt_modified": "2016-01-21T16:21:42Z",
"dt_start": "2016-01-21T19:00:00Z",
"dt_end": "2016-01-21T19:00:00Z",
"rrule": "",
"status": "open",
"author": "Austin Powers <austin.powers@mi6.gov.uk>",
"users": "Austin Powers <austin.powers@mi6.gov.uk>",
"contacts": "Ivana Humpalot <ivana.humpalot@kgb.ru>;Mustafa <assassinmustafa@gmail.com>",
"subject": "Discuss placement subject",
"body": "Discuss placement body"
}, {
"id": "33104112",
"activity_type": "default",
"label": "Lunch",
"calendar_id": "1",
"all_day": true,
"dt_created": "2016-01-09T15:05:29Z",
"dt_modified": "2016-01-21T16:18:57Z",
"dt_start": "2016-01-21T19:00:00Z",
"dt_end": "2016-01-21T19:00:00Z",
"rrule": "",
"status": "open",
"author": "Austin Powers <austin.powers@mi6.gov.uk>",
"users": "Austin Powers <austin.powers@mi6.gov.uk>",
"contacts": "Ivana Humpalot <ivana.humpalot@kgb.ru>;Mustafa <assassinmustafa@gmail.com>",
"subject": "Discuss placement subject",
"body": "Discuss placement body"
}]
}
/activity.save.json
To create or update an activity the body of POST needs to contain the data structure identical to that of activity list.
curl -X POST -H "X-Relenta-Department-Key: 8e222f0167df75f78449921176c570ca" https://mycompany.relenta.com/api/v3/activity.save.json --data @activity.json
activity.json - file that contains object data in json format
{
"status": true,
"code": 200,
"data": {
"id": 2312789
}
}
/custom_field.list.json
No additional parameters needed or allowed.
curl -X GET -H "X-Relenta-Department-Key: 8e222f0167df75f78449921176c570ca" https://show.relenta.com/api/v3/custom_field.list.json
{
"status": true,
"code": 200,
"data": [{
"id": "33078803",
"type": "Text",
"key": "Occupation",
"label": "Occupation",
"default_value": ""
}, {
"id": "33078800",
"type": "Single choice",
"key": "T-shirt_size",
"label": "T-shirt size",
"default_value": "",
"choices": [
"S",
"M",
"L",
"XL",
"XXL"
]
}, {
"id": "33078801",
"type": "Multiple choice",
"key": "Featured_in",
"label": "Featured in",
"default_value": "",
"choices": [
"International Man of Mystery",
"The Spy Who Shagged Me",
"Goldmember",
"Austin Powers 4"
]
}, {
"id": "33101174",
"type": "Text",
"key": "Hours",
"label": "Hours",
"default_value": ""
}, {
"id": "33101635",
"type": "Text",
"key": "Skills",
"label": "Skills",
"default_value": ""
}, {
"id": "33102253",
"type": "Date",
"key": "DOB",
"label": "DOB",
"default_value": ""
}]
}
Responses return with one of the following standard HTTP status codes:
Code | Description |
200 | OK. Operation successful. |
400 | Bad Request. Тhe request is not properly formatted, doesn’t properly specify response format or contains improper parameters or data. |
401 | Forbidden. The department API key is missing or is incorrect. This includes cases when your account has reached its plan limits like the allowed number of contacts. |
404 | Resource Not Found. When an id was provided for a request but no resource exists for that object. |