---
title: "Approve or reject a submission"
method: POST
path: "/api/v1/submissions/{id}/transition/"
tags: ["submissions"]
---

# Approve or reject a submission

`POST /api/v1/submissions/{id}/transition/`

Transition a submission to `APPROVED`, `REJECTED`, `PARTIALLY APPROVED`, `AWAITING REVIEW` or `SCREENED OUT`. Once the status is changed, it can not be restored to its previous value.

You can only transition a submission to PARTIALLY APPROVED or SCREENED OUT by:
  - setting up the study with the appropriate completion codes (only some workspaces have access to these features)
  - providing the correct completion code in the request body
  - providing the necessary data in the request body (to PARTIALLY APPROVE a submission)

Note this endpoint is idempotent, so if you make the same request twice, the second request will be ignored.

## Path parameters

- `id` string, required

## Headers

- `Authorization` string, required

## Request body

- SubmissionTransition
  - `action` 'APPROVE' | 'COMPLETE' | 'REJECT' | 'RETURN' | 'START' | 'SCREEN_OUT' | 'UNREJECT' | 'UNRETURN', required — The action that should be performed on the submission.
  - `message` string — Required if action is 'REJECT'. Message sent to the participant explaining the reason for the rejection. It must be at least 100 chars long.
  - `rejection_category` 'TOO_QUICKLY' | 'TOO_SLOWLY' | 'FAILED_INSTRUCTIONS' | 'INCOMP_LONGITUDINAL' | 'FAILED_CHECK' | 'LOW_EFFORT' | 'MALINGERING' | 'NO_CODE' | 'BAD_CODE' | 'NO_DATA' | 'UNSUPP_DEVICE' | 'OTHER' — Required if action is 'REJECT', it sums as the category of the rejection.
  - `completion_code` string — Required if the action is 'COMPLETE'. The completion code must match a value provided when creating the study, and the actor must have been set to `researcher`. Any actions that were provided during the set up of the completion code (e.g. automatically approve) will then be carried out.
  - `completion_code_data` SubmissionTransitionCompletionCodeData — Required if the action is 'COMPLETE' and the code has the action "DYNAMIC_PAYMENT" associated with it.
    - `percentage_of_reward` number, double — Required if the code is for a DYNAMIC_PAYMENT action. Must be between 8 - 99 (inclusive).
    - `message_to_participant` string — Optional message to the participant to be sent alongside a dynamic payment.

## Response `200`

OK

- Submission
  - `id` string, required — The id of the submission
  - `completed_at` string, nullable — The time the submission was completed at.
  - `entered_code` string, nullable — The completion code used by the participant to complete the study.
  - `participant` string — Participant id.
  - `started_at` string, required — The date and time that the user started the submission (UTC)
  - `status` 'ACTIVE' | 'APPROVED' | 'AWAITING REVIEW' | 'REJECTED' | 'RESERVED' | 'RETURNED' | 'TIMED-OUT' | 'SCREENED OUT' | 'UNKNOWN', required — The current status of the submission
  - `study_id` string, required — Study id.

## Other responses

- `400` — Error

---

[API](https://skmtc.net/prolific/apis/api-reference.md) · [All operations](https://skmtc.net/prolific/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/prolific/api-reference/versions/dc6f073a9827/schema)