openapi: 3.1.0
info:
  version: 1.0.0
  title: Ashby API Key Survey Request API
  description: Complete public API for accessing resources in your Ashby instance. Includes applications, candidates, jobs, interviews, offers, surveys, custom fields, organization metadata, files, reports, approvals, and webhooks.
  contact:
    name: Ashby Support
    url: https://app.ashbyhq.com/support
    email: support@ashbyhq.com
servers:
- url: https://api.ashbyhq.com
security:
- BasicAuth: []
tags:
- name: Survey Request
paths:
  /surveyRequest.create:
    post:
      summary: surveyRequest.create
      description: "This endpoint generates a survey request and returns a survey URL. You can send this URL to a candidate to allow them to complete a survey. \n\n**Requires the [`candidatesWrite`](authentication#permissions-surveyrequestcreate) permission.**\n\n**Note that calling this endpoint will not automatically email the survey to the candidate.** It simply creates the request and gives you a URL to share with a candidate.\n"
      operationId: surveyRequestCreate
      tags:
      - Survey Request
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - candidateId
              - applicationId
              - surveyFormDefinitionId
              properties:
                candidateId:
                  allOf:
                  - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                  - description: The id of the candidate to create a survey request for.
                applicationId:
                  allOf:
                  - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                  - description: The id of the application to associate with the survey request.
                surveyFormDefinitionId:
                  allOf:
                  - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                  - description: "The ID of the survey form that the candidate will see when they visit the URL returned in the `surveyURL` property of the API response. \nSurvey forms IDs can be obtained using the `surveyFormDefinition.list` endpoint. \n"
      responses:
        '200':
          description: Responses for the surveyRequest.create endpoint
          content:
            application/json:
              schema:
                oneOf:
                - title: Success response
                  allOf:
                  - $ref: '#/paths/~1job.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/0'
                  - type: object
                    properties:
                      results:
                        type: object
                        properties:
                          id:
                            allOf:
                            - description: 'The id of the survey request

                                '
                            - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                          candidateId:
                            allOf:
                            - description: 'The id of the candidate the survey request is for

                                '
                            - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                          applicationId:
                            allOf:
                            - description: 'The id of the application associated with the survey request

                                '
                            - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                          surveyFormDefinitionId:
                            allOf:
                            - description: 'The id of the survey form the candidate will fill out when they take the survey

                                '
                            - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                          surveyUrl:
                            type: string
                            example: https://you.ashbyhq.com/ashby/survey/3f20b73e-abec-4d62-ba6f-04f2f985f7dd
                            description: 'The URL that the candidate can visit to take the survey.

                              '
                        required:
                        - id
                        - candidateId
                        - applicationId
                        - surveyFormDefinitionId
                        - surveyUrl
                    required:
                    - results
                - title: Error response
                  $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /surveyRequest.list:
    post:
      summary: surveyRequest.list
      description: 'Lists all survey requests.


        See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for detailed usage examples.


        **Requires the [`candidatesRead`](authentication#permissions-surveyRequestList) permission.**

        '
      operationId: surveyRequestList
      tags:
      - Survey Request
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/paths/~1opening.list/post/requestBody/content/application~1json/schema'
              - type: object
                properties:
                  surveyType:
                    allOf:
                    - description: Returns only the survey requests of the given type. Currently, only `CandidateExperience` is supported.
                    - type: string
                    - enum:
                      - CandidateExperience
                  applicationId:
                    allOf:
                    - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                    - description: If provided, only returns the offers for the application with the supplied id
                  candidateId:
                    allOf:
                    - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                    - description: If provided, only returns the offers for the candidate with the supplied id
                required:
                - surveyType
      responses:
        '200':
          description: Responses for the surveyRequest.list endpoint
          content:
            application/json:
              schema:
                oneOf:
                - allOf:
                  - $ref: '#/paths/~1job.list/post/responses/200/content/application~1json/schema/oneOf/0/allOf/0'
                  - properties:
                      results:
                        type: array
                        items:
                          $ref: '#/paths/~1surveyRequest.create/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results'
                  required:
                  - results
                - $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Auth. Send your Ashby API key as the username and leave the password blank.
    WebhookSignature:
      type: apiKey
      in: header
      name: Ashby-Signature
      description: HMAC-SHA256 signature of the webhook payload, used to verify webhook authenticity.