# Surveys
Create, read, update, and delete partner surveys.
## List surveys
> Returns a paginated list of surveys for the program. Supports filtering by name, status, partner IDs, and publisher groups.
```json
{"openapi":"3.1.0","info":{"title":"Surveys","version":"v14"},"tags":[{"name":"Surveys","description":"Create, read, update, and delete partner surveys."}],"servers":[{"url":"https://api.impact.com","description":"impact.com API"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic","description":"HTTP Basic authentication. Use your Account SID as the username and your Auth Token as the password.\n"}},"parameters":{"Page":{"name":"Page","in":"query","required":false,"description":"Page number (1-based).","schema":{"type":"integer","default":1}},"PageSize":{"name":"PageSize","in":"query","required":false,"description":"Number of results per page.","schema":{"type":"integer","default":50}}},"schemas":{"SurveyListResponse":{"type":"object","properties":{"Page":{"type":"integer"},"PageSize":{"type":"integer"},"TotalCount":{"type":"integer"},"Surveys":{"type":"array","items":{"$ref":"#/components/schemas/SurveySummary"}}}},"SurveySummary":{"type":"object","properties":{"Id":{"type":"integer","format":"int64"},"Name":{"type":"string"},"Description":{"type":"string"},"StartDate":{"type":"string","format":"date-time"},"EndDate":{"type":"string","format":"date-time"},"Status":{"type":"string","enum":["Active","Upcoming","Expired"],"description":"Automatically calculated from the date range. Active = no restrictions or currently within range; Upcoming = start date in the future; Expired = end date in the past.\n"},"CoverImageUrl":{"type":"string"},"QuestionsCount":{"type":"integer"},"ResponsesCount":{"type":"integer"},"CreatedDate":{"type":"string","format":"date-time"},"UpdatedDate":{"type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Bad request — invalid request or validation failure."},"NotFound":{"description":"Resource not found."},"ServerError":{"description":"Internal server error."}}},"paths":{"/Advertisers/{AccountSid}/Programs/{ProgramId}/Surveys":{"get":{"tags":["Surveys"],"operationId":"listSurveys","summary":"List surveys","description":"Returns a paginated list of surveys for the program. Supports filtering by name, status, partner IDs, and publisher groups.\n","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"},{"name":"Query","in":"query","required":false,"description":"Filter surveys by name.","schema":{"type":"string"}},{"name":"Status","in":"query","required":false,"description":"Filter by survey status.","schema":{"type":"string","enum":["Active","Upcoming","Expired"]}},{"name":"PartnerIds","in":"query","required":false,"description":"Filter surveys by one or more partner IDs.","schema":{"type":"array","items":{"type":"integer","format":"int64"}},"style":"form","explode":true},{"name":"PublisherGroups","in":"query","required":false,"description":"Filter surveys by one or more publisher group names.","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true}],"responses":{"200":{"description":"A paginated list of surveys.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SurveyListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```
## Create a survey
> Creates a survey. Requires a name and a list of questions. Optional fields include dates, timezone, cover image URL, and partner/group restrictions.
```json
{"openapi":"3.1.0","info":{"title":"Surveys","version":"v14"},"tags":[{"name":"Surveys","description":"Create, read, update, and delete partner surveys."}],"servers":[{"url":"https://api.impact.com","description":"impact.com API"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic","description":"HTTP Basic authentication. Use your Account SID as the username and your Auth Token as the password.\n"}},"schemas":{"CreateSurveyRequest":{"type":"object","required":["Name","Questions"],"properties":{"Name":{"type":"string","maxLength":255,"description":"Name of the survey."},"Description":{"type":"string","description":"Description of the survey."},"StartDate":{"type":"string","format":"date","description":"Start date (ISO 8601)."},"EndDate":{"type":"string","format":"date","description":"End date (ISO 8601)."},"Timezone":{"type":"string","description":"IANA timezone ID (e.g. America/New_York, UTC). Stored for reference.\n"},"CoverImageUrl":{"type":"string","description":"URL for the survey cover image. If not provided, the brand's logo is used.\n"},"RestrictToPartners":{"type":"array","uniqueItems":true,"description":"Set of partner IDs to restrict the survey to.","items":{"type":"integer","format":"int64"}},"RestrictToGroups":{"type":"array","uniqueItems":true,"description":"Set of group names to restrict the survey to.","items":{"type":"string"}},"Questions":{"type":"array","description":"List of questions to create.","items":{"$ref":"#/components/schemas/CreateQuestion"}}}},"CreateQuestion":{"type":"object","required":["Question"],"properties":{"Question":{"type":"string","maxLength":191,"description":"The question text."},"CustomFieldId":{"type":"integer","format":"int64","description":"ID of the custom field linked to this question."},"ResponseRequired":{"type":"boolean","default":false,"description":"Whether a response is required."},"ResponseEditable":{"type":"boolean","default":false,"description":"Whether the response is editable."}}},"Survey":{"allOf":[{"$ref":"#/components/schemas/SurveySummary"},{"type":"object","properties":{"Questions":{"type":"array","items":{"$ref":"#/components/schemas/Question"}}}}]},"SurveySummary":{"type":"object","properties":{"Id":{"type":"integer","format":"int64"},"Name":{"type":"string"},"Description":{"type":"string"},"StartDate":{"type":"string","format":"date-time"},"EndDate":{"type":"string","format":"date-time"},"Status":{"type":"string","enum":["Active","Upcoming","Expired"],"description":"Automatically calculated from the date range. Active = no restrictions or currently within range; Upcoming = start date in the future; Expired = end date in the past.\n"},"CoverImageUrl":{"type":"string"},"QuestionsCount":{"type":"integer"},"ResponsesCount":{"type":"integer"},"CreatedDate":{"type":"string","format":"date-time"},"UpdatedDate":{"type":"string","format":"date-time"}}},"Question":{"type":"object","properties":{"Id":{"type":"integer","format":"int64"},"Question":{"type":"string"},"CustomFieldId":{"type":"integer","format":"int64"},"ResponseRequired":{"type":"boolean"},"ResponseEditable":{"type":"boolean"},"Rank":{"type":"integer"},"CustomField":{"$ref":"#/components/schemas/CustomField"}}},"CustomField":{"type":"object","description":"A custom field that defines the data collection type for a survey question. For selection-based display types (drop-down, single-select, multi-select), `Enumerations` lists the available options.\n","properties":{"Id":{"type":"integer","format":"int64"},"Name":{"type":"string"},"Description":{"type":"string"},"DisplayType":{"type":"string","description":"The data collection type, returned as the internal value: `paragraph`, `number`, `date_picker`, `dropdown`, `multiple_choice` (single-select), `multiple_checkbox` (multi-select), or `file`.\n"},"Enumerations":{"type":"array","items":{"$ref":"#/components/schemas/Enumeration"}}}},"Enumeration":{"type":"object","description":"An allowed value for a selection-based custom field.","properties":{"Id":{"type":"integer","format":"int64"},"Value":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Bad request — invalid request or validation failure."},"NotFound":{"description":"Resource not found."},"ServerError":{"description":"Internal server error."}}},"paths":{"/Advertisers/{AccountSid}/Programs/{ProgramId}/Surveys":{"post":{"tags":["Surveys"],"operationId":"createSurvey","summary":"Create a survey","description":"Creates a survey. Requires a name and a list of questions. Optional fields include dates, timezone, cover image URL, and partner/group restrictions.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSurveyRequest"}}}},"responses":{"201":{"description":"The created survey.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Survey"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```
## Get a survey
> Returns full survey details, including all questions and their linked custom field information.
```json
{"openapi":"3.1.0","info":{"title":"Surveys","version":"v14"},"tags":[{"name":"Surveys","description":"Create, read, update, and delete partner surveys."}],"servers":[{"url":"https://api.impact.com","description":"impact.com API"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic","description":"HTTP Basic authentication. Use your Account SID as the username and your Auth Token as the password.\n"}},"schemas":{"Survey":{"allOf":[{"$ref":"#/components/schemas/SurveySummary"},{"type":"object","properties":{"Questions":{"type":"array","items":{"$ref":"#/components/schemas/Question"}}}}]},"SurveySummary":{"type":"object","properties":{"Id":{"type":"integer","format":"int64"},"Name":{"type":"string"},"Description":{"type":"string"},"StartDate":{"type":"string","format":"date-time"},"EndDate":{"type":"string","format":"date-time"},"Status":{"type":"string","enum":["Active","Upcoming","Expired"],"description":"Automatically calculated from the date range. Active = no restrictions or currently within range; Upcoming = start date in the future; Expired = end date in the past.\n"},"CoverImageUrl":{"type":"string"},"QuestionsCount":{"type":"integer"},"ResponsesCount":{"type":"integer"},"CreatedDate":{"type":"string","format":"date-time"},"UpdatedDate":{"type":"string","format":"date-time"}}},"Question":{"type":"object","properties":{"Id":{"type":"integer","format":"int64"},"Question":{"type":"string"},"CustomFieldId":{"type":"integer","format":"int64"},"ResponseRequired":{"type":"boolean"},"ResponseEditable":{"type":"boolean"},"Rank":{"type":"integer"},"CustomField":{"$ref":"#/components/schemas/CustomField"}}},"CustomField":{"type":"object","description":"A custom field that defines the data collection type for a survey question. For selection-based display types (drop-down, single-select, multi-select), `Enumerations` lists the available options.\n","properties":{"Id":{"type":"integer","format":"int64"},"Name":{"type":"string"},"Description":{"type":"string"},"DisplayType":{"type":"string","description":"The data collection type, returned as the internal value: `paragraph`, `number`, `date_picker`, `dropdown`, `multiple_choice` (single-select), `multiple_checkbox` (multi-select), or `file`.\n"},"Enumerations":{"type":"array","items":{"$ref":"#/components/schemas/Enumeration"}}}},"Enumeration":{"type":"object","description":"An allowed value for a selection-based custom field.","properties":{"Id":{"type":"integer","format":"int64"},"Value":{"type":"string"}}}},"responses":{"NotFound":{"description":"Resource not found."},"ServerError":{"description":"Internal server error."}}},"paths":{"/Advertisers/{AccountSid}/Programs/{ProgramId}/Surveys/{SurveyId}":{"get":{"tags":["Surveys"],"operationId":"getSurvey","summary":"Get a survey","description":"Returns full survey details, including all questions and their linked custom field information.\n","responses":{"200":{"description":"The requested survey.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Survey"}}}},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```
## Delete a survey
> Archives the survey and its questions.
```json
{"openapi":"3.1.0","info":{"title":"Surveys","version":"v14"},"tags":[{"name":"Surveys","description":"Create, read, update, and delete partner surveys."}],"servers":[{"url":"https://api.impact.com","description":"impact.com API"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic","description":"HTTP Basic authentication. Use your Account SID as the username and your Auth Token as the password.\n"}},"schemas":{"StatusResponse":{"type":"object","properties":{"Status":{"type":"string"}}}},"responses":{"NotFound":{"description":"Resource not found."},"ServerError":{"description":"Internal server error."}}},"paths":{"/Advertisers/{AccountSid}/Programs/{ProgramId}/Surveys/{SurveyId}":{"delete":{"tags":["Surveys"],"operationId":"deleteSurvey","summary":"Delete a survey","description":"Archives the survey and its questions.","responses":{"200":{"description":"The survey was archived.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```
## Update a survey
> Partially updates a survey. Only the fields provided are updated. Questions with an \`Id\` are updated; questions without an \`Id\` are created.
```json
{"openapi":"3.1.0","info":{"title":"Surveys","version":"v14"},"tags":[{"name":"Surveys","description":"Create, read, update, and delete partner surveys."}],"servers":[{"url":"https://api.impact.com","description":"impact.com API"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic","description":"HTTP Basic authentication. Use your Account SID as the username and your Auth Token as the password.\n"}},"schemas":{"UpdateSurveyRequest":{"type":"object","description":"All fields are optional. Only the fields provided are updated.","properties":{"Name":{"type":"string","maxLength":255,"description":"Updated name of the survey."},"Description":{"type":"string","description":"Updated description of the survey."},"StartDate":{"type":"string","format":"date","description":"Updated start date (ISO 8601)."},"EndDate":{"type":"string","format":"date","description":"Updated end date (ISO 8601)."},"Timezone":{"type":"string","description":"IANA timezone ID (e.g. America/New_York, UTC). Stored for reference."},"CoverImageUrl":{"type":"string","description":"Updated cover image URL."},"RestrictToPartners":{"type":"array","uniqueItems":true,"description":"Set of partner IDs to restrict the survey to.","items":{"type":"integer","format":"int64"}},"RestrictToGroups":{"type":"array","uniqueItems":true,"description":"Set of group names to restrict the survey to.","items":{"type":"string"}},"Questions":{"type":"array","description":"List of questions to create or update.","items":{"$ref":"#/components/schemas/UpdateQuestion"}}}},"UpdateQuestion":{"type":"object","properties":{"Id":{"type":"integer","format":"int64","description":"ID of an existing question to update. Omit to create a new one."},"Question":{"type":"string","maxLength":191,"description":"The question text."},"CustomFieldId":{"type":"integer","format":"int64","description":"ID of the custom field linked to this question."},"ResponseRequired":{"type":"boolean","default":false,"description":"Whether a response is required."},"ResponseEditable":{"type":"boolean","default":false,"description":"Whether the response is editable."}}},"Survey":{"allOf":[{"$ref":"#/components/schemas/SurveySummary"},{"type":"object","properties":{"Questions":{"type":"array","items":{"$ref":"#/components/schemas/Question"}}}}]},"SurveySummary":{"type":"object","properties":{"Id":{"type":"integer","format":"int64"},"Name":{"type":"string"},"Description":{"type":"string"},"StartDate":{"type":"string","format":"date-time"},"EndDate":{"type":"string","format":"date-time"},"Status":{"type":"string","enum":["Active","Upcoming","Expired"],"description":"Automatically calculated from the date range. Active = no restrictions or currently within range; Upcoming = start date in the future; Expired = end date in the past.\n"},"CoverImageUrl":{"type":"string"},"QuestionsCount":{"type":"integer"},"ResponsesCount":{"type":"integer"},"CreatedDate":{"type":"string","format":"date-time"},"UpdatedDate":{"type":"string","format":"date-time"}}},"Question":{"type":"object","properties":{"Id":{"type":"integer","format":"int64"},"Question":{"type":"string"},"CustomFieldId":{"type":"integer","format":"int64"},"ResponseRequired":{"type":"boolean"},"ResponseEditable":{"type":"boolean"},"Rank":{"type":"integer"},"CustomField":{"$ref":"#/components/schemas/CustomField"}}},"CustomField":{"type":"object","description":"A custom field that defines the data collection type for a survey question. For selection-based display types (drop-down, single-select, multi-select), `Enumerations` lists the available options.\n","properties":{"Id":{"type":"integer","format":"int64"},"Name":{"type":"string"},"Description":{"type":"string"},"DisplayType":{"type":"string","description":"The data collection type, returned as the internal value: `paragraph`, `number`, `date_picker`, `dropdown`, `multiple_choice` (single-select), `multiple_checkbox` (multi-select), or `file`.\n"},"Enumerations":{"type":"array","items":{"$ref":"#/components/schemas/Enumeration"}}}},"Enumeration":{"type":"object","description":"An allowed value for a selection-based custom field.","properties":{"Id":{"type":"integer","format":"int64"},"Value":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Bad request — invalid request or validation failure."},"NotFound":{"description":"Resource not found."},"ServerError":{"description":"Internal server error."}}},"paths":{"/Advertisers/{AccountSid}/Programs/{ProgramId}/Surveys/{SurveyId}":{"patch":{"tags":["Surveys"],"operationId":"updateSurvey","summary":"Update a survey","description":"Partially updates a survey. Only the fields provided are updated. Questions with an `Id` are updated; questions without an `Id` are created.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSurveyRequest"}}}},"responses":{"200":{"description":"The updated survey.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Survey"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```
## Upload a cover image
> Uploads a cover image for the survey.
```json
{"openapi":"3.1.0","info":{"title":"Surveys","version":"v14"},"tags":[{"name":"Surveys","description":"Create, read, update, and delete partner surveys."}],"servers":[{"url":"https://api.impact.com","description":"impact.com API"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic","description":"HTTP Basic authentication. Use your Account SID as the username and your Auth Token as the password.\n"}},"schemas":{"CoverImageUploadResponse":{"type":"object","properties":{"Status":{"type":"string"},"Body":{"type":"object","properties":{"Id":{"type":"integer","format":"int64"},"Name":{"type":"string"},"CoverImageUrl":{"type":"string"}}}}}},"responses":{"BadRequest":{"description":"Bad request — invalid request or validation failure."},"NotFound":{"description":"Resource not found."},"ServerError":{"description":"Internal server error."}}},"paths":{"/Advertisers/{AccountSid}/Programs/{ProgramId}/Surveys/{SurveyId}/CoverImage":{"post":{"tags":["Surveys"],"operationId":"uploadSurveyCoverImage","summary":"Upload a cover image","description":"Uploads a cover image for the survey.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["CoverImageFile"],"properties":{"CoverImageFile":{"type":"string","format":"binary","description":"Cover image file (.png, .jpg, .jpeg, .gif, .webp)."}}}}}},"responses":{"200":{"description":"The cover image was uploaded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CoverImageUploadResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://integrations.impact.com/brand-api-reference/reference/surveys-and-custom-fields/surveys.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.