Hellodialog API (1.4.0)

Download OpenAPI specification:Download

This document describes the API of Hellodialog.

Call methods

Our API accepts POST, GET, PUT, DELETE requests. If you do not have the possibility to use the HTTP request methods you may also provide it as a request parameter method. A call would look like this GET https://app.hellodialog.com/api/contacts/58328?method=PUT

PHP API wrapper

We've created an API wrapper for our API that you can use to implement our API in your project. You can find the package here.

API Version history

Version	Release date	Changes
1.0.0	01-01-2011	Inital release
1.1.0	12-11-2019	Add external group endpoints
1.2.0	01-07-2020	Add unsubscribers endpoint
1.3.0	17-11-2020	Add resend optin endpoint
1.4.0	04-04-2022	Add contacts count to groups endpoint

Documentation version history

Version	Release date	Changes
1.0.0	27-10-2019	Inital release
1.0.1	07-11-2019	Small fixes
1.1.0	12-11-2019	Add external group documentation
1.2.0	15-01-2020	Add webhook documentation
1.3.0	06-07-2020	Add unsubscribers documentation
1.3.1	16-11-2020	Fixed date-format and missing description
1.4.0	17-11-2020	Add optin resend endpoint documentation
1.4.1	20-05-2021	Documentation text fixes
1.5.0	26-08-2021	Add _language to contact post
1.6.0	04-04-2022	Add contacts count to groups endpoint

Webhook for contacts that are updated

When a contact updates in Hellodialog we can send out a webhook call to a designated URL. In this call you will find the ID of the changed contact and an md5 of the API key + webhook secret.

To create a webhook you can add a URL to the API key you create in Hellodialog. This URL should be able to receive POST requests from the Hellodialog server. To verify the call is genuine you need to check the md5 from the call with the API key + webhook secret being used for the webhook URL. The POST data from the Hellodialog server looks like the following: id=2404&hash=7a6e1a0db07e621eee298fa1faa80090.

When the server verified the call is genuine you can then call Hellodialog with the ID and retrieve the new data of the contact and update it in your own app.

Authentication

ApiKeyAuth

Use ?token=<api_key> behind your call url as a parameter to authenticate with our API. You can generate your API key on this page.

Security Scheme Type	API Key
Query parameter name:	token

Contact operations

Operations on the contact endpoint

Create a contact

Create a contact to the database. You can add custom fields to this call too. Below are basic fields present in every account.

Authorizations:

ApiKeyAuth

Request Body schema: application/json

Contact to add to the database

email	string unique The email of the contact. This is a unique value.
voornaam	string The first name of the contact
achternaam	string The last name of the contact
geslacht	string Enum: "M" "F" Gender of the contact. Default values are M (male) or F (female)
groups	Array of numbers[ items ] Add a contact to Sending lists using the ID of the sending lists
_state	string Enum: "Optin" "Unsubscriber" "Bounced" "Contact" When no _state is given the default state is Opt-in and a mail will be sent to the contact when it's being posted to the API. `Optin` - Use this if you want to send an optin mail to this contact. When the contact clicks the link in the optin mail its state is changed to 'Contact' ('Opt-in' is the default value when the _state field is ommited) `Unsubscriber` - Use this to mark a contact as unsubscribed `Bounced` - Use this value to mark a contact as a bounced contact `Contact` - This is the value for a contact that you can use to send your mails to
_language	string Enum: "NL" "EN" "DE" "SE" You can add a language to a contact. When not providing `_language` we will pick the account language as the contact language. Adding a language to a contact will result in the opt-in mail send to that contact being in the set language. You can only select the predefined languages.

Responses

Request samples

Payload

Content type

application/json

{"email": "kevin@hellodialog.com",
"voornaam": "Kevin",
"achternaam": "Binder",
"geslacht": "M",
"groups": [1,
4
],
"_state": "Contact",
"_language": "NL"
}

Response samples

200

Content type

application/json

Example

{"result": {"status": "OK",
"message": "Contact created",
"code": "200",
"data": {"id": "3243",
"feedback": [ ]
}
}
}

Get contacts with parameters

Get contacts with paramenters in the URL. Using condition and values in the url with a deep object added to it will make it posible to search for multiple contacts. This enables you to search for a contact with an email address that ends with @domainname.com. The parameter will look like this &condition[email]=ends-with&values[email]=domainname.com. If you want to select all contacts with kevin as first name the parameter will look like this &condition[voornaam]=equals&values[voornaam]=kevin. When you want all the contacts from the database you can do something along the following lines &condition[voornaam]=not-equals&values[voornaam]=valuethatdoesnotexistinthedatabase. Don't forget to use pagination when you get all contacts from the database.

Authorizations:

ApiKeyAuth

query Parameters

condition[fieldname]	string Enum: "equals" "not-equals" "equals-any" "greater-than" "less-than" "contains" "not-contains" "starts-with" "ends-with" "before" "after" "contains-any" "contains-all" "contains-exactly" "not-contains-any" "not-contains-all" The value of condition is a search-condition.
values[fieldname]	string Example: values[fieldname]=domainname.com The value parameter is where you give your search condition
page	integer Example: page=1 Paginate the results with max 100 results per page

Responses

Response samples

200

Content type

application/json

Example

{"0": {"id": "2404",
"email": "dave@hellodialog.com",
"voornaam": "",
"last_open": "2019-10-21",
"achternaam": "",
"geboortedatum": "0000-00-00",
"geslacht": "",
"aangemaakt": "2019-02-25 10:39:49",
"aangepast": "2019-10-16 15:12:29",
"_state": "Contact",
"_language": null,
"groups": [ ]
},
"1": {"id": "2356",
"email": "dave+1@hellodialog.com",
"voornaam": "",
"last_open": null,
"achternaam": "",
"geboortedatum": null,
"geslacht": "",
"aangemaakt": "2019-09-24 17:09:31",
"aangepast": "2019-09-24 17:09:31",
"_state": "Contact",
"_language": null,
"groups": [ ]
},
"2": {"id": "2354",
"email": "dave+2@hellodialog.com",
"voornaam": "",
"last_open": null,
"achternaam": "",
"geboortedatum": null,
"geslacht": "",
"aangemaakt": "2019-09-24 17:08:53",
"aangepast": "2019-09-24 17:08:53",
"_state": "Contact",
"_language": null,
"groups": [26,
27,
29
]
}
}

Batch update contacts

Batch update contacts. Provide an object within an array with the contact ID per object attached to it. This wil update only the provided values

Authorizations:

ApiKeyAuth

Request Body schema: application/json

Array

id required	integer The ID of the contact
voornaam	string A field from the Hellodialog application
achternaam	string Another field from the Hellodialog application. You can add as many field to this as you want. You can also add custom fields.

Responses

Request samples

Payload

Content type

application/json

[{"id": 3452,
"voornaam": "Patrick",
"achternaam": "Star"
},
{"id": 3451,
"voornaam": "Sandy",
"achternaam": "Wang"
}
]

Response samples

200

Content type

application/json

{"result": {"status": "OK",
"message": "Contacts updated",
"code": 200,
"data": {"success_data": [{"firstname": "Patrick",
"lastname": "Star",
"id": 3452
},
{"firstname": "Sandy",
"lastname": "Wang",
"id": 3451
}
]
}
}
}

Get a single contact

Get all the data that is available of a contact

Authorizations:

ApiKeyAuth

path Parameters

contactId

required

string

pass a contact id to get the contact data

Responses

Response samples

200

Content type

application/json

Example

{"id": "1",
"email": "kevin@hellodialog.com",
"last_open": "2020-09-30",
"voornaam": "Kevin",
"achternaam": "Binder",
"geboortedatum": "2011-04-20",
"geslacht": "M",
"aangemaakt": "2019-02-25 10:39:49",
"aangepast": "2019-02-26 09:12:00",
"nps_score": null,
"_state": "Contact",
"_language": null,
"groups": [ ]
}

Update a single contact

Update a contact based on its ID. This wil update only the provided values

Authorizations:

ApiKeyAuth

path Parameters

contactId

required

string

pass a contact id to update the contact

Request Body schema: application/json

voornaam	string The first name of the contact
achternaam	string The last name of the contact
groups	Array of numbers[ items ] When updating a contact with a new Sending list you should first get the current Sending lists the contact is in. Then append the new Sending list ID en add the whole array to the call. When sending an empty array the contact is removed from all groups.

Responses

Request samples

Payload

Content type

application/json

{"voornaam": "Kevin",
"achternaam": "Binder",
"groups": [1,
4
]
}

Response samples

200

Content type

application/json

Example

{"result": {"status": "OK",
"message": "Contact updated",
"code": "200",
"data": {"id": "3243"
}
}
}

Delete a single contact

Delete a contact based on its ID in the database.

Authorizations:

ApiKeyAuth

path Parameters

contactId

required

string

pass a contact id to update the contact

Responses

Response samples

200

Content type

application/json

Example

{"result": {"status": "OK",
"message": "Contact deleted",
"code": "200",
"data": {"id": "3243"
}
}
}

Send a optin mail

Send a optin mail to a contact that has the state Optin, Unsubscribe or Transactional. When adding a contact with a state of Optin our application will automatically send an optin mail. If the optin mail is not accepted within 3 days another optin mail is send. After that you can use this endpoint to send another optin mail.

Authorizations:

ApiKeyAuth

path Parameters

contactId

required

string

pass a contact id to send the optin mail

Request Body schema: application/json

optin_language

string

The language you want the optin to be. Choose from NL, EN, DE or SE

Responses

Request samples

Payload

Content type

application/json

{"optin_language": "EN"
}

Response samples

200

Content type

application/json

Example

{"result": {"status": "OK",
"message": "The optin mail has been sent to the contact",
"code": "200",
"data": {"id": "103504"
}
}
}

Field operations

Operations on the field endpoint

Create a field

Create a single field to a account

Authorizations:

ApiKeyAuth

Request Body schema: application/json

name required	string
type	string Enum: "Text" "Dropdown" "Multiselect" "Date" "Integer" "Decimal" "Textarea" type values: `Text` - String values (default value when type is ommited) `Dropdown` - Use the `options` key with an array inside the `values` key to define the values of the dropdown `Multiselect` - Use the `options` key with an array inside the `values` key to define the values of the multiselect `Date` - Date values. Dates should be formated like `yyyy-mm-dd` `Integer` - You can use integers for creating dynamic segments of contacts in the app `Decimal` - You can use decimals for creating dynamic segments of contacts in the app `Textarea` - Use textarea for large strings and when you need a big input on the profile page of a contact
	object
user_viewable	boolean set this to true when you want to show this field on the contacts profile page
user_editable	boolean set this to true when you want a contact to be able to edit this fields data in the contacts profile page

Responses

Request samples

Payload

Content type

application/json

{"name": "Test",
"type": "Dropdown",
"options": {"values": ["Item 1",
"Item 2",
"Item 3"
]
},
"user_viewable": true,
"user_editable": true
}

Response samples

200

Content type

application/json

Example

{"result": {"status": "OK",
"message": "Field created",
"code": 200,
"data": {"id": 16,
"field": {"name": "Test23",
"type": "Dropdown",
"options": "{\"values\":[\"Item 1\",\"Item 2\",\"Item 3\"]}",
"user_viewable": "1",
"user_editable": "1",
"account_editable": "1"
}
}
}
}

Get all fields of account

Get all the fields that are available in an account

Authorizations:

ApiKeyAuth

Responses

Response samples

200

Content type

application/json

Example

{"1": {"id": "1",
"name": "Email",
"type": "Text",
"removable": "0",
"options": null,
"position": "0",
"show_in_overview": "1",
"user_viewable": "1",
"user_editable": "1",
"subscription_field_mandatory": "0",
"columns": ["email"
],
"system_name": "email"
},
"2": {"id": "2",
"name": "Laatst geopend",
"type": "Date",
"removable": "0",
"options": null,
"position": "1",
"show_in_overview": "0",
"user_viewable": "0",
"user_editable": "0",
"subscription_field_mandatory": "0",
"columns": ["laatst_geopend"
],
"system_name": "laatst_geopend"
},
"3": {"id": "3",
"name": "Voornaam",
"type": "Text",
"removable": "1",
"options": null,
"position": "1",
"show_in_overview": "1",
"user_viewable": "1",
"user_editable": "1",
"subscription_field_mandatory": "0",
"columns": ["voornaam"
],
"system_name": "voornaam"
},
"4": {"id": "4",
"name": "Achternaam",
"type": "Text",
"removable": "1",
"options": null,
"position": "2",
"show_in_overview": "1",
"user_viewable": "1",
"user_editable": "1",
"subscription_field_mandatory": "0",
"columns": ["achternaam"
],
"system_name": "achternaam"
},
"5": {"id": "5",
"name": "Geboortedatum",
"type": "Date",
"removable": "0",
"options": null,
"position": "3",
"show_in_overview": "1",
"user_viewable": "1",
"user_editable": "1",
"subscription_field_mandatory": "0",
"columns": ["geboortedatum"
],
"system_name": "geboortedatum"
},
"6": {"id": "6",
"name": "Geslacht",
"type": "Dropdown",
"removable": "0",
"options": {"values": ["M",
"F"
]
},
"position": "4",
"show_in_overview": "1",
"user_viewable": "1",
"user_editable": "1",
"subscription_field_mandatory": "0",
"columns": ["geslacht"
],
"system_name": "geslacht"
},
"7": {"id": "7",
"name": "Aangemaakt",
"type": "Created",
"removable": "0",
"options": null,
"position": "5",
"show_in_overview": "0",
"user_viewable": "0",
"user_editable": "0",
"subscription_field_mandatory": "0",
"columns": ["aangemaakt"
],
"system_name": "aangemaakt"
},
"8": {"id": "8",
"name": "Aangepast",
"type": "Modified",
"removable": "0",
"options": null,
"position": "6",
"show_in_overview": "0",
"user_viewable": "0",
"user_editable": "0",
"subscription_field_mandatory": "0",
"columns": ["aangepast"
],
"system_name": "aangepast"
},
"9": {"id": "9",
"name": "NPS Score",
"type": "Dropdown",
"removable": "0",
"options": {"values": ["0",
"1",
"2",
"3",
"4",
"5",
"6",
"7",
"8",
"9",
"10"
]
},
"position": "6",
"show_in_overview": "0",
"user_viewable": "0",
"user_editable": "0",
"subscription_field_mandatory": "0",
"columns": ["nps_score"
],
"system_name": "nps_score"
}
}

Get a single field of an account

Get a single field based on its ID

Authorizations:

ApiKeyAuth

path Parameters

fieldId

required

string

pass a field ID to get that specific field

Responses

Response samples

200

Content type

application/json

Example

{"1": {"id": "1",
"name": "Email",
"type": "Text",
"removable": "0",
"options": null,
"position": "0",
"show_in_overview": "1",
"user_viewable": "1",
"user_editable": "1",
"subscription_field_mandatory": "0",
"columns": ["email"
],
"system_name": "email"
}
}

Update a single field

Update a field with only the to update values

Authorizations:

ApiKeyAuth

path Parameters

fieldId

required

string

pass a field ID to get that specific field

Request Body schema: application/json

removable	boolean set this to true if you want users of the Hellodialog app to be able to delete a field and it's contents
user_viewable	boolean set this to true when you want to show this field on the contacts profile page
user_editable	boolean set this to true when you want a contact to be able to edit this fields data in the contacts profile page

Responses

Request samples

Payload

Content type

application/json

{"removable": true,
"user_viewable": true,
"user_editable": true
}

Response samples

200

Content type

application/json

Example

{"result": {"status": "OK",
"message": "Field updated",
"code": 200,
"data": {"field": {"id": "15",
"name": "Test",
"type": "Text",
"removable": "1",
"options": null,
"position": "13",
"show_in_overview": "0",
"user_viewable": "1",
"user_editable": "1",
"subscription_field_mandatory": "0"
}
}
}
}

Delete a field

Delete a field based on its ID in the database.

Authorizations:

ApiKeyAuth

path Parameters

fieldId

required

string

pass a field id to update the contact

Responses

Response samples

200

Content type

application/json

Example

{"result": {"status": "OK",
"message": "Field deleted",
"code": "200",
"data": {"id": "3243"
}
}
}

Groups operations

Operations on the groups endpoint

Create a group

Create a group in the database and get the ID as response

Authorizations:

ApiKeyAuth

Request Body schema: application/json

Contact to add to the database

name	string The internal name for the app. You will see this name inside the Hellodialog app
visible_name	string The name the contact will see on their profile page, unsubscribe page and on the subcribe form
is_private	boolean When set to true only contact that are in the Sending list will be able to see it on their profile page and when unsubscribing. When set to false every contact can see this sendinglist.
external_id	string Add a custom ID to your call if you want to use your own ID to get a group via the API. You can do this with the group/external/{external_id} endpoint.

Responses

Request samples

Payload

Content type

application/json

{"name": "Newsletter contacts",
"visible_name": "Newsletter",
"is_private": false,
"external_id": "201911121234"
}

Response samples

200

Content type

application/json

Example

{"result": {"status": "OK",
"message": "Group created",
"code": 200,
"data": {"id": 3
}
}
}

Get all groups

Get all groups from the database in an array

Authorizations:

ApiKeyAuth

Responses

Response samples

200

Content type

application/json

Example

[{"id": 1,
"name": "Newsletter contacts",
"visible_name": "Newsletter",
"is_private": false,
"subscription_group_checked": "0",
"description": "You receive this newsletter because you have subscribed to our newsletter in the past.",
"created_at": "2019-10-15 09:11:46",
"updated_at": "2019-10-15 09:11:46",
"contacts_count": 3
},
{"id": 2,
"name": "Sale newsletter contacts",
"visible_name": "Sale Newsletter",
"is_private": true,
"subscription_group_checked": "0",
"description": "You receive this newsletter because you have shown intrest in our sale newsletter in the past.",
"created_at": "2019-10-15 09:11:41",
"updated_at": "2019-10-15 09:11:41",
"contacts_count": 8
}
]

Get all groups with their external ID

Get all sending lists with their external group ID in the body.

Authorizations:

ApiKeyAuth

Responses

Response samples

200

Content type

application/json

[{"id": 1,
"name": "Newsletter contacts",
"visible_name": "Newsletter",
"is_private": false,
"subscription_group_checked": "0",
"description": "You receive this newsletter because you have subscribed to our newsletter in the past.",
"created_at": "2019-10-15 09:11:46",
"updated_at": "2019-10-15 09:11:46",
"external_id": "201911121234"
},
{"id": 2,
"name": "Sale newsletter contacts",
"visible_name": "Sale Newsletter",
"is_private": true,
"subscription_group_checked": "0",
"description": "You receive this newsletter because you have shown intrest in our sale newsletter in the past.",
"created_at": "2019-10-15 09:11:41",
"updated_at": "2019-10-15 09:11:41",
"external_id": "201911125678"
}
]

Get group with external ID

Get a sending list with their external ID.

Authorizations:

ApiKeyAuth

path Parameters

externalId

required

string

Pass a external group ID to get the Sending list

Responses

Response samples

200

Content type

application/json

[{"id": 1,
"name": "Newsletter contacts",
"visible_name": "Newsletter",
"is_private": false,
"subscription_group_checked": "0",
"description": "You receive this newsletter because you have subscribed to our newsletter in the past.",
"created_at": "2019-10-15 09:11:46",
"updated_at": "2019-10-15 09:11:46",
"external_id": "201911121234"
}
]

Get group with ID

Get the group with the external ID in its body when passing its internal ID

Authorizations:

ApiKeyAuth

path Parameters

groupId

required

string

Pass a the ID of a group to get the Sending list

Responses

Response samples

200

Content type

application/json

{"id": 1,
"name": "Newsletter contacts",
"visible_name": "Newsletter",
"is_private": false,
"subscription_group_checked": "0",
"description": "You receive this newsletter because you have subscribed to our newsletter in the past.",
"created_at": "2019-10-15 09:11:46",
"updated_at": "2019-10-15 09:11:46",
"external_id": "201911121234"
}

Get a single group

Get a single group from the database

Authorizations:

ApiKeyAuth

path Parameters

groupId

required

string

Pass a group ID to get the Sending list

Responses

Response samples

200

Content type

application/json

Example

{"id": 1,
"name": "Newsletter contacts",
"visible_name": "Newsletter",
"is_private": false,
"subscription_group_checked": "0",
"description": "You receive this newsletter because you have subscribed to our newsletter in the past.",
"created_at": "2019-10-15 09:11:46",
"updated_at": "2019-10-15 09:11:46",
"contacts_count": 6
}

Update group

Update a single Sending list in the database

Authorizations:

ApiKeyAuth

path Parameters

groupId

required

string

Pass a group ID to update the Sending list

Request Body schema: application/json

Contact to add to the database

name	string The internal name for the app. You will see this name inside the Hellodialog app
visible_name	string The name the contact will see on their profile page, unsubscribe page and on the subcribe form
is_private	boolean When set to true only contacts that are in the Sending list will be able to see it on their profile page and when unsubscribing. When set to false every contact can see this sendinglist.
external_id	string Add a custom ID to your call if you want to use your own ID to get a group via the API. You can do this with the group/external/{external_id} endpoint.

Responses

Request samples

Payload

Content type

application/json

{"name": "Newsletter contacts updated",
"visible_name": "Newsletter v2",
"is_private": true,
"external_id": "201911121234"
}

Response samples

200

Content type

application/json

Example

{"result": {"status": "OK",
"message": "Group updated",
"code": 200
}
}

Delete group

Delete a single Sending list in the database

Authorizations:

ApiKeyAuth

path Parameters

groupId

required

string

Pass a group ID to delete the Sending list

Responses

Response samples

200

Content type

application/json

Example

{"result": {"status": "OK",
"message": "Group deleted",
"code": 200,
"data": {"id": 1,
"group": {"id": 1,
"name": "Newsletters contacts",
"visible_name": "Newsletters",
"is_private": false,
"subscription_group_checked": "0",
"description": "You receive this newsletter because you have subscribed to our newsletter in the past.",
"created_at": "2019-10-15 09:46:39",
"updated_at": "2019-10-15 09:46:39"
},
"notices": [ ]
}
}
}

Lists operations

Operations on the list (segment) endpoint

Create a list

Create a list in the database

Authorizations:

ApiKeyAuth

Request Body schema: application/json

name required	string Internal name for the segment
description	string A description for the segment that you can see in the segment overview of the app
contacts required	Array of numbers[ items ] The contact ID's of the contacts you want to add to the static list

Responses

Request samples

Payload

Content type

application/json

{"name": "Test",
"description": "A simple description of the segment",
"contacts": [1,
3
]
}

Response samples

200

Content type

application/json

Example

{"result": {"status": "OK",
"message": "List created",
"code": 200,
"data": {"id": 10,
"notices": [ ]
}
}
}

Get all lists

Get all lists from the database as an object

Authorizations:

ApiKeyAuth

Responses

Response samples

200

Content type

application/json

Example

{"1": {"id": "1",
"name": "Testsegment",
"type": "static",
"date": "1564036867",
"count": "0"
},
"2": {"id": "2",
"name": "Alle e-mailadressen",
"type": "dynamic",
"date": "1564036867",
"count": "5"
}
}

Get a single list

Get a single list from the database with its contacts in it

Authorizations:

ApiKeyAuth

path Parameters

listId

required

string

Pass a list ID

Responses

Response samples

200

Content type

application/json

Example

{"id": "2",
"name": "Alle e-mailadressen",
"description": "",
"list": {"1": "kevin@hellodialog.com",
"2": "dave@hellodialog.com",
"3": "martijn@hellodialog.com",
"4": "bart@hellodialog.com"
}
}

Update single static list

Update a single static list from the database

Authorizations:

ApiKeyAuth

path Parameters

listId

required

string

Pass a list ID

Request Body schema: application/json

name required	string Internal name for the segment
description	string A description for the segment that you can see in the segment overview of the app
contacts required	Array of numbers[ items ] The contact ID's of the contacts you want to keep in the static list. If you pass an empty array your segment will be empty. So always GET the contents of the segment first and pass it with this call if you want to keep your segment populated.

Responses

Request samples

Payload

Content type

application/json

{"name": "Test",
"description": "A simple description of the segment",
"contacts": [1,
3
]
}

Response samples

200

Content type

application/json

Example

{"result": {"status": "OK",
"message": "List updated",
"code": 200
}
}

Delete list

Delete a single list in the database

Authorizations:

ApiKeyAuth

path Parameters

listId

required

string

Pass a list ID to delete the list

Responses

Response samples

200

Content type

application/json

Example

{"result": {"status": "OK",
"message": "List deleted",
"code": 200,
"data": {"id": 9,
"notices": [ ]
}
}
}

Get a list of campaigns send to this list

Get a list of campaigns that have been sent to this list with some basic statistics

Authorizations:

ApiKeyAuth

path Parameters

listId

required

string

Pass a list ID

Responses

Response samples

200

Content type

application/json

Example

{"id": "18",
"name": "Kevin segment",
"description": "List description",
"list": {"1": "kevin@hellodialog.com",
"516": "kevin@icloud.com",
"519": "kevin@gmail.com"
},
"campaigns": [{"id": "15492",
"type": "Regular",
"name": "Mijn nieuwe mailing",
"recipients": "3",
"udate": "1553091362",
"stats": {"sent": 3,
"bounces": 0,
"delivered": 3,
"soft-bounces": 0,
"hard-bounces": 0,
"unopened": 2,
"opened": 1,
"notclicked": 0,
"clicked": 1
}
},
{"id": "15216",
"type": "Regular",
"name": "Mijn nieuwe mailing",
"recipients": "3",
"udate": "1518770102",
"stats": {"sent": 3,
"bounces": 0,
"delivered": 3,
"soft-bounces": 0,
"hard-bounces": 0,
"unopened": 0,
"opened": 3,
"notclicked": 3,
"clicked": 0
}
},
{"id": "15357",
"type": "Smart",
"name": "Dave test",
"recipients": "0",
"udate": "0",
"stats": {"sent": 0,
"bounces": 0,
"delivered": 0,
"soft-bounces": 0,
"hard-bounces": 0,
"unopened": 0,
"opened": 0,
"notclicked": 0,
"clicked": 0
}
}
]
}

Login operations

Operations on the login endpoint

Create a login

Create a login link for the Hellodialog application

Authorizations:

ApiKeyAuth

Responses

Response samples

200

Content type

application/json

Example

{"result": {"status": "OK",
"message": "Token login URL generated",
"code": 200,
"data": {"url": "https://app.hellodialog.com/account/tokenlogin/******/*************************"
}
}
}

Newsletter operations

Operations on the newsletter endpoint

Create a new newsletter

Create a basic HTML newsletter

Authorizations:

ApiKeyAuth

query Parameters

page	integer Example: page=1 Paginate the results with max 15 results per page

Request Body schema: application/json

name	string
subject	string
html required	string

Responses

Request samples

Payload

Content type

application/json

{"name": "Newsletter API",
"subject": "My new newsletter subject",
"html": "<html>...</html>"
}

Response samples

200

Content type

application/json

Example

{"result": {"status": "OK",
"message": "Newsletter created",
"code": 200,
"data": {"id": 147
}
}
}

Get a list of all newsletters

Get a list of all newsletters and their data

Authorizations:

ApiKeyAuth

Responses

Response samples

200

Content type

application/json

Example

{"1": {"id": "1",
"folder_id": "1",
"name": "Nieuwsbrief",
"subject": "What is your approach?",
"type": "Newsletter",
"html": "...",
"draft": "...",
"plaintext": "",
"hide_preheader": "0",
"google_analytics": "0",
"ga_utm_settings": "",
"extra_tracking_params": "",
"created": "2019-07-25",
"format": "JSON",
"preview_file": "client-assets/49175291/previews/162_65a00e5edc6fab325c61746243ca12aa6f706e87",
"recipients": 0
},
"2": {"id": "2",
"folder_id": "1",
"name": "Welkomstmail",
"subject": "Welkom bij Hellodialog!",
"type": "Newsletter",
"html": "...",
"draft": null,
"plaintext": "",
"hide_preheader": "0",
"google_analytics": "0",
"ga_utm_settings": "",
"extra_tracking_params": "",
"created": "2019-07-25",
"format": "JSON",
"preview_file": "client-assets/49175291/previews/68_3852240119a364da1d957e8b4507a44af2666525",
"recipients": 0
},
"3": {"id": "3",
"folder_id": "1",
"name": "Update van ...",
"subject": "Newsletter subject",
"type": "Newsletter",
"html": "...",
"draft": null,
"plaintext": "",
"hide_preheader": "0",
"google_analytics": "0",
"ga_utm_settings": "",
"extra_tracking_params": "",
"created": "2019-07-25",
"format": "JSON",
"preview_file": "client-assets/49175291/previews/159_a88a80c1ff84c426900133d705161e0abff78858",
"recipients": 0
}
}

Get a newsletter

Get a single newsletter and its data

Authorizations:

ApiKeyAuth

path Parameters

newsletterId

required

string

Pass a newsletter ID

Responses

Response samples

200

Content type

application/json

Example

{"id": "3",
"folder_id": "1",
"name": "Update van ...",
"subject": "Newsletter subject",
"type": "Newsletter",
"html": "...",
"draft": null,
"plaintext": "",
"hide_preheader": "0",
"google_analytics": "0",
"ga_utm_settings": "",
"extra_tracking_params": "",
"created": "2019-07-25",
"format": "JSON",
"preview_file": "client-assets/49175291/previews/159_a88a80c1ff84c426900133d705161e0abff78858",
"recipients": 0
}

Update a newsletter

Update a single newsletter

Authorizations:

ApiKeyAuth

path Parameters

newsletterId

required

string

Pass a newsletter ID

Request Body schema: application/json

name	string
subject	string
html required	string

Responses

Request samples

Payload

Content type

application/json

{"name": "Updated name",
"subject": "Updated subject",
"html": "<html>...</html>"
}

Response samples

200

Content type

application/json

Example

{"result": {"status": "OK",
"message": "Newsletter updated",
"code": 200
}
}

Delete newsletter

Delete a single newsletter in the database

Authorizations:

ApiKeyAuth

path Parameters

newsletterId

required

string

Pass a newsletter ID to delete the list

Responses

Response samples

200

Content type

application/json

Example

{"result": {"status": "OK",
"message": "Newsletter deleted",
"code": 200,
"data": {"id": 14,
"notices": [ ]
}
}
}

Order operations

Operations on the order endpoint

Create an order with products

Create an order in the database with products in it. POST multiple orders at once by supplying the order object in an array.

Authorizations:

ApiKeyAuth

Request Body schema: application/json

contact required	integer The unique Hellodialog contact ID
order_number required	string unique The unique order ID of the order
created_on required	integer UNIX timestamp of when the order was placed
price required	number Total price of the order
payment_method	string The payment method of the order
payment_status	string Enum: "PAID" "ERROR" "REFUND" "CANCELLED" "PENDING" "DENIED" Payment status of the order. Update this accordingly with one of the following values
discount	number Total discount of the order
zip_code	string Postal code of the order
lat	number Latitude of the order address
lng	number Longitude of the order address
country	string Country code of the order (ISO 3166-1 alpha-2)
coupon	string Coupon that was used with the order
	Array of objects (The Custom Fields Schema) [ items ] An array of custom fields
	Array of objects (The Items Schema) [ items ] An array of product objects

Responses

Request samples

Payload

Content type

application/json

{"contact": 5101,
"order_number": "1928885",
"created_on": 1539285883,
"price": 49.99,
"payment_method": "PAYPAL",
"payment_status": "PAID",
"discount": 10.49,
"zip_code": "2011KC",
"lat": 52.386639,
"lng": 4.64302,
"country": "NL",
"coupon": "SALE90",
"custom_fields": [{"id": 1,
"value": "in stock"
}
],
"products": [{"product_code": "AKCU-29182",
"name": "Razer Keyboard",
"quantity": 1,
"price": 15.5,
"brand": "Razer",
"discount": 2.12,
"category": "Peripherals",
"subcategory": "Keyboards"
}
]
}

Response samples

200

Content type

application/json

Example

{"result": {"status": "OK",
"message": "Order created",
"code": 200,
"data": {"id": 2
}
}
}

Get order data with parameters

Use parameters to get an order

Authorizations:

ApiKeyAuth

query Parameters

count	integer returns the number of orders in the database
order_number	string Find the order by the order number provided

Responses

Response samples

200

Content type

application/json

Example

{"result": {"status": "OK",
"message": "Number of orders",
"code": 200,
"data": {"count": "2"
}
}
}

Update the status of orders

Update the order status of multiple orders in the database

Authorizations:

ApiKeyAuth

Request Body schema: application/json

Array

id required	integer
payment_status required	string Enum: "PAID" "ERROR" "REFUND" "CANCELLED" "PENDING" "DENIED" Payment status of the order. Update this accordingly with one of the following values

Responses

Request samples

Payload

Content type

application/json

[{"id": 1,
"payment_status": "CANCELLED"
},
{"id": 2,
"payment_status": "CANCELLED"
}
]

Response samples

200

Content type

application/json

Example

{"result": {"status": "OK",
"message": "Order payment status updated",
"code": 200,
"data": {"id": 1
}
}
}

Get an order

Get a single order with the order ID

Authorizations:

ApiKeyAuth

path Parameters

orderId

required

string

Pass a order ID

Responses

Response samples

200

Content type

application/json

Example

{"id": "1",
"contact": "1",
"order_number": "1928885",
"created_on": "1539285883",
"payment_method": "PAYPAL",
"payment_status": "PAID",
"price": "49.99",
"discount": "10.49",
"zip_code": "2011KC",
"lat": "52.386639",
"lng": "4.643020",
"country": "NL",
"coupon": "SALE90",
"imported_on": "1571216158",
"products": [{"id": "1",
"order": "1",
"product_code": "AKCU-29182",
"name": "Razer Keyboard",
"quantity": "1",
"price": "15.50",
"discount": "2.12",
"category": "Peripherals",
"subcategory": "Keyboards",
"brand": "Razer"
}
]
}

Update the status of a single order

Update the order status

Authorizations:

ApiKeyAuth

path Parameters

orderId

required

string

Pass a order ID

Request Body schema: application/json

payment_status

required

string

Enum: "PAID" "ERROR" "REFUND" "CANCELLED" "PENDING" "DENIED"

Payment status of the order. Update this accordingly with one of the following values

Responses

Request samples

Payload

Content type

application/json

{"payment_status": "REFUND"
}

Response samples

200

Content type

application/json

Example

{"result": {"status": "OK",
"message": "Order payment status updated",
"code": 200,
"data": {"id": 1
}
}
}

Delete an order

Delete the order from the database

Authorizations:

ApiKeyAuth

path Parameters

orderId

required

string

Pass a order ID

Responses

Response samples

200

Content type

application/json

Example

{"result": {"status": "OK",
"message": "Order deleted",
"code": 200,
"data": {"id": 1,
"notices": [ ]
}
}
}

Ping operations

Operations on the ping endpoint

Get account data

Get account data from the account linked to the API

Authorizations:

ApiKeyAuth

Responses

Response samples

200

Content type

application/json

{"account": "Hellodialog",
"account_id": "52128944",
"plan": "Professional",
"access": {"all": ["*"
]
},
"modules": ["PROFILE",
"STATS",
"SURVEY",
"TELLAFRIEND",
"REPLY",
"EXPORT",
"SOCIAL",
"API",
"AUTOMAILER",
"HEATMAP",
"TEMPLATEIMPORT",
"GANALYTICS",
"BRANDING",
"LISTSTATS",
"ABTESTING",
"TIMESCHEDULER",
"REACH",
"FEEDBACK",
"ENRICH",
"CAMPAIGNS"
]
}

NPS operations

Operations on the NPS endpoint

Get the avarage NPS score

Get the avarage NPS (Net Promoters Score) contacts gave. You can also add date parameters to the URL to get the NPS score of a given period. Add date_start and date_end as parameters to the URL with a date in the format 2021-02-03 (Y-m-d). That would give you a querystring like this: ?date_start=2020-12-01&date_end=2021-02-01 in the URL. The JSON returned is the same but with a NPS score calculated to the participants in that period.

Authorizations:

ApiKeyAuth

Responses

Response samples

200

Content type

application/json

Example

{"score": -33.33,
"participants": 3
}

Campaign operations

Operations on the campaign endpoint

Get all previous campaigns

Get an object of all previous campaigns

Authorizations:

ApiKeyAuth

Responses

Response samples

200

Content type

application/json

Example

{"246236": {"id": 246236,
"name": "Test mail 1",
"type": "Regular",
"subject": "Test",
"template": "Template design",
"list": "All email addresses",
"from_name": "Dave Hoeks",
"from_email": "dave@hellodialog.com",
"datetime": 1551365165,
"total": 3342,
"status": "Done"
},
"246253": {"id": 246253,
"name": "Test mail 2",
"type": "Regular",
"subject": "Test subject",
"template": "Newsletter design",
"list": "Test segment",
"from_name": "Kevin Binden",
"from_email": "kevin@hellodialog.com",
"datetime": 1551367084,
"total": 3,
"status": "Done"
}
}

Unsubscriber operations

Operations on the unsubscriber endpoint

Get unsubscribers with parameters

Get unsubscribers with paramenters in the URL. Using condition and values in the url with a deep object added to it will make it posible to search for multiple unsubscribers. Don't forget to use pagination when you get all unsubscribers from the database.

Authorizations:

ApiKeyAuth

query Parameters

condition[fieldname]	string Enum: "equals" "not-equals" "equals-any" "greater-than" "less-than" "contains" "not-contains" "starts-with" "ends-with" "before" "after" "contains-any" "contains-all" "contains-exactly" "not-contains-any" "not-contains-all" The value of condition is a search-condition.
value[fieldname]	integer Example: value[fieldname]=12 The value parameter is where you give your search condition
page	integer Example: page=1 Paginate the results with max 100 results per page

Responses

Response samples

200

Content type

application/json

Example

{"0": {"campaign_id"": "12",
"contact_id"": "35",
"datetime"": "1592818256",
"reason"": "notinteresting",
"reason_text"": "Custom reason for the unsubscribe"
}
}

Get a single unsubscriber

Get all the data that is available of an unsubscriber

Authorizations:

ApiKeyAuth

path Parameters

unsubscriberId

required

string

pass a unsubscriber id to get the unsubscriber data

Responses

Response samples

200

Content type

application/json

Example

{"0": {"campaign_id"": "12",
"contact_id"": "11",
"datetime"": "1592818256",
"reason"": "otherchannel",
"reason_text"": "Custom reason for the unsubscribe"
}
}

Statistics operations

Operations on the statistics endpoint

Get contact statistics data

Get statistics about number of contacts in the database

Authorizations:

ApiKeyAuth

Responses

Response samples

200

Content type

application/json

{"Transactional": "2",
"Optin": "21",
"Contact": "1075",
"Bounced": "303",
"Unsubscriber": "1"
}

Get campaign statistics data

Get statistics like opens, clicks or bouces about a campaign.

Authorizations:

ApiKeyAuth

path Parameters

campaignId

required

string

Pass a order ID

Responses

Response samples

200

Content type

application/json

Example

{"sent": 5,
"bounces": 0,
"delivered": 5,
"soft-bounces": 0,
"hard-bounces": 0,
"unopened": 0,
"opened": 5,
"notclicked": 5,
"clicked": 0
}

Transactional operations

Operations on the transacional endpoint

Send a transactional mail

Send a transactional mail to a single contact

Authorizations:

ApiKeyAuth

Request Body schema: application/json

to required	string The emailaddress you want to send the
required	object From email values
	object The email address used when the recipient replies to the email.
subject	string The subject of your email. The application uses the subject configured in your template when you leave this blank.
required	object Template object
	object Optionally specify an attachment. It's possible to add multiple attachments, by passing an array of attachment objects. Else an object is sufficient
tag required	string Keyword identifying all transactional email of the same type. This keyword is used to group reports and also finds its way into your logs.
force_sending	boolean Some transactional email must be sent regardless subscriber preferences in the application. This flag allows you to send order confirmations to recipients that previously unsubscribed from your file.

Responses

Request samples

Payload

Content type

application/json

{"to": "patrick@hellodialog.com",
"from": {"email": "kevin@hellodialog.com",
"name": "Kevin Binder"
},
"reply_to": {"email": "dave@hellodialog.com"
},
"subject": "Transactional test subject",
"template": {"id": 23,
"hide_sections": ["INTRODUCTION",
"PROMOTIONS"
],
"replaces": [{"find": "__sent__",
"replace": "Your order was sent"
},
{"find": "__received__",
"replace": "Your order was received"
}
]
},
"attachment": [{"name": "readme.txt",
"content": "TWFhbmRhZ21pZGRhZyAxMCBub3ZlbWJlciAyMDg3IDEzOjA0OjA4"
},
{"name": "readme2.txt",
"content": "QWxsIHlvdXIgYmFzZSBhcmUgYmVsb25nIHRvIHVz"
}
],
"tag": "test tag",
"force_sending": true
}

Response samples

200