> For the complete documentation index, see [llms.txt](https://integrations.impact.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://integrations.impact.com/brand-api-reference/reference/surveys-and-custom-fields/models.md).

# Models

## The Enumeration object

```json
{"openapi":"3.1.0","info":{"title":"Surveys","version":"v14"},"components":{"schemas":{"Enumeration":{"type":"object","description":"An allowed value for a selection-based custom field.","properties":{"Id":{"type":"integer","format":"int64"},"Value":{"type":"string"}}}}}}
```

## The CustomField object

```json
{"openapi":"3.1.0","info":{"title":"Surveys","version":"v14"},"components":{"schemas":{"CustomField":{"type":"object","description":"A custom field that defines the data collection type for a survey question.\n","properties":{"Id":{"type":"integer","format":"int64"},"Name":{"type":"string"},"Description":{"type":"string"},"DisplayType":{"type":"string","description":"The display type.","enum":["Paragraph","Multi-select","Dropdown list","Single-select","Date picker","Number","File"]},"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"}}}}}}
```

## The Question object

```json
{"openapi":"3.1.0","info":{"title":"Surveys","version":"v14"},"components":{"schemas":{"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.\n","properties":{"Id":{"type":"integer","format":"int64"},"Name":{"type":"string"},"Description":{"type":"string"},"DisplayType":{"type":"string","description":"The display type.","enum":["Paragraph","Multi-select","Dropdown list","Single-select","Date picker","Number","File"]},"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"}}}}}}
```

## The SurveySummary object

```json
{"openapi":"3.1.0","info":{"title":"Surveys","version":"v14"},"components":{"schemas":{"SurveySummary":{"type":"object","properties":{"Id":{"type":"integer","format":"int64"},"Name":{"type":"string"},"Description":{"type":"string"},"StartDate":{"type":"string","format":"date-time"},"EndDate":{"type":["string","null"],"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"}}}}}}
```

## The Survey object

```json
{"openapi":"3.1.0","info":{"title":"Surveys","version":"v14"},"components":{"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","null"],"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.\n","properties":{"Id":{"type":"integer","format":"int64"},"Name":{"type":"string"},"Description":{"type":"string"},"DisplayType":{"type":"string","description":"The display type.","enum":["Paragraph","Multi-select","Dropdown list","Single-select","Date picker","Number","File"]},"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"}}}}}}
```

## The SurveyListResponse object

```json
{"openapi":"3.1.0","info":{"title":"Surveys","version":"v14"},"components":{"schemas":{"SurveyListResponse":{"type":"object","properties":{"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","null"],"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"}}}}}}
```

## The CreateQuestion object

```json
{"openapi":"3.1.0","info":{"title":"Surveys","version":"v14"},"components":{"schemas":{"CreateQuestion":{"type":"object","required":["Question","CustomFieldId"],"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."}}}}}}
```

## The CreateSurveyRequest object

```json
{"openapi":"3.1.0","info":{"title":"Surveys","version":"v14"},"components":{"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. Supported file extensions: gif, jpg, png, and webp.\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. Group names are case-sensitive.\n","items":{"type":"string"}},"Questions":{"type":"array","minItems":1,"description":"List of questions to create. At least one question is required to create a survey.\n","items":{"$ref":"#/components/schemas/CreateQuestion"}}}},"CreateQuestion":{"type":"object","required":["Question","CustomFieldId"],"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."}}}}}}
```

## The UpdateQuestion object

```json
{"openapi":"3.1.0","info":{"title":"Surveys","version":"v14"},"components":{"schemas":{"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."}}}}}}
```

## The UpdateSurveyRequest object

```json
{"openapi":"3.1.0","info":{"title":"Surveys","version":"v14"},"components":{"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. Group names are case-sensitive.\n","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."}}}}}}
```

## The SurveyResponse object

```json
{"openapi":"3.1.0","info":{"title":"Surveys","version":"v14"},"components":{"schemas":{"SurveyResponse":{"type":"object","properties":{"Id":{"type":"integer"},"QuestionId":{"type":"integer","format":"int64"},"Question":{"type":"string"},"PartnerId":{"type":"integer","format":"int64"},"PartnerName":{"type":"string"},"UserId":{"type":"integer","format":"int64"},"UserEmail":{"type":"string"},"ResponseValue":{"type":"string","description":"The response value. For enumeration-based custom fields, this is a comma-separated list of enumeration IDs that resolve to display values via the custom field's enumeration list.\n"},"ResponseDate":{"type":"string","format":"date-time"},"CustomFieldId":{"type":"integer","format":"int64"}}}}}}
```

## The SurveyResponseListResponse object

```json
{"openapi":"3.1.0","info":{"title":"Surveys","version":"v14"},"components":{"schemas":{"SurveyResponseListResponse":{"type":"object","properties":{"Responses":{"type":"array","items":{"$ref":"#/components/schemas/SurveyResponse"}}}},"SurveyResponse":{"type":"object","properties":{"Id":{"type":"integer"},"QuestionId":{"type":"integer","format":"int64"},"Question":{"type":"string"},"PartnerId":{"type":"integer","format":"int64"},"PartnerName":{"type":"string"},"UserId":{"type":"integer","format":"int64"},"UserEmail":{"type":"string"},"ResponseValue":{"type":"string","description":"The response value. For enumeration-based custom fields, this is a comma-separated list of enumeration IDs that resolve to display values via the custom field's enumeration list.\n"},"ResponseDate":{"type":"string","format":"date-time"},"CustomFieldId":{"type":"integer","format":"int64"}}}}}}
```

## The CoverImageUploadResponse object

```json
{"openapi":"3.1.0","info":{"title":"Surveys","version":"v14"},"components":{"schemas":{"CoverImageUploadResponse":{"type":"object","properties":{"Status":{"type":"string"},"Body":{"description":"The full survey detail with the updated cover image URL — same structure as the Get a Survey response.\n","$ref":"#/components/schemas/Survey"}}},"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","null"],"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.\n","properties":{"Id":{"type":"integer","format":"int64"},"Name":{"type":"string"},"Description":{"type":"string"},"DisplayType":{"type":"string","description":"The display type.","enum":["Paragraph","Multi-select","Dropdown list","Single-select","Date picker","Number","File"]},"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"}}}}}}
```

## The StatusResponse object

```json
{"openapi":"3.1.0","info":{"title":"Surveys","version":"v14"},"components":{"schemas":{"StatusResponse":{"type":"object","properties":{"Status":{"type":"string"}}}}}}
```

## The ErrorResponse object

```json
{"openapi":"3.1.0","info":{"title":"Surveys","version":"v14"},"components":{"schemas":{"ErrorResponse":{"type":"object","description":"Error envelope returned by custom field write operations.","properties":{"Status":{"type":"string"},"Message":{"type":"string","description":"Human-readable error description."}}}}}}
```

## The CustomFieldListResponse object

```json
{"openapi":"3.1.0","info":{"title":"Surveys","version":"v14"},"components":{"schemas":{"CustomFieldListResponse":{"type":"object","properties":{"CustomFields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}}}},"CustomField":{"type":"object","description":"A custom field that defines the data collection type for a survey question.\n","properties":{"Id":{"type":"integer","format":"int64"},"Name":{"type":"string"},"Description":{"type":"string"},"DisplayType":{"type":"string","description":"The display type.","enum":["Paragraph","Multi-select","Dropdown list","Single-select","Date picker","Number","File"]},"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"}}}}}}
```

## The CreateCustomFieldRequest object

```json
{"openapi":"3.1.0","info":{"title":"Surveys","version":"v14"},"components":{"schemas":{"CreateCustomFieldRequest":{"type":"object","required":["Name","DisplayType"],"properties":{"Name":{"type":"string","description":"Name of the custom field."},"Description":{"type":"string","description":"Description of the custom field."},"DisplayType":{"type":"string","description":"The display type for the custom field. Determines what kind of data\nthe field collects:\n\n- **Paragraph** — Open-ended questions that allow unique answers.\n- **Multi-select** — Questions that may include multiple answers. Respondents can select one or more options. *(enumeration-based)*\n- **Dropdown list** — Questions that require respondents to select one option from a dropdown menu. *(enumeration-based)*\n- **Single-select** — Questions that require respondents to select only one option from a list. *(enumeration-based)*\n- **Date picker** — Questions that require a date as an answer.\n- **Number** — Questions that require a number as an answer.\n- **File** — Questions that require an attachment from the partner.\n","enum":["Paragraph","Multi-select","Dropdown list","Single-select","Date picker","Number","File"]},"Enumerations":{"type":"array","description":"List of option values, required for enumeration-based display types (dropdown list, single-select, multi-select). Provide each option as a separate array item.\n","items":{"type":"string"}}}}}}}
```

## The UpdateCustomFieldRequest object

```json
{"openapi":"3.1.0","info":{"title":"Surveys","version":"v14"},"components":{"schemas":{"UpdateCustomFieldRequest":{"type":"object","description":"Only the fields provided are updated.","properties":{"Name":{"type":"string","description":"Updated name of the custom field."},"Description":{"type":"string","description":"Updated description of the custom field."}}}}}}
```

## The CustomFieldEnvelope object

```json
{"openapi":"3.1.0","info":{"title":"Surveys","version":"v14"},"components":{"schemas":{"CustomFieldEnvelope":{"type":"object","description":"Success envelope returned when a custom field is created.","properties":{"Status":{"type":"string"},"Body":{"$ref":"#/components/schemas/CustomField"}}},"CustomField":{"type":"object","description":"A custom field that defines the data collection type for a survey question.\n","properties":{"Id":{"type":"integer","format":"int64"},"Name":{"type":"string"},"Description":{"type":"string"},"DisplayType":{"type":"string","description":"The display type.","enum":["Paragraph","Multi-select","Dropdown list","Single-select","Date picker","Number","File"]},"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"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://integrations.impact.com/brand-api-reference/reference/surveys-and-custom-fields/models.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.