Basic Changes
To update your code from using API version 1 to version 2, mostly, all you will need to do is change the part of the endpoint URL in your API call code that reads "/v1/" to "/v2/". For example, the endpoint to return a list of the surveys on an account changes from:
https://api.smartsurvey.io/v1/surveys
to:
https://api.smartsurvey.io/v2/surveys
However, with the release of API version 2, it was necessary to make some breaking changes to the endpoints that were migrated from version 1. This was almost entirely related to making the endpoints consistent with each other for naming and response types. This page describes the changes we are aware of making but you should always test any endpoints that you are using after migration to ensure they behave as expected.
You can find more detailed documentation on the API Reference site links below:
API Version 1 Reference
API Version 2 Reference
Please let us know via support ticket if you spot any problems with the new API! We might have missed something.
General Breaking Changes
- Some endpoints have messages returned such as "Tracking link has been deleted.". Although these have not been deliberately changed, some might have had typos fixed or naming made consistent so if you are using the text returned from an endpoint, you should check this still works as before.
- All endpoints that return more than one object now use a consistent return format that looks like this:
{
"records": [
{
"id": 78357,
... etc
}
],
"page_index": 0,
"pages": 1,
"page_size": 10,
"total": 6
}
{
"status": 400,
"code": "bad_request",
"message": "Some message"
}
- Some endpoints will be charged at a higher "rate" due to the additional load put on the system, for example the detailed surveys responses might cost 3 hits instead of 1. This code has not been enabled yet and you will be notified when it is but you are advised to avoid requesting any detailed responses that you do not need so it won't affect you later on.
- Some endpoints have had their default ordering changed to be more logical (ordering pages by their survey ordering instead of creation date for example). If you rely on the ordering, you need to specify it in the call.
Specific Breaking Changes
- Tracking Link endpoints no longer return date_closed if the tracking link is not closed, or auto_close_date if auto_close is false. This is because dates default to the created date and could be misleading.
- Send One and Send Multi for Survey Invitations now return a specific object describing the success of the operation as well as optional errors for specific contacts passed in the request. The original /send endpoint is now called /sendone whereas the new /send endpoint is for Send Multi.
- Scoring values will now only be returned if scoring is enabled on the survey you are querying
New Additions to the API
- Some response objects have 1 or 2 more properties in them
- There is now a Send Multi endpoint on the Survey Invitations controller which allows up to 100 contacts to be sent a new invitation to a survey instead of needing to be called multiple times. The Send One endpoint is closer to the behaviour of the old endpoint.