# Field values

{% openapi src="/files/isyTxDSEytZTcy98sbBT" path="/chatroom/{id}/checklist-field/{fid}" method="get" %}
[openapi.json](https://3661566390-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJofjecEbyzuivtchBrHn%2Fuploads%2FBPIoFZMfZUt49MV9XS35%2Fopenapi.json?alt=media\&token=b6723cf7-2b00-4025-8d42-96c88a41ed5a)
{% endopenapi %}

{% openapi src="/files/isyTxDSEytZTcy98sbBT" path="/chatroom/{id}/checklist-field/{fid}" method="post" %}
[openapi.json](https://3661566390-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJofjecEbyzuivtchBrHn%2Fuploads%2FBPIoFZMfZUt49MV9XS35%2Fopenapi.json?alt=media\&token=b6723cf7-2b00-4025-8d42-96c88a41ed5a)
{% endopenapi %}

{% openapi src="/files/isyTxDSEytZTcy98sbBT" path="/chatroom/{id}/checklist-field/{fid}" method="patch" %}
[openapi.json](https://3661566390-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJofjecEbyzuivtchBrHn%2Fuploads%2FBPIoFZMfZUt49MV9XS35%2Fopenapi.json?alt=media\&token=b6723cf7-2b00-4025-8d42-96c88a41ed5a)
{% endopenapi %}

{% openapi src="/files/isyTxDSEytZTcy98sbBT" path="/chatroom/{id}/checklist-field/{fid}/value" method="delete" %}
[openapi.json](https://3661566390-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJofjecEbyzuivtchBrHn%2Fuploads%2FBPIoFZMfZUt49MV9XS35%2Fopenapi.json?alt=media\&token=b6723cf7-2b00-4025-8d42-96c88a41ed5a)
{% endopenapi %}

## Examples

The examples below will take you through filling in the checklist of your record, for all kinds of checklists fields.

### Text field

#### Filling text

Use the [Create field value](#chatroom-id-checklist-field-fid-1) API.

The `value` attribute is a plaintext string.

```json
{
    "value": "Some text"
}
```

#### Modifying text

Follow the same instructions as [#adding-text](#adding-text "mention") to overwrite existing text.

#### Clear text

To clear all text, use the [Create field value](#chatroom-id-checklist-field-fid-1) API and set the `value` attribute to an empty string.

```json
{
    "value": ""
}
```

### Number field

#### Filling a number

Use the [Create field value](#chatroom-id-checklist-field-fid-1) API.

The `value` attribute is a numerical value.

```json
{
    "value": 10
}
```

#### Updating number

Follow the same instructions as [#filling-a-number](#filling-a-number "mention") to overwrite the existing number.

#### Clearing number

To delete the number, use the [Create field value](#chatroom-id-checklist-field-fid-1) API and set the `value` attribute to `null`.

```json
{
    "value": null
}
```

### Picklist field

#### Filling an option

Use the [Create field value](#chatroom-id-checklist-field-fid-1) API.

The `value` attribute is either a string or an array of strings.

```json
{
    "value": ["abc","xyz"]
}
```

#### Deleting option

Follow the same instructions as [#filling-an-option](#filling-an-option "mention") to overwrite the existing option(s).

#### Clearing options

To delete all the options, use the [Create field value](#chatroom-id-checklist-field-fid-1) API and set the `value` attribute to `[]` or `null`.

```json
{
    "value": null
}
```

### Date field

#### Filling a date

Use the [Create field value](#chatroom-id-checklist-field-fid-1) API.

The `value` attribute is a date as a string, in the format `yyyy-mm-dd`.

```json
{
    "value": "1999-12-15"
}
```

#### Updating date

Follow the same instructions as [#filling-a-date](#filling-a-date "mention") to overwrite the existing date.

#### Clearing date

To delete the date, use the [Create field value](#chatroom-id-checklist-field-fid-1) API and set the `value` attribute to `null`.

```json
{
    "value": null
}
```

### User field

#### Filling a user/group

Use the [Create field value](#chatroom-id-checklist-field-fid-1) API. The `value` attribute is a JSON object or an array of JSON objects, representing either a user or a group.

```json
{
  "value": [
    {
      "type": "user",
      "uid": "jA6d4gH0oMfGd90uKCrFyjMnrvt2"
    },
    {
      "id": 1098,
      "type": "group"
    }
  ]
}
```

Alternatively, you can use the [Update field value](#chatroom-id-checklist-field-fid-2) API and specify a single user or group instead of all of them. This will effectively append a value to the existing values instead of overwriting them.

```json
{
  "value": {
    "id": 2000,
    "type": "group"
  }
}
```

#### Deleting a user/group

Use the [Delete field value](#chatroom-id-checklist-field-fid-value) API. The `value` attribute is a JSON object representing the user or group you wish to delete

```json
{
  "value": {
    "id": 1098,
    "type": "group"
  }
}
```

### File field

#### Attaching a file

Use the [Update field value](#chatroom-id-checklist-field-fid-2) API.

You must first upload your file using the Upload file API. Then, you can attach it to the checklist using the file id and version id.

```json
{
  "value": {
    "name": "a4e0580a-a7dd-469f-a373-a852e9efb684",
    "versionId": "7Pq5poXyVwHTJAzaEwS7ZYj9FdEXzkSi",
    "size": 124243,
    "originalName": "1280px-Giant_Panda_2.jpg",
    "folderId": null
  }
}
```

#### Removing file(s)

Use the [Create field value](#chatroom-id-checklist-field-fid-1) API and set the value attribute to \[] or null to delete all the files from the checklist field.

```json
{
  "value": []
}
```

Alternatively, use the [Delete field value](#chatroom-id-checklist-field-fid-value) API to delete a single file from the checklist field.

```json
{
  "value": "a4e0580a-a7dd-469f-a373-a852e9efb684"
}
```

### PDF field

Use the [Create field value](#chatroom-id-checklist-field-fid-1) API. You do not need to send anything in the payload to generate the PDF.

### Revision field

Use the [Create field value](#chatroom-id-checklist-field-fid-1) API. When creating a revision, you can specify the following options:

* A comment (revision notes)
* Data to copy over
  * Metadata
  * Checklist field values

```json
{
  "value": {
    "comment": "abc",
    "clone": {
      "metadata": [
        "title",
        "owner",
        "members",
        "dueDate",
        "files",
        "messages"
      ],
      "checklistFields": [
        340441,
        341220,
        341221,
        341222
      ]
    }
  }
}
```

### Approval field

#### Requesting an Approval (Adhoc)

Use the [Create field value](#chatroom-id-checklist-field-fid-1) API. When requesting an approval, you can specify users and groups that can sign the approval.

```json
{
  "value": {
    "requestApproval": true,
    "config": {
      "approvers": {
        "groups": [],
        "users": [
          "jA6d4gH0oMfGd90uKCrFyjMnrvt2"
        ]
      },
      "minApprovers": 1
    }
  }
}
```

#### Signing an Approval

Use the [Create field value](#chatroom-id-checklist-field-fid-1) API. When signing, you can specify the following options:

* Whether to use a custom signature or the default one
* Whether to approve or reject
* A comment
* Your email and password

```json
{
  "value": {
    "customSignature": true,
    "approved": true,
    "comment": "abc",
    "username": "abc@unifize.com",
    "password": "password"
  }
}
```

#### Canceling an Approval

Use the [Create field value](#chatroom-id-checklist-field-fid-1) API and set the `revision` attribute to `true`.

```json
{
  "value": {
    "revision": true,
    "comment": "abc"
  }
}
```

### Conversation field (Parent/Child)

#### Create new record

Use the [Create field value](#chatroom-id-checklist-field-fid-1) API. The `value` attribute would match the payload used in the [Create record](/developer/api-reference/records.md#chatroom-1) API.

```json
{
  "value": {
    "title": "abc",
    "type": "workflow",
    "owner": "jA6d4gH0oMfGd90uKCrFyjMnrvt2",
    "creator": "jA6d4gH0oMfGd90uKCrFyjMnrvt2",
    "members": [
      "jA6d4gH0oMfGd90uKCrFyjMnrvt2"
    ],
    "templateId": 16650,
    "description": "",
    "orgId": 222,
    "groups": [],
    "parent": 1453392,
    "numberingScheme": "API Docs Conv ###",
    "checklists": [],
    "privacy": "none"
  }
}
```

To add more values, the same API can be used. It will not overwrite existing values.

#### Select existing record

Use the [Create field value](#chatroom-id-checklist-field-fid-1) API. The `value` attribute is an array of record ID's. This will overwrite any existing records present in the field.

```json
{
  "value": [
    1453412,
    1453413
  ]
}
```

Alternatively, you can use the [Update field value](#chatroom-id-checklist-field-fid-2) API and specify a single record ID. This will "append" a value to the existing values, without overwriting them.

```json
{
  "value": 1453413
}
```

#### Delete conversation

To delete all the values, use the [Create field value](#chatroom-id-checklist-field-fid-1) API and set the `value` attribute to `null` or `[]`.

```json
{
  "value": []
}
```

To delete a single value, use the [Delete field value](#chatroom-id-checklist-field-fid-value) API and specify the value to be deleted in the payload.

```json
{
  "value": 1453413
}
```

### Linked field

#### Create new record

Use the [Update field value](#chatroom-id-checklist-field-fid-2) API. The `value` attribute would match the payload used in the [Create record](/developer/api-reference/records.md#chatroom-1) API.

```json
{
  "value": {
    "chatroom": {
      "title": "abc",
      "type": "workflow",
      "owner": "jA6d4gH0oMfGd90uKCrFyjMnrvt2",
      "creator": "jA6d4gH0oMfGd90uKCrFyjMnrvt2",
      "members": [
        "jA6d4gH0oMfGd90uKCrFyjMnrvt2"
      ],
      "templateId": 16650,
      "description": "",
      "orgId": 222,
      "groups": [],
      "parent": 1453392,
      "numberingScheme": "API Docs Conv ###",
      "checklists": [],
      "privacy": "none"
    }
  },
  "linkAllVersions": true
}
```

#### Select existing record

Use the [Create field value](#chatroom-id-checklist-field-fid-1) API. The `value` attribute is an array of objects. This will overwrite any existing records present in the field.

```json
{
  "value": [
    {
      "chatroom": 1453412, 
      "linkAllVersions" true
    },
    { 
      "chatroom": 1453413, 
      "linkAllVersions" true
    }
  ]
}
```

Alternatively, you can use the [Update field value](#chatroom-id-checklist-field-fid-2) API and specify a single record ID. This will "append" a value to the existing values, without overwriting them.

```json
{
  "value": {
    "chatroom": 1453413, 
    "linkAllVersions" true
  }
}
```

#### Linking specific record revisions

If you set `linkAllVersions` to `true` in [#create-new-record-1](#create-new-record-1 "mention")and [#select-existing-record-1](#select-existing-record-1 "mention"), all of the revisions of the linked record will also be automatically linked.

To link only a specific revision, you can remove that attribute from the payload.

#### Delete record

To delete a single value, use the [Delete field value](#chatroom-id-checklist-field-fid-value) API and specify the value to be deleted in the payload.

```json
{
  "value": {
    "originChatroomId": 1453413
  }
}
```

### Form field

#### Creating a form instance

Use the [Update field value](#chatroom-id-checklist-field-fid-2) API and specify the form template id.

```json
{
  "value": {
    "templateId": 18585
  }
}
```

#### Filling/updating/deleting a field value inside a form

See the above examples on how to fill the different types of fields.

Filling them when they are inside a form is exactly the same, but you will need to specify the formId query parameter when calling any of the APIs.

{% hint style="info" %}
The responses of [Update field value](#chatroom-id-checklist-field-fid-2) and [Get field value](#chatroom-id-checklist-field-fid) APIs for a form field will include two identifiers which might be confusing to distinguish.

* **`templateId`**\
  This is the ID of the form template. It will remain constant throughout the form instances, across chatrooms. \
  \
  This is the ID you should use when creating a form instance.
* **`id`**\
  This is the ID of the unique, individual form instance. \
  \
  This is the ID you should use when filling a field inside a form.
  {% endhint %}

#### Deleting a form instance

Use the [Delete field value](#chatroom-id-checklist-field-fid-value) API and specify the form instance ID in the payload.

```json
{
  "value": 235224
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.unifize.com/developer/api-reference/field-values.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.