Template API

Owned by Claudio Baldi
Last updated: Nov 30, 2022
38 min read

Context:

Buyers can now select the template via API. The Template API allows a buyer to create a survey based on a template without specifying other settings. Buyers can use the API and add the template ID to use during the survey creation.

Functional:

  • Allow buyers to use a template via API

  • Buyers need only to specify the ID of the template

  • Buyers can check the list of template-id via API

    • The API returns

      • Title

      • Template ID

      • Template name

      • Folder name

  • Any template survey created via API template can be managed via UI.

  • Any survey created via API template will have the template selected.

Note:

  • Buyer account must have the template feature activated

  • Buyers can use only the accessible templates

    • Own templates: Created by the buyer

    • Default templates: Created by PS Product team and accessible to any buyer

    • Shared templates: Created by PS Support and accessible to a specific buyer

  • Buyers can select only one template.

API Specification:

GET templates API for API users:

GET <SERVER_BASE_URL>/buyers/v2/templates?UI=0

Response:

[ { "folder": "CA-en", "templates": [ { "id": 26, "name": "Province qual", "title": "Template - Non US countries" } ] }, { "folder": "Austria-German", "templates": [ { "id": 30, "name": "Age, Education, Postal codes", "title": "Austria - German" } ] } ]

GET templates API for UI users:

GET <SERVER_BASE_URL>/buyers/v2/templates?UI=1

Response:

POST survey API - When in payload buyer passes a template-id, but the template feature is not enabled for him:

Request:

Response - 403 Forbidden:

 

POST survey API - When in payload buyer passes a template he does not have access to.

Request:

Response - 404 Not Found:

POST survey API - When the buyer passes the correct template Id in the payload

Request:

Response:

PUT survey API - When in payload buyer passes a template id, but template feature is not enabled for him.

Same request and response payload as POST survey API

PUT survey API - When in payload buyer passes a template he does not have access to.

Same request and response payload as POST survey API

PUT survey API - When the buyer passes the correct template Id in the payload

Same request and response payload as POST survey API

PUT survey API - When the buyer passes a different template id than the one used in the survey

Same request payload as POST survey API

Response

PUT survey API - When the buyer passes the template id but the survey does not use any template

Same request and response payload as POST survey API

 

Inherit the metadata template value if the payload doesn’t have them.
POST survey API

 

Request Payload:

 

Response:

 

UI view of this survey:

 

PUT survey API

 

Request Payload:

 

Response:

 

If the user specifies in the payload these values, they will be overridden in both POST and PUT API.
Values are:

  • Completes

  • IR

  • LOI

  • Category

  • Country

  • Language

  • Title