# Create a question

URL: /docs/api-reference/endpoints/project-questions/project.questions.create

`POST /project/{projectId}/questions`

Base URL: https://api.orvelt.com/v1

Add a guided question to a project.

API-key permission: `questions` create. Business sessions and resource-authorized OAuth tokens are also supported.

## Authentication

```json
[
  {
    "businessSession": []
  },
  {
    "businessApiKey": []
  },
  {
    "businessOAuth": []
  }
]
```

## Parameters

```json
[
  {
    "in": "path",
    "required": true,
    "name": "projectId",
    "schema": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    }
  }
]
```

## Request body

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "tags": {
            "minItems": 1,
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "Trust",
                "Reliability",
                "Experience",
                "Safety",
                "Personalization",
                "Fairness",
                "Identity",
                "Outcome"
              ]
            }
          },
          "isAutoTags": {
            "description": "Defaults to true when tags are omitted. Sending tags selects manual tagging.",
            "type": "boolean"
          },
          "priority": {
            "default": 50,
            "type": "integer",
            "minimum": 1,
            "maximum": 100
          },
          "isAutoPriority": {
            "default": true,
            "type": "boolean"
          },
          "question": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          },
          "answerMode": {
            "type": "string",
            "enum": [
              "text_only",
              "single_select",
              "multi_select"
            ]
          },
          "answers": {
            "default": {},
            "type": "object",
            "properties": {
              "options": {
                "minItems": 2,
                "maxItems": 6,
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 64
                    },
                    "option": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 200
                    },
                    "description": {
                      "type": "string",
                      "maxLength": 200
                    }
                  },
                  "required": [
                    "id",
                    "option"
                  ]
                }
              },
              "allowOther": {
                "type": "boolean"
              },
              "skippable": {
                "type": "boolean"
              },
              "layout": {
                "type": "string",
                "enum": [
                  "inline",
                  "stacked"
                ]
              },
              "chipPosition": {
                "type": "string",
                "enum": [
                  "left",
                  "right"
                ]
              },
              "otherPlaceholder": {
                "type": "string",
                "maxLength": 120
              },
              "freeTextPlaceholder": {
                "type": "string",
                "maxLength": 120
              },
              "freeTextMultiline": {
                "type": "boolean"
              }
            }
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "archived"
            ]
          },
          "responseVisibility": {
            "type": "string",
            "enum": [
              "default",
              "private"
            ],
            "description": "Whether answers can appear with the customer’s published opinion. Set when the question is created; it cannot be changed."
          }
        },
        "required": [
          "question",
          "answerMode",
          "status",
          "responseVisibility"
        ]
      }
    }
  }
}
```

## Responses

```json
{
  "200": {
    "description": "OK",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "question": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "familyId": {
                  "type": "string",
                  "format": "uuid",
                  "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                  "description": "Stable identity shared by every wording version of this question."
                },
                "version": {
                  "type": "integer",
                  "exclusiveMinimum": 0,
                  "maximum": 9007199254740991,
                  "description": "Wording version number within this question."
                },
                "question": {
                  "type": "string"
                },
                "answerMode": {
                  "type": "string",
                  "enum": [
                    "text_only",
                    "single_select",
                    "multi_select"
                  ]
                },
                "answers": {
                  "type": "object",
                  "properties": {
                    "options": {
                      "minItems": 2,
                      "maxItems": 6,
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "minLength": 1,
                            "maxLength": 64
                          },
                          "option": {
                            "type": "string",
                            "minLength": 1,
                            "maxLength": 200
                          },
                          "description": {
                            "type": "string",
                            "maxLength": 200
                          }
                        },
                        "required": [
                          "id",
                          "option"
                        ]
                      }
                    },
                    "allowOther": {
                      "type": "boolean"
                    },
                    "skippable": {
                      "type": "boolean"
                    },
                    "layout": {
                      "type": "string",
                      "enum": [
                        "inline",
                        "stacked"
                      ]
                    },
                    "chipPosition": {
                      "type": "string",
                      "enum": [
                        "left",
                        "right"
                      ]
                    },
                    "otherPlaceholder": {
                      "type": "string",
                      "maxLength": 120
                    },
                    "freeTextPlaceholder": {
                      "type": "string",
                      "maxLength": 120
                    },
                    "freeTextMultiline": {
                      "type": "boolean"
                    }
                  }
                },
                "tags": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "enum": [
                      "Trust",
                      "Reliability",
                      "Experience",
                      "Safety",
                      "Personalization",
                      "Fairness",
                      "Identity",
                      "Outcome"
                    ]
                  }
                },
                "priority": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 100
                },
                "isAutoPriority": {
                  "type": "boolean"
                },
                "isAutoTags": {
                  "type": "boolean"
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "active",
                    "archived"
                  ]
                },
                "responseVisibility": {
                  "type": "string",
                  "enum": [
                    "default",
                    "private"
                  ]
                },
                "createdAt": {
                  "type": "string",
                  "format": "date-time",
                  "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
                }
              },
              "required": [
                "id",
                "familyId",
                "version",
                "question",
                "answerMode",
                "answers",
                "tags",
                "priority",
                "isAutoPriority",
                "isAutoTags",
                "status",
                "responseVisibility",
                "createdAt"
              ]
            }
          },
          "required": [
            "question"
          ]
        }
      }
    }
  },
  "400": {
    "description": "Invalid request.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Http400Error"
        }
      }
    }
  },
  "401": {
    "description": "Authentication is required.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Http401Error"
        }
      }
    }
  },
  "403": {
    "description": "You do not have permission to perform this action., This action would exceed the current plan limit.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Http403Error"
        }
      }
    }
  },
  "404": {
    "description": "The requested resource was not found.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Http404Error"
        }
      }
    }
  },
  "409": {
    "description": "The requested resource has changed.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Http409Error"
        }
      }
    }
  },
  "429": {
    "description": "Too many requests., A delivery link was already emailed to this customer recently.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Http429Error"
        }
      }
    }
  },
  "503": {
    "description": "The service is temporarily unavailable.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Http503Error"
        }
      }
    }
  }
}
```

## Components

```json
{
  "securitySchemes": {
    "businessSession": {
      "type": "apiKey",
      "in": "cookie",
      "name": "orvelt-biz.session_token",
      "description": "An existing Business session. Browser requests must also pass origin and CSRF checks."
    },
    "businessApiKey": {
      "type": "apiKey",
      "in": "header",
      "name": "x-api-key",
      "description": "An organization API key. Keep keys on your server."
    },
    "businessOAuth": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "JWT",
      "description": "OAuth access token for the Business API resource. Requires live consent, per-resource access, and current membership."
    }
  },
  "schemas": {
    "UndefinedError": {
      "title": "UndefinedError",
      "type": "object",
      "properties": {
        "defined": {
          "const": false
        },
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "data": {}
      },
      "required": [
        "defined",
        "code",
        "message"
      ]
    },
    "UnexpectedHttpError": {
      "type": "object",
      "properties": {
        "defined": {
          "type": "boolean",
          "const": false
        },
        "code": {
          "type": "string"
        },
        "status": {
          "type": "number"
        },
        "message": {
          "type": "string"
        },
        "data": {}
      },
      "required": [
        "defined",
        "code",
        "status",
        "message"
      ]
    },
    "BadRequestError": {
      "type": "object",
      "properties": {
        "defined": {
          "type": "boolean",
          "const": true
        },
        "code": {
          "const": "BAD_REQUEST"
        },
        "status": {
          "const": 400
        },
        "message": {
          "type": "string",
          "default": "Invalid request."
        },
        "data": {}
      },
      "required": [
        "defined",
        "code",
        "status",
        "message"
      ]
    },
    "Http400Error": {
      "oneOf": [
        {
          "$ref": "#/components/schemas/BadRequestError"
        },
        {
          "$ref": "#/components/schemas/UnexpectedHttpError"
        }
      ]
    },
    "UnauthorizedError": {
      "type": "object",
      "properties": {
        "defined": {
          "type": "boolean",
          "const": true
        },
        "code": {
          "const": "UNAUTHORIZED"
        },
        "status": {
          "const": 401
        },
        "message": {
          "type": "string",
          "default": "Authentication is required."
        },
        "data": {}
      },
      "required": [
        "defined",
        "code",
        "status",
        "message"
      ]
    },
    "Http401Error": {
      "oneOf": [
        {
          "$ref": "#/components/schemas/UnauthorizedError"
        },
        {
          "$ref": "#/components/schemas/UnexpectedHttpError"
        }
      ]
    },
    "ForbiddenError": {
      "type": "object",
      "properties": {
        "defined": {
          "type": "boolean",
          "const": true
        },
        "code": {
          "const": "FORBIDDEN"
        },
        "status": {
          "const": 403
        },
        "message": {
          "type": "string",
          "default": "You do not have permission to perform this action."
        },
        "data": {}
      },
      "required": [
        "defined",
        "code",
        "status",
        "message"
      ]
    },
    "PlanLimitReachedError": {
      "type": "object",
      "properties": {
        "defined": {
          "type": "boolean",
          "const": true
        },
        "code": {
          "const": "PLAN_LIMIT_REACHED"
        },
        "status": {
          "const": 403
        },
        "message": {
          "type": "string",
          "default": "This action would exceed the current plan limit."
        },
        "data": {
          "type": "object",
          "properties": {
            "metric": {
              "type": "string",
              "enum": [
                "privateAnswersPerOrganizationMonth",
                "preverifiedLinksPerProjectMonth",
                "goalsPerProject",
                "activeQuestionsPerProject",
                "additionalTeamsPerOrganization",
                "membersPerAdditionalTeam",
                "knowledgebaseStorageBytes"
              ]
            },
            "currentUsage": {
              "type": "number",
              "minimum": 0
            },
            "limit": {
              "type": "number",
              "minimum": 0
            },
            "upgradePath": {
              "type": "string",
              "const": "/billing"
            }
          },
          "required": [
            "metric",
            "currentUsage",
            "limit",
            "upgradePath"
          ]
        }
      },
      "required": [
        "defined",
        "code",
        "status",
        "message",
        "data"
      ]
    },
    "Http403Error": {
      "oneOf": [
        {
          "$ref": "#/components/schemas/ForbiddenError"
        },
        {
          "$ref": "#/components/schemas/PlanLimitReachedError"
        },
        {
          "$ref": "#/components/schemas/UnexpectedHttpError"
        }
      ]
    },
    "NotFoundError": {
      "type": "object",
      "properties": {
        "defined": {
          "type": "boolean",
          "const": true
        },
        "code": {
          "const": "NOT_FOUND"
        },
        "status": {
          "const": 404
        },
        "message": {
          "type": "string",
          "default": "The requested resource was not found."
        },
        "data": {}
      },
      "required": [
        "defined",
        "code",
        "status",
        "message"
      ]
    },
    "Http404Error": {
      "oneOf": [
        {
          "$ref": "#/components/schemas/NotFoundError"
        },
        {
          "$ref": "#/components/schemas/UnexpectedHttpError"
        }
      ]
    },
    "ConflictError": {
      "type": "object",
      "properties": {
        "defined": {
          "type": "boolean",
          "const": true
        },
        "code": {
          "const": "CONFLICT"
        },
        "status": {
          "const": 409
        },
        "message": {
          "type": "string",
          "default": "The requested resource has changed."
        },
        "data": {}
      },
      "required": [
        "defined",
        "code",
        "status",
        "message"
      ]
    },
    "Http409Error": {
      "oneOf": [
        {
          "$ref": "#/components/schemas/ConflictError"
        },
        {
          "$ref": "#/components/schemas/UnexpectedHttpError"
        }
      ]
    },
    "TooManyRequestsError": {
      "type": "object",
      "properties": {
        "defined": {
          "type": "boolean",
          "const": true
        },
        "code": {
          "const": "TOO_MANY_REQUESTS"
        },
        "status": {
          "const": 429
        },
        "message": {
          "type": "string",
          "default": "Too many requests."
        },
        "data": {}
      },
      "required": [
        "defined",
        "code",
        "status",
        "message"
      ]
    },
    "LinkEmailCooldownError": {
      "type": "object",
      "properties": {
        "defined": {
          "type": "boolean",
          "const": true
        },
        "code": {
          "const": "LINK_EMAIL_COOLDOWN"
        },
        "status": {
          "const": 429
        },
        "message": {
          "type": "string",
          "default": "A delivery link was already emailed to this customer recently."
        },
        "data": {
          "type": "object",
          "properties": {
            "nextEligibleAt": {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
            }
          },
          "required": [
            "nextEligibleAt"
          ]
        }
      },
      "required": [
        "defined",
        "code",
        "status",
        "message",
        "data"
      ]
    },
    "Http429Error": {
      "oneOf": [
        {
          "$ref": "#/components/schemas/TooManyRequestsError"
        },
        {
          "$ref": "#/components/schemas/LinkEmailCooldownError"
        },
        {
          "$ref": "#/components/schemas/UnexpectedHttpError"
        }
      ]
    },
    "ServiceUnavailableError": {
      "type": "object",
      "properties": {
        "defined": {
          "type": "boolean",
          "const": true
        },
        "code": {
          "const": "SERVICE_UNAVAILABLE"
        },
        "status": {
          "const": 503
        },
        "message": {
          "type": "string",
          "default": "The service is temporarily unavailable."
        },
        "data": {}
      },
      "required": [
        "defined",
        "code",
        "status",
        "message"
      ]
    },
    "Http503Error": {
      "oneOf": [
        {
          "$ref": "#/components/schemas/ServiceUnavailableError"
        },
        {
          "$ref": "#/components/schemas/UnexpectedHttpError"
        }
      ]
    },
    "__schema0": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/__schema0"
          }
        },
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "$ref": "#/components/schemas/__schema0"
          }
        }
      ]
    }
  }
}
```