openapi: 3.1.0
info:
  version: 1.0.0
  title: Ashby API Key Survey Request API
  description: The public API for accessing resources in your Ashby instance.
  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: "Use HTTP Basic Auth to authenticate with our API. You must send your API key with every request. \nPut your API key as the basic auth username and leave the password blank.\n"
    WebhookSignature:
      type: apiKey
      in: header
      name: Ashby-Signature
      description: '[Optional] If you provide a secret token when configuring your webhook, this will be used to create a digest of the JSON payload sent with each webhook request.

        The digest will be included in the request under the `Ashby-Signature` http header.


        It will look like this:

        `Ashby-Signature: sha256=f3124911d2956f10aa3a49c43a88bdf13bba846e94f0ae2bd7c034f90239bd04`


        The part before the = indicates the algorithm that was used to compute the hash digest.

        '