---
title: Change Requests
slug: api/change-requests
description: This document provides detailed information and instructions on how to retrieve change request templates and create change requests using API endpoints. It covers the required parameters and their accepted values for both types of requests, as well as the
createdAt: 2023-07-04T09:11:30.847Z
---

## Retrieve a list of Change Request Templates

Returns a list of Change Request Templates including information about the states of the templates.

:::CodeblockTabs
Endpoint

```json
GET   {baseUrl}/fws/api/changerequest/template/listtemplates
```
:::

**Example response:**

```json
[
  {
    "uuid": “01234567-89ab-cdef-0123-456789abcdef”,
    "name": "",
    "context": "STANDARD",
    "active": true,
    "customProperties": [
      {
        "name": "",
        "propertyType": "TEXT",
        "mandatory": true,
        "options": [
          "", ...
        ],
        "multiple": true,
        "orderNumber": 1
      }
    ],
    "states": [
      {
        "uuid": "01234567-89ab-cdef-0123-456789abcdef",
        "name": "",
        "approvalLabels": [
          "", ...
        ],
        "category": "NOT_STARTED",
        "transitionsTo": [
          {
            "uuid": "01234567-89ab-cdef-0123-456789abcdef",
            "requiresApproval": true
          }, ...
        ]
      }
    ],
    "initialState": "01234567-89ab-cdef-0123-456789abcdef"
  }, ...
]

```

| Response Parameters | Possible Values                                                         |
| ------------------- | ----------------------------------------------------------------------- |
| `context`           | NONE, STANDARD, STUDY, CONTAINER, STANDARD\_ASSET, STUDY\_ASSET, ASSET  |
| `category`          | NOT\_STARTED, COMPLETED, WILL\_NOT\_DO, IN\_REVIEW, IN\_PROGRESS, DRAFT |
| `propertyType`      | TEXT, NOTE, NUMBER, DATETIME, SELECT, URL                               |

`initialState `is an optional field that is returned if populated in the ryze UI.
`options`, `multiple `and `orderNumber `are optional fields in the `customProperties`and are returned depending on configuration in ryze.

**Errors:**

See [Common Errors](https://docs.formedix.com/api/common-errors)

## Create a Change Request

Creates a new Change Request if the template ID specified both exists and is active. Any container AIDs or asset AIDs specified are checked for existence before being created. Any specified custom properties are checked against the change request template.

:::CodeblockTabs
Endpoint

```json
POST   {baseUrl}/fws/api/changerequest
```
:::

:::CodeblockTabs
Request

```json

{
 "templateID": "01234567-89ab-cdef-0123-456789abcdef",
 "title": "",
 "description": "",
 "dueDate": "ccyymmddThhmmssZ",
 "containerAIDs": [
   "01234567-89ab-cdef-0123-456789abcdef", ...
 ],
 "assets": [
   {
     "containerAID": "01234567-89ab-cdef-0123-456789abcdef",
     "assetAID": "01234567-89ab-cdef-0123-456789abcdef"
   }, ...
 ],
 "customProperties": [
   {
     "name": "",
     "values": ["", ...],
     "propertyType": "TEXT",
     "mandatory": true,
     "orderNumber": 1
   }, ...
 ]
}

```
:::

| Request Parameters | Values                                    |
| ------------------ | ----------------------------------------- |
| `dueDate`          | \[Optional]                               |
| `containers`       | \[Optional]                               |
| `assets`           | \[Optional]                               |
| `customProperties` | \[Optional]                               |
| `dueDate`          | \[Optional]                               |
| `assetAID`         | \[Optional]                               |
| `‘propertyType’`   | TEXT, NOTE, NUMBER, DATETIME, SELECT, URL |

The context set on the Change Request Template (NONE, STANDARD, STUDY, CONTAINER, STANDARD\_ASSET, STUDY\_ASSET, ASSET) impacts which properties should be sent when creating the Change Request. If request includes properties that are not permitted within the context, an `invalid_context_details `error is returned.

The Change Request Template is configured in ryze, **Admin > Repository > Change Requests**.

If the context is NONE, then it is expected that there will be no assets or containers specified in the request.

If the context is CONTAINER and the user has chosen to supply containerAIDs, then there must be no assets specified.&#x20;

If the context is set to STANDARD or STUDY, then those containers must be of that container type.

If the context is ASSETS and the user chooses to supply assets, then both the assets field and the containerAIDs fields must be populated. The containerAIDs and the containerAID fields in the assets field must match. If the context is set to STANDARD\_ASSET or STUDY\_ASSET, then the assets specified in the request must be from one of those container types.

**Example response:**

```json
{
  "id": "CR-0"
}
```

Related requests: [Retrieve a list of Change Request Templates](#)

**Errors:**

| **HTTP Status** | **Error Code**                               |                                                            |
| --------------- | -------------------------------------------- | ---------------------------------------------------------- |
| 400             | invalid\_template\_id                        | Badly formatted **templateID**.                            |
| 404             | unknown\_template                            | Template not found for **templateID**.                     |
| 400             | template\_inactive                           | Template not activated.                                    |
| 400             | change\_request\_custom\_properties\_invalid | Invalid custom properties for template.                    |
| 400             | invalid\_container\_aid                      | Badly formatted container AID.                             |
| 404             | unknown\_container                           | Container not found for AID.                               |
| 400             | invalid\_asset\_aid                          | Badly formatted asset AID.                                 |
| 400             | invalid\_context\_details                    | Incorrect container or asset details for Template Context. |
| 404             | unknown\_asset                               | Asset not found for AID.                                   |

See also [Common Errors](https://docs.formedix.com/api/common-errors)

## Retrieve Change Request Details

Retrieve the details of a Change Request with the specified ID.

:::CodeblockTabs
Endpoint

```text
GET {baseUrl}/fws/api/changerequest/:id
```
:::

:::CodeblockTabs
Response

```json
{
  "id":"CR-1",
  "title": "",
  "description": "",
  "created": “ccyymmddThhmmssZ”,
  "dueDate": “ccyymmddThhmmssZ”,
  "customProperties": [
    {
      "name": "",
      "values": ["", ...],
      "propertyType": "TEXT",
      "mandatory": true,
      "orderNumber": 1
    }, ...
  ],
  "updated": “ccyymmddThhmmssZ”,
  "templateID": "01234567-89ab-cdef-0123-456789abcdef",
  "templateName": "",
  "templateContext": "STANDARD",
  "stateID": "01234567-89ab-cdef-0123-456789abcdef",
  "stateName": "",
  "stateCategory": "NOT_STARTED",
  "approvers": [
    {
      "label": "",
      "username": "",
      "isApproved": true
    }, ...
  ],
  "owner": "",
  "assignee": "",
  "containers": [
    {
      "aid": "01234567-89ab-cdef-0123-456789abcdef",
      "label": "",
      "version": 1,
      "containerType": "STANDARD"
    }, ...
  ],
  "assets": [
    {
      "container": {
        "aid": "01234567-89ab-cdef-0123-456789abcdef",
        "label": "",
        "version": 1,
        "containerType": "STANDARD"
      }, 
      "asset": {
        "aid": "01234567-89ab-cdef-0123-456789abcdef",
        "assetType": "FORM",
        "label": ""
      }
    }, ...
  ],
  "completedVersions": [
    {
      "container": {
        "aid": "01234567-89ab-cdef-0123-456789abcdef",
        "label": "",
        "version": 1,mand
        "containerType": "STANDARD"
      }, 
      "asset": {
        "aid": "01234567-89ab-cdef-0123-456789abcdef",
        "assetType": "FORM",
        "label": ""
      }
    }, ...
  ],
  "comments": [ 
    {
      "uuid": "01234567-89ab-cdef-0123-456789abcdef",
      "username": "",
      "at": “ccyymmddThhmmssZ”,
      "comment": ""
    }, ...
  ],
  “fileReferences”: [
    {
      “uuid”: “01234567-89ab-cdef-0123-456789abcdef”,
      “path”: “”
    }, …
  ]
}

```
:::

| **Request Parameters**          | **Accepted Values**                                                                                                                                                                                |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `propertyType`                  | TEXT, NOTE, NUMBER, DATETIME, SELECT, URL                                                                                                                                                          |
| `templateContext`               | NONE, STANDARD, STUDY, CONTAINER, STANDARD\_ASSET, STUDY\_ASSET, ASSET                                                                                                                             |
| `stateCategory`                 | NOT\_STARTED, COMPLETED, WILL\_NOT\_DO, IN\_REVIEW, IN\_PROGRESS, DRAFT                                                                                                                            |
| `containerType`                 | STANDARD, STUDY                                                                                                                                                                                    |
| `assetType`                     | VISIT\_SCHEDULE, VISIT, FORM, SECTION, QUESTION, CONDITION, METHOD, UNIT, DATASET, VARIABLE, VALUE, SELECTION\_CRITERIA, RESULT\_DISPLAY, ANALYSIS\_RESULT, TERMINOLOGY, TERM, COMMENT, FILE, LINK |
| `dueDate`                       | \[Optional]                                                                                                                                                                                        |
| `updated`                       | \[Optional]                                                                                                                                                                                        |
| `templateID`                    | \[Optional]                                                                                                                                                                                        |
| `templateName`                  | \[Optional]                                                                                                                                                                                        |
| `templateContext`               | \[Optional]                                                                                                                                                                                        |
| `stateID`                       | \[Optional]                                                                                                                                                                                        |
| `stateName`                     | \[Optional]                                                                                                                                                                                        |
| `stateCategory`                 | \[Optional]                                                                                                                                                                                        |
| `assignee `                     | \[Optional]                                                                                                                                                                                        |
| `customProperties > mandatory ` | \[Optional]                                                                                                                                                                                        |
| `assets > asset`                | \[Optional]                                                                                                                                                                                        |
| `completedVersions > asset`     | \[Optional]                                                                                                                                                                                        |
| `comments > username`           | \[Optional]                                                                                                                                                                                        |

When creating a change request and sending container information, only a container AID is specified. When retrieving a change request, theT container information received contains the AID and the latest version for that container.

**Errors:**

| **HTTP Status** | **Error Code**           |                                                |
| --------------- | ------------------------ | ---------------------------------------------- |
| 404             | unknown\_change\_request | Change request not found for specified **id**. |
| 404             | change\_request\_deleted | Change request is in a deleted state.          |

See also [Common Errors](https://docs.formedix.com/api/common-errors)

## Add Approver to Change Request State Transition

:::CodeblockTabs
Request

```text
PUT {baseUrl}/fws/api/changerequest/:crID/approver/:crsUUID/:label/:userUUID
```
:::

| **Request Parameters** | **Accepted Values**                                   |
| ---------------------- | ----------------------------------------------------- |
| `crID `                | Change Request ID                                     |
| `crsUUID `             | Change Request State ID                               |
| `label `               | Label of Change Request State for user to be added as |
| `userUUID `            | UUID of the user being added                          |

Add a user with the specified UUID as a Change Request State Transition approver for the specified label.

:::CodeblockTabs
Response

```json
{}
```
:::

Related requests:
**[List Users](https://docs.formedix.com/api/users#iKNOH)**

**Errors:**

| **HTTP Status** | **Error Code**                        |                                                                  |
| --------------- | ------------------------------------- | ---------------------------------------------------------------- |
| 404             | unknown\_change\_request              | Change Request Not Found for **crID**.                           |
| 404             | change\_request\_deleted              | Change request has been deleted.                                 |
| 400             | invalid\_change\_request\_state\_uuid | Change Request State **crsUUID** Invalid format.                 |
| 404             | unknown\_change\_request\_state       | Change Request State not found for **crsUUID**.                  |
| 400             | invalid\_approval\_label              | Invalid **label** for specified change request state transition. |
| 400             | invalid\_user\_id                     | Invalid format for **userUUID**.                                 |
| 404             | unknown\_user                         | User not found for given **userUUID**.                           |

See also [Common Errors](https://docs.formedix.com/api/common-errors)

## Remove Approver from Change Request State Transition

Remove a User with the specified UUID from a Change Request State Transition for the specified label.

:::CodeblockTabs
Request

```text
DELETE {baseUrl}/fws/api/changerequest/:crID/approver/:crsUUID/:label/:userUUID
```
:::

| R**equest Parameters** | **Accepted Values**                                   |
| ---------------------- | ----------------------------------------------------- |
| `crID `                | Change Request ID                                     |
| `crsUUID `             | Change Request State ID                               |
| `label `               | Label of Change Request State for user to be added as |
| `userUUID `            | UUID of the user being added                          |



:::CodeblockTabs
Response

```text
{}
```
:::

Related requests:
**[List Users](https://docs.formedix.com/api/users#iKNOH)**

**Errors:**

| **HTTP Status** | **Error Code**                        |                                                                              |
| --------------- | ------------------------------------- | ---------------------------------------------------------------------------- |
| 404             | unknown\_change\_request              | Change Request Not Found for **crID**.                                       |
| 404             | change\_request\_deleted              | Change request has been deleted.                                             |
| 400             | invalid\_change\_request\_state\_uuid | Change Request State **crsUUID** Invalid format.                             |
| 404             | unknown\_change\_request\_state       | Change request state not found for **crsUUID**.                              |
| 400             | invalid\_approval\_label              | Invalid **label** for specified Change Request State Transition.             |
| 400             | invalid\_user\_id                     | Invalid format for the **userUUID**.                                         |
| 404             | unknown\_user                         | User not found for the specified **userUUID**.                               |
| 404             | approver\_not\_assigned               | User doesn’t exist on Change Request as an approver.                         |
| 400             | change\_request\_already\_approved    | Trying to remove a user that has already approved change request transition. |

See also [Common Errors](https://docs.formedix.com/api/common-errors)

## Delete a Change Request

Delete a Change Request with the specified ID.

:::CodeblockTabs
Request

```text
DELETE {baseUrl}/fws/api/changerequest/:crID
```
:::



:::CodeblockTabs
Response

```text
{}
```
:::

**Related requests:**

[Create a Change Request](https://docs.formedix.com/api/change-requests#MUJ6B)

**Errors:**

| **HTTP Status** | **Error Code**           |                                      |
| --------------- | ------------------------ | ------------------------------------ |
| 404             | unknown\_change\_request | Change Request Not Found for **id**. |

See also [Common Errors](https://docs.formedix.com/api/common-errors)

## Transition Change Request State

Transitions the Change Request to the Change Request state with the specified state UUID. Will validate that both the change request and the change request state for the specified IDs exist before transitioning.

:::CodeblockTabs
Request

```text
PUT {baseUrl}/fws/api/changerequest/:crID/transition/:crsUUID
```
:::

:::CodeblockTabs
Response

```text
{}
```
:::

**Errors:**

| **HTTP Status** | **Error Code**                        |                                                  |
| --------------- | ------------------------------------- | ------------------------------------------------ |
| 404             | unknown\_change\_request              | Change Request Not Found for **crID**.           |
| 400             | invalid\_change\_request\_state\_uuid | Change Request State **crsUUID** invalid format. |
| 404             | change\_request\_deleted              | Change request has been deleted.                 |
| 404             | unknown\_change\_request\_state       | Change request state not found for **crsUUID**.  |

See also [Common Errors](https://docs.formedix.com/api/common-errors)

## Approve a Change Request State Transition

Transitions the Change Request to the Change Request state with the specified state UUID. Will validate that both the change request and the change request state for the specified IDs exist before transitioning.

:::CodeblockTabs
Request

```text
PUT {baseUrl}/fws/api/changerequest/:crID/approve/:label/:userID
```
:::

:::CodeblockTabs
Response

```text
{}
```
:::

Related requests:
**[List Users](https://docs.formedix.com/api/users#iKNOH)**

**Errors:**

| **HTTP Status** | **Error Code**           |                                                            |
| --------------- | ------------------------ | ---------------------------------------------------------- |
| 404             | unknown\_change\_request | Change Request not found for specified **crID**.           |
| 400             | invalid\_user\_id        | **userID** is Invalid Format.                              |
| 404             | change\_request\_deleted | Change request has been deleted.                           |
| 404             | unknown\_user            | User not found for specified **userID**.                   |
| 400             | invalid\_user            | User is either not enabled or awaiting activation.         |
| 400             | invalid\_approval\_label | Invalid **label** for specified change request transition. |
| 400             | approver\_not\_assigned  | User trying to be approved is not assigned.                |

See also [Common Errors](https://docs.formedix.com/api/common-errors)

## Associate an uploaded file to a change request

:::CodeblockTabs
Endpoint

```json
PUT {baseUrl}/fws/api/changerequest/:crID/file

```
:::

Allows the user to associate a previously uploaded file (Add a temporary file) to the change request with the supplied crID. The uuid and path supplied in the request will be the same values as the ‘Add a temporary file’ call

:::CodeblockTabs
Request

```text

{
  "uuid": "01234567-89ab-cdef-0123-456789abcdef",
  "path": ""
}

```
:::

:::CodeblockTabs
Response

```text
{
  "uuid": "01234567-89ab-cdef-0123-456789abcdef",
  "path": ""
}
```
:::

Related requests:
[Add a temporary file](https://docs.formedix.com/api/general#9mYwV)

**Errors:**

| **HTTP Status** | **Error Code**            |                                                      |
| --------------- | ------------------------- | ---------------------------------------------------- |
| 400             | invalid\_file\_id\_format | The **id** passed in the request isn’t a valid UUID. |
| 404             | unknown\_change\_request  | Change request not found for specified **id**.       |
| 404             | unknown\_file             | Can’t find previously uploaded file.                 |
| 404             | change\_request\_deleted  | Change Request has been deleted.                     |

See also [Common Errors](https://docs.formedix.com/api/common-errors)

## Request a change request files download

Allows the user to request the preparation of files associated with a change request for download. Where `crID ` is the change request and `fileID ` is the file associated with that change request.

:::CodeblockTabs
Endpoint

```json
GET {baseUrl}/fws/api/changerequest/:crID/file/:fileID

```
:::

:::CodeblockTabs
Response

```text
{
  "uuid": "01234567-89ab-cdef-0123-456789abcdef"
}
```
:::

**Related requests:**

[Retrieve a previously prepared file](https://docs.formedix.com/api/general#W_vMw)

**Errors:**

| **HTTP Status** | **Error Code**           |                                                  |
| --------------- | ------------------------ | ------------------------------------------------ |
| 404             | unknown\_change\_request | Change request not found for specified **crID**. |
| 400             | invalid\_file\_id        | **fileID** not correct format.                   |
| 404             | unknown\_file            | File not found for **fileID** specified.         |
| 404             | change\_request\_deleted | Change request has been deleted.                 |

See also [Common Errors](https://docs.formedix.com/api/common-errors)

## Update a Change request

Allows a user to update a change request with the specified ID.

:::CodeblockTabs
Endpoint

```json
PUT {baseUrl}/fws/api/changerequest/:crID
```
:::

:::CodeblockTabs
Request

```text
{
  "title": "",
  "description": "",
  "dueDate": "ccyymmddThhmmssZ",
  "containerAIDs": [
    "", ...
  ],
  "assets": [
    {
      "containerAID": "",
      "assetAID": ""
    }, ...
  ],
  "customProperties": [
    {
      "name": "",
      "values": ["", ...],
      "propertyType": "NUMBER",
      "mandatory": true,
      "orderNumber": 1
    }, ...
  ],
  "completedVersions": [
    {
      "container": {
        "aid": "",
        "version": 1
      },
      "asset": {
        "aid": ""
      }
    }, ...
  ]
}

```
:::

| **Request Parameters** | **Accepted Values**                       |
| ---------------------- | ----------------------------------------- |
| `propertyType `        | TEXT, NOTE, NUMBER, DATETIME, SELECT, URL |
| `assets `              | \[Optional]                               |
| `customProperties `    | \[Optional]                               |
| `completedVersions `   | \[Optional]                               |

If `title`, `description` or `dueDate` are omitted, their previous value is retained.
If `assets` are supplied, then they must specify a `containerAID` but an `assetAID` is optional.
If `completedVersions` are supplied, then a container must be specified but the `asset` is optional.


:::CodeblockTabs
Response

```text
{
}
```
:::

**Errors:**

| **HTTP Status** | **Error Code**                               |                                                          |
| --------------- | -------------------------------------------- | -------------------------------------------------------- |
| 404             | unknown\_change\_request                     | Change request not found for **id**.                     |
| 404             | unknown\_template                            | Template not found for change request.                   |
| 400             | invalid\_context\_details                    | Incorrect details specified for change request template. |
| 400             | change\_request\_custom\_properties\_invalid | Custom properties are invalid for template.              |
| 400             | invalid\_container\_aid                      | Container AID wrong format.                              |
| 404             | unknown\_container                           | Container not found for AID.                             |
| 400             | invalid\_asset\_aid                          | Asset AID wrong format.                                  |
| 404             | unknown\_asset                               | Asset not found for AID.                                 |
| 404             | change\_request\_deleted                     | Change Request has been deleted.                         |

See also [Common Errors](https://docs.formedix.com/api/common-errors)



