---
title: "surveyRequest.create"
method: POST
path: "/surveyRequest.create"
tags: ["Survey Request"]
---

# surveyRequest.create

`POST /surveyRequest.create`

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.

**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.

**Requires the [`candidatesWrite`](authentication#permissions-surveyrequestcreate) permission.**

## Request body

- SurveyRequestCreateRequest
  - `candidateId` string, uuid, required — The id of the candidate to create a survey request for.
  - `applicationId` string, uuid, required — The id of the application to associate with the survey request.
  - `surveyFormDefinitionId` string, uuid, required — 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. Survey forms IDs can be obtained using the `surveyFormDefinition.list` endpoint.

## Response `200`

Responses from the surveyRequest.create endpoint

- union
  - SurveyRequestCreateSuccessResponse
    - `success` true, required
    - `results` SurveyRequest, required
      - `id` string, uuid, required — The unique identifier for the survey request
      - `surveyUrl` string, uri, required — The URL that the candidate can use to complete the survey
      - `surveyFormDefinitionId` string, uuid, required — The unique identifier for the survey form definition
      - `applicationId` string, uuid, required — The unique identifier for the associated application
      - `candidateId` string, uuid, required — The unique identifier for the associated candidate
  - ErrorResponse
    - `success` false, required
    - `errors` ErrorDetail[], required
      - `message` string, required
      - `parameter` string

---

[API](https://skmtc.net/ashbyhq/apis/ashby-api.md) · [All operations](https://skmtc.net/ashbyhq/apis/ashby-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ashbyhq/ashby-api/revisions/778b919dc743/schema)