API | GET, UPDATE, and ADD Collection TouchPoint Responses

Australia and New Zealand users: API is not currently available in your region. Visit the Ideas Portal to submit or upvote a request. Your votes help the product team prioritize what's built next.

1. Authenticate your session in the API

2. Navigate to services.etosoftware.com/api-docs and locate the /API/Touchpoint.svc/GetCollectionResponses/ under the Collections tab

3. Fill out the required fields:

4. The returned value will look something like this: (See full text here)

5. Copy the response to Notepad or HTML/Text editing platform

6. Move to the /API/Touchpoint.svc/SaveCollectionResponse/

7. See the model of the call on the right hand side under 'Body'. You can copy this to Notepad or an HTML/Text editing platform as well to make it easier to fill out.

8. You can now use the values that you received from your GetCollectionResponses to fill out the parameters for the SaveCollectionResponseWrapper.

9. Post the response with the changes you made

Status Code 400 = Bad request
​Status Code 500 = Internal error, Error trying to update TouchPoint Response
​Status Code 502 = Server Connection Error (This can sometimes be a bad call. Review the call and then contact Support for additional help.)
​Status Code 200 = Request was received and understood. See response header for details.

Note: There are some values that will differ depending on if you are adding a new response set or updating an existing one. See filled out examples and details below for each type of POST.

Adding a New Response Set:

• Use the data from this article to see how to fill out the parameters for each type of element and use this article to see how to convert dates.

• Because you are adding a brand new response set, you will not be able to get the exact data you need from the GetCollectionResponses. You would want to use the Standard Reference Form Universe in ETO Results to pull the Response Choice IDs, Element IDs and Element Type IDs for the TouchPoint you are working with.

• In the example below, anywhere you see '###' or 'insert x here' fill these in with your own data. This example is only using one element, and it is a Multiple Choice element. You will likely have additional elements that will need to be filled out in the sections where below there are a lot of null values.

• Anywhere you see a 0 or another numeric value, you will need to keep these as is.

• Note that there is a separate section for each Participant in the Collection which is identified by the SubjectID. This example Collection has three Participants.

Example body for adding a new Response Set:

{  "cr": {    "CollectionResponseID": 0,    "TouchPointID": ###,    "CollectionID": ###,    "CollectionTypeID": ###,    "ResponseSetID": 0,    "ProgramID": ###,    "SubjectTypeID": 1,    "CollectionElementResponses": [      {        "CollectionElementID": 0,        "CollectionElementIdentifier": null,        "CollectionID": ###,        "CreatedDate": "insert date here",        "AuditStaffID": ###,        "SubjectID": ###,        "ResponseElements": [          {            "ElementID": ###,            "Value": "insert value here",            "ElementType": ##,            "ResponseElementChoices": [              {                "ResponseChoiceTableID": 0,                "TouchPointResponseChoiceID": 0,                "TouchPointElementChoiceID": ###,                "AuditStaffID": ###              }            ],            "AttachmentDetailType": 0,            "ResponseStartAndEndTime": null,            "DateOfNextContactDetailType": 0,            "ResponseAddressField": null,            "ResponseDateOfNextContact": null,            "ResponseFileAttachment": null,            "ResponseFileAttachments": [],            "ResponseCheckInField": null          }        ],        "ErrorMessage": [          "string"        ],        "Action": 2      },	  	        {        "CollectionElementID": 0,        "CollectionElementIdentifier": null,        "CollectionID": ##,        "CreatedDate": "insert date here",        "AuditStaffID": ##,        "SubjectID": ###,        "ResponseElements": [          {            "ElementID": ###,            "Value": "insert value here",            "ElementType": ##,            "ResponseElementChoices": [              {                "ResponseChoiceTableID": 0,                "TouchPointResponseChoiceID": 0,                "TouchPointElementChoiceID": ###,                "AuditStaffID": ###              }            ],            "AttachmentDetailType": 0,            "ResponseStartAndEndTime": null,            "DateOfNextContactDetailType": 0,            "ResponseAddressField": null,            "ResponseDateOfNextContact": null,            "ResponseFileAttachment": null,            "ResponseFileAttachments": [],            "ResponseCheckInField": null          }        ],        "ErrorMessage": [          "string"        ],        "Action": 2      },	        {        "CollectionElementID": 0,        "CollectionElementIdentifier": null,        "CollectionID": ##,        "CreatedDate": "insert date here",        "AuditStaffID": ###,        "SubjectID": ###,        "ResponseElements": [          {            "ElementID": ###,            "Value": "insert value here",            "ElementType": ##,            "ResponseElementChoices": [              {                "ResponseChoiceTableID": 0,                "TouchPointResponseChoiceID": 0,                "TouchPointElementChoiceID": ###,                "AuditStaffID": ###              }            ],            "AttachmentDetailType": 0,            "ResponseStartAndEndTime": null,            "DateOfNextContactDetailType": 0,            "ResponseAddressField": null,            "ResponseDateOfNextContact": null,            "ResponseFileAttachment": null,            "ResponseFileAttachments": [],            "ResponseCheckInField": null          }        ],        "ErrorMessage": [          "string"        ],        "Action": 2      }    ],    "CreatedDate": "insert date here",    "AuditStaffID": ###,    "PopulateWithSameResponse": false,    "DefaultResponseElements": null,    "ErrorMessage": [      "string"    ]  },  "addNewResponseToExistingResponse": true}

Updating an Existing Response Set:

• This one is very similar to the above example, you will use the Standard Reference Form Universe in ETO Results to pull the Response Choice IDs, Element IDs and Element Type IDs for the TouchPoint you are working with.

• You may want to also run a TouchPoint response report in ETO Results to identify the ResponseSetID for the response set that you want to update, as this will be the identifier within the GetCollectionResponses.

• The example below is the same as the example above, but with minor adjustments, such as filling out the CollectionResponseID, ResponseSetID, and CollectionElementIDs with the information from the GetCollectionResponses. Additionally, you will be changing the "addNewResponseToExistingResponse" to False

Example body for updating an existing Response Set:

{  "cr": {    "CollectionResponseID": ###,    "TouchPointID": ###,    "CollectionID": ###,    "CollectionTypeID": ###,    "ResponseSetID": ###,    "ProgramID": ###,    "SubjectTypeID": 1,    "CollectionElementResponses": [      {        "CollectionElementID": ###,        "CollectionElementIdentifier": null,        "CollectionID": ###,        "CreatedDate": "insert date here",        "AuditStaffID": ###,        "SubjectID": ###,        "ResponseElements": [          {            "ElementID": ###,            "Value": "insert value here",            "ElementType": ##,            "ResponseElementChoices": [              {                "ResponseChoiceTableID": 0,                "TouchPointResponseChoiceID": 0,                "TouchPointElementChoiceID": ###,                "AuditStaffID": ###              }            ],            "AttachmentDetailType": 0,            "ResponseStartAndEndTime": null,            "DateOfNextContactDetailType": 0,            "ResponseAddressField": null,            "ResponseDateOfNextContact": null,            "ResponseFileAttachment": null,            "ResponseFileAttachments": [],            "ResponseCheckInField": null          }        ],        "ErrorMessage": [          "string"        ],        "Action": 2      },	  	        {        "CollectionElementID": ###,        "CollectionElementIdentifier": null,        "CollectionID": ##,        "CreatedDate": "insert date here",        "AuditStaffID": ##,        "SubjectID": ###,        "ResponseElements": [          {            "ElementID": ###,            "Value": "insert value here",            "ElementType": ##,            "ResponseElementChoices": [              {                "ResponseChoiceTableID": 0,                "TouchPointResponseChoiceID": 0,                "TouchPointElementChoiceID": ###,                "AuditStaffID": ###              }            ],            "AttachmentDetailType": 0,            "ResponseStartAndEndTime": null,            "DateOfNextContactDetailType": 0,            "ResponseAddressField": null,            "ResponseDateOfNextContact": null,            "ResponseFileAttachment": null,            "ResponseFileAttachments": [],            "ResponseCheckInField": null          }        ],        "ErrorMessage": [          "string"        ],        "Action": 2      },	        {        "CollectionElementID": ###,        "CollectionElementIdentifier": null,        "CollectionID": ##,        "CreatedDate": "insert date here",        "AuditStaffID": ###,        "SubjectID": ###,        "ResponseElements": [          {            "ElementID": ###,            "Value": "insert value here",            "ElementType": ##,            "ResponseElementChoices": [              {                "ResponseChoiceTableID": 0,                "TouchPointResponseChoiceID": 0,                "TouchPointElementChoiceID": ###,                "AuditStaffID": ###              }            ],            "AttachmentDetailType": 0,            "ResponseStartAndEndTime": null,            "DateOfNextContactDetailType": 0,            "ResponseAddressField": null,            "ResponseDateOfNextContact": null,            "ResponseFileAttachment": null,            "ResponseFileAttachments": [],            "ResponseCheckInField": null          }        ],        "ErrorMessage": [          "string"        ],        "Action": 2      }    ],    "CreatedDate": "insert date here",    "AuditStaffID": ###,    "PopulateWithSameResponse": false,    "DefaultResponseElements": null,    "ErrorMessage": [      "string"    ]  },  "addNewResponseToExistingResponse": false}

API Main Page