Invites
Get a list of invites
This method retrieves the list of review invites by channel ID. The result set can be modified using a set of filters.
The path must contain a channelId
. Note that this must be the channel ID that was assigned by eTrusted and not a user-defined ID.
Query parameters can be added to the request, separated by &
.
By adding parameters to the request, you can filter the result list and:
- specify the maximum number of invites they want to retrieve with this request
- retrieve invites submitted within a certain time frame
The response object contains the list of invite objects as well as information for paginating invites in a user interface. See our article on paginating response data for more information.
Parameters
Route Parameters
Name | Description |
---|---|
id | The channel UUID for which to retrieve the list of invites. |
HTTP Headers
Name | Description |
---|---|
token | An authorisation header containing meta information, see OAuth2. |
Channel-Id | Channel-Id contains the user-defined channel name. This allows the resource to to be called without a channel ID in the path. If using this header, the channel ID in the path must be set to "user-defined". |
Query Parameters
Name | Description |
---|---|
count | The desired number of invite objects to be retrieved per page. |
after |
|
before |
|
query |
|
Responses
200 - The list of invites.
Name | Description |
---|---|
application/json | InviteResponseListDto |
|
401 - Unauthorized
403 - Forbidden
404 - Not Found
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.etrusted.com/channels/{channelId}/invites?count=95&query=search_term",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_POSTFIELDS => "",
CURLOPT_HTTPHEADER => array(
"Content-Type: application/json",
"cache-control: no-cache"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
var settings = {
"async": true,
"crossDomain": true,
"url": "https://api.etrusted.com/channels/{channelId}/invites?count=95&query=search_term",
"method": "GET",
"headers": {
"Content-Type": "application/json",
"cache-control": "no-cache"
},
"processData": false,
"data": ""
}
$.ajax(settings).done(function (response) {
console.log(response);
});
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://api.etrusted.com/channels/{channelId}/invites?count=95&query=search_term")
.get()
.addHeader("Content-Type", "application/json")
.addHeader("cache-control", "no-cache")
.build();
Response response = client.newCall(request).execute();
Schedule new invites
This endpoint allows for the scheduling of new review invites into eTrusted system.
NB: In compliance with GDPR, customers should be given the option to opt-in to receive review invitations from you. Therefore, schedule invites using data of only customers who have opted-in.
Parameters
Body
Content-Type | Type |
---|---|
application/json | InvitesRequest |
|
Responses
207 - Multi-Status
Name | Description |
---|---|
application/json | InvitesResponse |
|
400 - Bad Request
Name | Description |
---|---|
application/json | ErrorResponse |
|
401 - Unauthorized
Name | Description |
---|---|
application/json | ErrorResponse |
|
Models
TemplateDto
The template used for generating the questionnaire for the invite.
Properties
id
string
A reference to the template used for generating the questionnaire.
name
string
The title of the questionnaire.
A reference to the template used for generating the questionnaire.
The title of the questionnaire.
EmailDto
Email data for identifying a customer or an organisation by email address.
Properties
name
string
The customer's or organisation's name.
email
string
The email address.
The customer's or organisation's name.
The email address.
InviteResponseDto
A single invite object retrieved via API.
Properties
id
string
The invite UUID.
_object
string
The invite object type.
mode
string
The invite mode.
Automatic invites are triggered by invite rules, while manual invites are triggered manually (e.g. in the Control Centre).
reviewType
string
The type of review the invitation asks for.
The invite has been sent asking for feedback either about the service, the transaction's products or for both.
accountRef
string
A UUID as account reference.
channelRef
string
A UUID as channel reference.
locale
string
The channel locale that determines the language that is used for this channel.
platform
string
Represents the name of an external review platform.
customer
object
The data of the customer who is invited to the review.
Properties
id
string
The customer UUID.
firstName
string
First name of the customer.
lastName
string
Last name of the customer.
email
string
Email address of the customer.
This must be a valid email address.
phoneNumber
string
A phone number in E.164 format.
preferredLocale
string
The preferred locale for this customer.
consents
object[]
This is an array of consent objects for the customer.
inviteSource
string
The source system that triggered the invite.
This property can have the following values:
TRUSTBADGE
IMPORTER
APP_IOS
APP_ANDROID
REVIEW_COLLECTOR
CUSTOM
transaction
object
scheduledAt
string
estimatedDeliveryDate
string
The estimated date of the delivery. It is a date in the ISO 8601 and RFC3339 compliant format yyyy-MM-dd
.
template
sender
replyTo
event
string
A UUID as event reference.
createdAt
string
updatedAt
string
sentAt
string
status
object
Status information of the invite when the API request was processed.
See our glossary entry for invites for more information about the statuses.
Properties
name
string
The invite state.
reason
string
The reason for the invite state.
The invite UUID.
The invite object type.
The invite mode.
Automatic invites are triggered by invite rules, while manual invites are triggered manually (e.g. in the Control Centre).
The type of review the invitation asks for.
The invite has been sent asking for feedback either about the service, the transaction's products or for both.
A UUID as account reference.
A UUID as channel reference.
The channel locale that determines the language that is used for this channel.
Represents the name of an external review platform.
The data of the customer who is invited to the review.
The customer UUID.
First name of the customer.
Last name of the customer.
Email address of the customer. This must be a valid email address.
A phone number in E.164 format.
The preferred locale for this customer.
This is an array of consent objects for the customer.
The source system that triggered the invite. This property can have the following values:
TRUSTBADGE
IMPORTER
APP_IOS
APP_ANDROID
REVIEW_COLLECTOR
CUSTOM
The estimated date of the delivery. It is a date in the ISO 8601 and RFC3339 compliant format yyyy-MM-dd
.
A UUID as event reference.
Status information of the invite when the API request was processed.
See our glossary entry for invites for more information about the statuses.
The invite state.
The reason for the invite state.
InviteResponseListDto
Properties
totalElements
integer
This field has the default value of 0 and will be removed in the future cause backend compatibillity issue.
paging
object
The paging object holds pagination information for the invites retrieved via this API.
Properties
count
integer
The number of invites displayed in one page of the pagination.
Note that this number might be lower than the count
number in the request.
This happens when the last page is reached.
For example: A total number of 105 invites are displayed in chunks of 20 invites per page.
The sixth and last page will only have 5 reviews.
The count
property will hold the value 5
.
cursor
object
The cursor object contains information to navigate to the previous and next pages in a subsequent request.
Properties
after
string
after
is an invite UUID to retrieve the next page in the pagination.
before
string
before
is an invite UUID to retrieve the previous page in the pagination.
links
object
Links to the previous and next pages in the pagination.
Note that the links contain the same query
filter parameters that was used in the request.
This makes sure that the pagination is always relative to the same filter in subsequent requests.
If you build URLs yourself using after
, before
, make sure that you recreate the same filter as well.
Properties
previous
string
The link to the previous page in the pagination.
next
string
The link to the next page in the pagination.
items
The list of invite objects.
Each item
object represents a single retrieved invite.
This field has the default value of 0 and will be removed in the future cause backend compatibillity issue.
The paging object holds pagination information for the invites retrieved via this API.
The number of invites displayed in one page of the pagination.
Note that this number might be lower than the count
number in the request.
This happens when the last page is reached.
For example: A total number of 105 invites are displayed in chunks of 20 invites per page.
The sixth and last page will only have 5 reviews.
The count
property will hold the value 5
.
The cursor object contains information to navigate to the previous and next pages in a subsequent request.
after
is an invite UUID to retrieve the next page in the pagination.
before
is an invite UUID to retrieve the previous page in the pagination.
Links to the previous and next pages in the pagination.
Note that the links contain the same query
filter parameters that was used in the request.
This makes sure that the pagination is always relative to the same filter in subsequent requests.
If you build URLs yourself using after
, before
, make sure that you recreate the same filter as well.
The link to the previous page in the pagination.
The link to the next page in the pagination.
The list of invite objects.
Each item
object represents a single retrieved invite.
Invite
The invite to be scheduled for later sendout.
Properties
questionnaireTemplate
object
The questionnaire template which will be used to render the actual questionnaire for this invite.
Properties
id
string
The eTrusted unique identifier of the questionnaire template.
template
object
The invite template which will be used for sending the invite.
Properties
id
string
The eTrusted unique identifier of the invite template.
customer
object
The customer invited to leave a review.
Properties
firstName
string
The customer's first name.
lastName
string
The customer's last name.
email
string
The customer's email address.
locale
string
The locale in which the customer will get the invite and questionnaire.
transaction
object
The transaction to be reviewed.
Properties
reference
string
An external reference to the transaction.
date
string
The date when the transaction occurred, given in the ISO8601 & RFC3339 valid format yyyy-MM-dd'T'HH:mm:ss.SSSZ.
products
object[]
This is a list of products.
It contains the products that are associated with the event.
It includes all data needed for product reviews for these products.
preferredSendTime
string
The date and time when the invite should be sent. It is in the ISO 8601 & RFC3339 valid format yyyy-MM-dd'T'HH:mm:ss.SSSZ
. If it is not set or the date is in the past, the invite will be scheduled immediately.
metadata
object
Key-value pairs of metadata associated with the invite.
The questionnaire template which will be used to render the actual questionnaire for this invite.
The eTrusted unique identifier of the questionnaire template.
The invite template which will be used for sending the invite.
The eTrusted unique identifier of the invite template.
The customer invited to leave a review.
The customer's first name.
The customer's last name.
The customer's email address.
The locale in which the customer will get the invite and questionnaire.
The transaction to be reviewed.
An external reference to the transaction.
The date when the transaction occurred, given in the ISO8601 & RFC3339 valid format yyyy-MM-dd'T'HH:mm:ss.SSSZ.
This is a list of products. It contains the products that are associated with the event. It includes all data needed for product reviews for these products.
The date and time when the invite should be sent. It is in the ISO 8601 & RFC3339 valid format yyyy-MM-dd'T'HH:mm:ss.SSSZ
. If it is not set or the date is in the past, the invite will be scheduled immediately.
Key-value pairs of metadata associated with the invite.
InvitesRequest
The request, that contains all the needed information to schedule new invites.
Properties
channel
object
The channel which will be associated with the invites.
Properties
id
string
The unique identifier of the channel.
type
string
This can be set to either user_defined
if you defined the channel id yourself or etrusted
if it was generated by the eTrusted system thus its in the format chl-xxxxxxxx-yyyy-xxxx-yyyy-xxxxxxxxxxxx
. Visit channel IDs to read more
system
string
The system
property identifies the clients system that issued the API call (e.g. “salesforce”, “sap”, etc.).
systemVersion
string
The systemVersion
property identifies the version of the source system (e.g. “1.0”). This offers organisations the option to use different versions of the same integration without putting this information into the system name.
The invites to be scheduled.
The channel which will be associated with the invites.
The unique identifier of the channel.
This can be set to either user_defined
if you defined the channel id yourself or etrusted
if it was generated by the eTrusted system thus its in the format chl-xxxxxxxx-yyyy-xxxx-yyyy-xxxxxxxxxxxx
. Visit channel IDs to read more
The system
property identifies the clients system that issued the API call (e.g. “salesforce”, “sap”, etc.).
The systemVersion
property identifies the version of the source system (e.g. “1.0”). This offers organisations the option to use different versions of the same integration without putting this information into the system name.
The invites to be scheduled.
FailedInvite
The invite that was not scheduled.
Properties
status
integer
The HTTP status code of the error.
reasons
[]
The reasons, why the invite was not scheduled.
The HTTP status code of the error.
The reasons, why the invite was not scheduled.
InvitesResponse
The response, if something went wrong.
Properties
batchId
string
The eTrusted unique identifier of the request with invites. It will be returned only if some invites were successfully scheduled (successfulInvites>0).
successfulInvites
integer
The number of successfully scheduled invites.
failedInvites
The invites that were not scheduled.
The eTrusted unique identifier of the request with invites. It will be returned only if some invites were successfully scheduled (successfulInvites>0).
The number of successfully scheduled invites.
The invites that were not scheduled.
ErrorResponse
The response, if the authorization or initial validation failed.
Properties
Message
string
Error message details
Error message details
Need further support?
Visit the Help Centre for further information, or contact us. Are some words or terms unfamiliar? Then visit the glossary for clarification.