Trustmary Integration API (1.0.0)

Download OpenAPI specification:

Rate Limiting

The API enforces a rate limit of 1000 requests per minute. Excess requests will result in a 429 error.

API key test

Authorizations:

ApiKeyAuth

Responses

Response samples

200
403
500

Content type

application/json

{"message": "Your API key is working",
"organization_id": "testorg",
"organization_name": "Test Organization",
"api_key_name": "Test API key"
}

List contacts

Authorizations:

ApiKeyAuth

query Parameters

email	string Email to filter by
offset	integer <int32> Start offset for query
includeAll	boolean Include also contacts marked as deleted.

Responses

Response samples

200
400
403
500

Content type

application/json

[{"id": "Ujdno_k8k",
"email": "frank@example.com",
"name": "Frank Mushroom",
"firstname": "Frank",
"lastname": "Mushroom",
"eid": "Thow9nJ23",
"phone": "+358100100",
"company": "Company Inc",
"created_at": "2021-09-29T14:14:46.651Z",
"updated_at": "2021-09-29T14:14:46.651Z",
"last_action": "2021-09-29T14:14:46.762Z",
"deleted_at": null,
"status": "active",
"type": "customer",
"nps_status": "promoter",
"original_nps_status": "passive",
"recommend_status": "recommend",
"nps_change": "up"
}
]

Create or update contact

Upserts a contact in Trustmary. If a contact exists with the same email address it will be updated. If no existing contact is found a new contact will be created.

If the addToLists property is in the request, the contact will also be added in the list. If the list has an automation connected to it, adding a contact with this endpoint also sends the survey invite to the contact. Adding a contact to a list has the same meaning as triggering an invite for the contact to the survey that is connected to the list.

The segment value is only used for the single survey invite a request to this endpoint results in (if addToLists is specified). The value is never saved in the contact data.

Authorizations:

ApiKeyAuth

Request Body schema: application/json
required

Contact data

email required	string
name	string This field can be used to populate the firstname and lastname fields if processName is set to true.
firstname	string
lastname	string
eid	string
phone	string
company	string
type	string Enum: "customer" "employee"
	Array of strings or objects (AddToContactListItem) Array of contact list ID's or list ID/segment tuples. If the optional segment parameter is included in addToLists then a connected automation will be triggered with the segment value included.
removeFromLists	Array of strings Array of contact list ID's
addToCampaignIds	Array of strings Array of campaign ID's. For each campaign, its automation pipeline is triggered for the upserted contact. Requires Automation V2 to be active for the organization — otherwise the campaign has no automation pipeline and the request fails with campaign_not_found. The pipeline must also not be stopped, otherwise the request fails with pipeline_stopped.
processName	boolean If set to true, firstname and lastname will be extracted and populated from name.
field_*	string Set custom field value

Responses

Request samples

Payload

Content type

application/json

{"email": "string",
"name": "string",
"firstname": "string",
"lastname": "string",
"eid": "string",
"phone": "string",
"company": "string",
"type": "customer",
"addToLists": ["string"
],
"removeFromLists": ["string"
],
"addToCampaignIds": ["string"
],
"processName": true,
"field_*": "string"
}

Response samples

200
400
403
500

Content type

application/json

{"contact": {"id": "85jtL8fjw",
"email": "frank@example.com",
"created_at": "2021-09-29T14:14:46.651Z",
"updated_at": "2021-09-29T14:14:46.651Z",
"status": "active",
"type": "customer",
"name": "Frank Mushroom",
"phone": "+358100100",
"eid": "jJkirjK9",
"company": "Company Inc"
},
"action": "IMPORT_CREATE",
"listsUpdated": 1
}

Delete contact

Authorizations:

ApiKeyAuth

Request Body schema: application/json
required

email

string

Responses

Request samples

Payload

Content type

application/json

{"email": "string"
}

Response samples

200
400
403
500

Content type

application/json

{"contact": {"email": "e@example.com",
"id": "qaPTkgycqd",
"created_at": "2021-09-30T09:19:28.385Z",
"updated_at": "2021-09-30T09:19:28.385Z",
"deleted_at": "2021-10-11T10:35:01.567Z",
"last_action": "2021-09-30T09:19:34.691Z",
"status": "active",
"type": "customer",
"name": "Sarah Oak",
"lastname": "Oak",
"firstname": "Sarah"
}
}

List contact lists

Authorizations:

ApiKeyAuth

Responses

Response samples

200
400
403
500

Content type

application/json

[{"id": "W0yDxNPeK",
"type": "employee",
"count": 5,
"name": "Customer list",
"source": "list",
"created_at": "2021-09-29T14:13:53.784Z",
"updated_at": "2021-09-29T14:13:53.784Z",
"deleted_at": null
}
]

List surveys

Authorizations:

ApiKeyAuth

query Parameters

type	string Enum: "customer" "employee" Survey type to filter by
offset	integer <int32> Start offset for query

Responses

Response samples

200
400
403
500

Content type

application/json

[{"id": "5iEwG88ib",
"type": "customer",
"count": 2,
"name": "NPS survey",
"created_at": "2021-09-29T14:06:13.963Z",
"updated_at": "2021-09-29T14:06:13.963Z",
"deleted_at": null
},
{"id": "c8U5ckfks",
"type": "customer",
"count": 15,
"name": "Video review",
"created_at": "2021-03-23T13:01:10.903Z",
"updated_at": "2021-03-23T13:01:10.903Z",
"deleted_at": null
}
]

List responses to a survey

Authorizations:

ApiKeyAuth

path Parameters

survey_id

required

string

String ID of the survey

query Parameters

offset	integer <int32> Start offset for pagination
limit	integer <int32> [ 1 .. 100 ] Number of responses to return (1–100, default 100)
sort	string Enum: "asc" "desc" Sort order by created_at date

Responses

Response samples

200
400
403
500

Content type

application/json

{"questions": [{"id": "nps",
"type": "nps",
"label": "How likely are you to recommend us?"
},
{"id": "feedback",
"type": "comment",
"label": "What is the primary reason for your score?"
},
{"id": "question_b946gsF57n",
"type": "text",
"label": "Name"
}
],
"responses": [{"id": "3ItabcuL5",
"created_at": "2021-09-29T14:14:46.651Z",
"completed_at": "2021-09-29T14:14:46.651Z",
"contact": {"id": "Ujdno_k8k",
"email": "frank@example.com",
"name": "Frank Mushroom",
"firstname": "Frank",
"lastname": "Mushroom",
"phone": "+358100100",
"company": "Company Inc"
},
"answers": {"nps": 9,
"feedback": "Great product!",
"question_b946gsF57n": "Frank Mushroom"
},
"customParams": {"utm_source": "google",
"campaign": "spring"
}
}
]
}

Get survey information

Authorizations:

ApiKeyAuth

path Parameters

surveyId

required

string

String ID of the survey to get

Responses

Response samples

200
403
500

Content type

application/json

{"id": "TN6I4tvo_",
"name": "NPS survey",
"organization_id": "testorg",
"type": "customer",
"status": "open",
"fields": [{"name": "nps",
"type": "nps",
"label": "How likely are you to recommend our\n product to a friend or colleague?"
},
{"name": "feedback",
"type": "comment",
"label": "What is the primary reason for your score?"
},
{"name": "comment",
"type": "comment",
"label": "Can we publish your feedback on our website and social media?",
"description": "You can edit your public comment here."
},
{"name": "noPublicConsent",
"type": "checkbox",
"label": "I don't want to publish my feedback"
},
{"name": "comment_video",
"type": "video"
},
{"name": "noVideoRecord",
"type": "checkbox",
"label": "I don’t want to record a video comment"
}
]
}

List embeds owned by the API key holder

Authorizations:

ApiKeyAuth

query Parameters

offset

integer <int32>

Start offset for query

Responses

Response samples

200
403
500

Content type

application/json

[{"id": "Krxo5Mgn9",
"name": "Embed 1",
"active": true
},
{"id": "7nmdQtD8R",
"name": "Embed 2",
"active": false
}
]

List widgets owned by the API key holder

Authorizations:

ApiKeyAuth

query Parameters

offset

integer <int32>

Start offset for query

Responses

Response samples

200
403
500

Content type

application/json

[{"id": "Krxo5Mgn9",
"name": "Popup widget",
"active": true,
"template_type": "popup"
},
{"id": "7nmdQtD8R",
"name": "Inpage Chatbot",
"active": false,
"template_type": "inpage"
}
]

List experiments owned by the API key holder

Authorizations:

ApiKeyAuth

query Parameters

offset

integer <int32>

Start offset for query

Responses

Response samples

200
403
500

Content type

application/json

[{"id": "experiment-1",
"name": "Which one is better",
"variants": [{"id": "7nmdQtD8R",
"name": "Popup Notification"
},
{"id": "ALF8_O09Ma",
"name": "Inpage Chatbot"
}
]
}
]

List webhooks

Authorizations:

ApiKeyAuth

Responses

Response samples

200
403
500

Content type

application/json

{"webhooks": [{"id": "webhook_123",
"name": "My Webhook",
"hookUrl": "https://example.com/webhook",
"events": ["surveyAnswerComplete",
"newReview"
],
"created_at": "2021-09-29T14:14:46.651Z",
"disabled": false
}
]
}

Create webhook

Authorizations:

ApiKeyAuth

Request Body schema: application/json
required

name	string Webhook name
hookUrl required	string Webhook URL to receive events
events required	Array of strings Items Enum: "surveyAnswerComplete" "newSurveyAnswer" "newReview" List of events to subscribe to

Responses

Request samples

Payload

Content type

application/json

{"name": "My Webhook",
"hookUrl": "https://example.com/webhook",
"events": ["surveyAnswerComplete",
"newReview"
]
}

Response samples

200
400
403
500

Content type

application/json

{"webhook": {"id": "webhook_123",
"name": "My Webhook",
"hookUrl": "https://example.com/webhook",
"events": ["surveyAnswerComplete",
"newReview"
],
"created_at": "2021-09-29T14:14:46.651Z",
"disabled": false
}
}

Delete webhook

Authorizations:

ApiKeyAuth

path Parameters

webhook_id

required

string

Webhook ID to delete

Responses

Response samples

200
403
500

Content type

application/json

{"webhook": {"id": "webhook_123"
}
}

Get webhook example payload

Returns example webhook payload data for testing and integration purposes

Authorizations:

ApiKeyAuth

Responses

Response samples

200
403
500

Content type

application/json

{"payload": [{"survey_id": "qmckabcGa",
"survey_name": "Example survey",
"answer_id": "3ItabcuL5",
"answer_values": {"nps": 10,
"name": "Person Name",
"email": "person.name@domain.com",
"comment": "The product was awesome!",
"location": "Helsinki",
"organization": "Company Inc.",
"publicConsent": "true",
"noPublicConsent": "false"
},
"created_at": "2020-11-19T14:22:43.618Z",
"organization_id": "5SabcACyt",
"contact": {"review_id": "5j123ddc",
"source": "trustmary",
"published": false,
"eid": "nx123dlTO",
"created_at": "2020-12-03T13:32:29.370Z",
"reviewNps": 10,
"personName": "Person Name",
"commentText": "The product was awesome!",
"email": "person.name@domain.com"
},
"review": {"name": "Person Name",
"phone": "+358501231234",
"email": "person.name@domain.com",
"id": "IW5JasdMV",
"created_at": "2020-11-17T15:18:06.898Z",
"status": "active",
"type": "customer"
},
"automation": {"created_at": "2021-02-08T13:58:28.497Z",
"completed_at": "2021-02-08T13:58:30.357Z"
}
}
]
}

Retrieve a review connection by the ID or the slug property

Authorizations:

ApiKeyAuth

path Parameters

idOrSlug

required

string

The ID as returned by the review connection list operation or user-specified name (slug)

Responses

Response samples

200

Content type

application/json

{"id": "12345",
"slug": "my-hotel-1",
"title": "My title for my hotel",
"source": "googlemaps",
"lang": "en",
"targetId": "hotel-0001",
"targetUrl": "https://airbnb.example.com/hotels/hotel-0001/"
}

Delete a review connection by the ID or the slug property

Authorizations:

ApiKeyAuth

path Parameters

idOrSlug

required

string

The ID as returned by the review connection list operation or user-specified name (slug)

Update a review connection by the ID or the slug property

Authorizations:

ApiKeyAuth

path Parameters

idOrSlug

required

string

The ID as returned by the review connection list operation or user-specified name (slug)

Request Body schema: application/json
required

slug	string or null User-specified name for the connection (unique), or null to unset
title	string or null User-specified title for the connection (unique), or null to unset

Request samples

Payload

Content type

application/json

{"slug": "my-hotel",
"title": "My hotel in Helsinki"
}

Create a new review connection by URL, source ID or by Google Places search

Authorizations:

ApiKeyAuth

Request Body schema: application/json
required

One of

slug	string Optional user-specified name for the review connection
title	string Optional title for the review connection
targetUrl	string The URL for the review service page. Connection parameters will be automatically parsed.

Responses

Request samples

Payload

Content type

application/json

Example

Create source with a source URL

{"slug": "my-hotel",
"targetUrl": "https://airbnb.example.com/hotels/hotel-id-123"
}

Response samples

200

Content type

application/json

{"id": "string",
"targetId": "string",
"targetTitle": "string"
}

List review connections

Authorizations:

ApiKeyAuth

Responses

Response samples

200

Content type

application/json

{"reviewConnections": [{"id": "12345",
"slug": "my-hotel-1",
"title": "My title for my hotel",
"source": "googlemaps",
"lang": "en",
"targetId": "hotel-0001",
"targetUrl": "https://airbnb.example.com/hotels/hotel-0001/"
}
]
}

List custom fields

Authorizations:

ApiKeyAuth

query Parameters

entity

string

Filter fields by entity type

Responses

Response samples

200
400
403
500

Content type

application/json

{"fields": [{"id": "string",
"type": "string",
"code": "string",
"label": "string",
"options": [null
],
"entities": ["string"
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z"
}
]
}

Create custom field

Authorizations:

ApiKeyAuth

Request Body schema: application/json
required

type required	string Field type identifier
code required	string Unique field code within the organization
label required	string Display name for the field
options	Array of any Field options for select-type fields
entities	Array of strings Entity types the field is attached to

Responses

Request samples

Payload

Content type

application/json

{"type": "string",
"code": "string",
"label": "string",
"options": [null
],
"entities": ["string"
]
}

Response samples

200
400
403
500

Content type

application/json

{"field": {"id": "string",
"type": "string",
"code": "string",
"label": "string",
"options": [null
],
"entities": ["string"
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z"
}
}

Upsert custom field

Authorizations:

ApiKeyAuth

Request Body schema: application/json
required

id required	string Unique field identifier
type required	string Field type identifier
code required	string Unique field code within the organization
label required	string Display name for the field
options required	Array of any Field options for select-type fields
entities required	Array of strings Entity types the field is attached to
created_at required	string <date-time>
updated_at required	string <date-time>
deleted_at	string or null <date-time>

Responses

Request samples

Payload

Content type

application/json

{"id": "string",
"type": "string",
"code": "string",
"label": "string",
"options": [null
],
"entities": ["string"
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z"
}

Response samples

200
400
403
500

Content type

application/json

{"field": {"id": "string",
"type": "string",
"code": "string",
"label": "string",
"options": [null
],
"entities": ["string"
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z"
}
}

Delete custom field by code

Authorizations:

ApiKeyAuth

Request Body schema: application/json
required

code

required

string

Field code to delete

Responses

Request samples

Payload

Content type

application/json

{"code": "string"
}

Response samples

200
400
403
500

Content type

application/json

{"field": {"id": "string",
"type": "string",
"code": "string",
"label": "string",
"options": [null
],
"entities": ["string"
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z"
}
}

Get custom field

Authorizations:

ApiKeyAuth

path Parameters

field_id

required

string

Identifier of the field to retrieve

Responses

Response samples

200
403
500

Content type

application/json

{"field": {"id": "string",
"type": "string",
"code": "string",
"label": "string",
"options": [null
],
"entities": ["string"
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z"
}
}

Update custom field

Authorizations:

ApiKeyAuth

path Parameters

field_id

required

string

Identifier of the field to update

Request Body schema: application/json
required

id required	string Unique field identifier
type required	string Field type identifier
code required	string Unique field code within the organization
label required	string Display name for the field
options required	Array of any Field options for select-type fields
entities required	Array of strings Entity types the field is attached to
created_at required	string <date-time>
updated_at required	string <date-time>
deleted_at	string or null <date-time>

Responses

Request samples

Payload

Content type

application/json

{"id": "string",
"type": "string",
"code": "string",
"label": "string",
"options": [null
],
"entities": ["string"
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z"
}

Response samples

200
400
403
500

Content type

application/json

{"field": {"id": "string",
"type": "string",
"code": "string",
"label": "string",
"options": [null
],
"entities": ["string"
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z"
}
}

Delete custom field

Authorizations:

ApiKeyAuth

path Parameters

field_id

required

string

Identifier of the field to delete

Responses

Response samples

200
403
500

Content type

application/json

{"success": true
}

Trustmary Integration API (1.0.0)

Rate Limiting

API key test

Authorizations:

Responses

Response samples

List contacts

Authorizations:

query Parameters

Responses

Response samples

Create or update contact

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Delete contact

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

List contact lists

Authorizations:

Responses

Response samples

List surveys

Authorizations:

query Parameters

Responses

Response samples

List responses to a survey

Authorizations:

path Parameters

query Parameters

Responses

Response samples

Get survey information

Authorizations:

path Parameters

Responses

Response samples

List embeds owned by the API key holder

Authorizations:

query Parameters

Responses

Response samples

List widgets owned by the API key holder

Authorizations:

query Parameters

Responses

Response samples

List experiments owned by the API key holder

Authorizations:

query Parameters

Responses

Response samples

List webhooks

Authorizations:

Responses

Response samples

Create webhook

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Delete webhook

Authorizations:

path Parameters

Responses

Response samples

Get webhook example payload

Authorizations:

Responses

Response samples

Retrieve a review connection by the ID or the slug property

Authorizations:

path Parameters

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required