21 CFR Part 11 requests

21 CFR Part 11 is a US Food and Drug Administration (FDA) regulation that defines the criteria for accepting electronic records and electronic signatures as equivalent to paper records and handwritten signatures. Organizations in regulated industries, such as life sciences, refer to these requirements as GxP (good practice) compliance. You can create and manage both 21 CFR Part 11 and standard signature requests through the Box Sign API. You can now require 21 CFR Part 11 signatures in your own applications, as well as in Box Automate workflows and the Box for Salesforce integration, rather than only in the Box web app.

Support for 21 CFR Part 11 in Box Sign requires GxP Validation. In addition to GxP Validation, customers must enable 21 CFR Part 11 for specific users and groups within the Admin Console before they can create cfr11 requests through the API. To learn more, see 21 CFR Part 11 compliance support.

Choose a request flow

The request_flow field determines whether a request follows the 21 CFR Part 11 or the standard flow. It accepts the following values:

Value	Description
`cfr11`	The request follows the 21 CFR Part 11 flow and enforces the related requirements.
`standard`	The request follows the standard Box Sign flow.

The request_flow field is optional when you create a request. If you don’t set it, Box selects a default based on your enterprise’s admin setting. If you set a value that your account doesn’t have access to, the API returns a 403 Forbidden error. The request_flow field is also returned in the response when you create, retrieve, or list signature requests and templates, so you can identify which flow each request or template uses.

Requirements for 21 CFR Part 11 requests

When request_flow is cfr11, the following requirements apply:

Signer login is required. The login_required field on each signer is always true. If you set login_required to false, the API returns a 400 Bad Request error.
Signature color can’t be red. If you set signature_color to red, the API returns a 400 Bad Request error. Use blue or black instead.
Each recipient must have valid fields. Each recipient or recipient group must be assigned either no fields, or at least one required signature or initials field. For example, you can’t create a 21 CFR Part 11 request that has only text fields, but you can create one with no placeholders at all.

Create a 21 CFR Part 11 request

Set request_flow to cfr11 when you . How Box validates the request depends on whether you provide a template, source files, or both.

Create from a template

When you create a request from a template, pass the template_id and set request_flow to cfr11. Box validates the template’s placeholders at request time against the 21 CFR Part 11 requirements.

cURL

curl -i -X POST "https://api.box.com/2.0/sign_requests" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "request_flow": "cfr11",
       "template_id": "123075213-af2c8822-3ef2-4952-8557-52d69c2fe9cb",
       "signers": [
         {
           "role": "signer",
           "email": "signer@example.com"
         }
       ],
       "parent_folder": {
         "type": "folder",
         "id": "234102987614"
       }
     }'

If the template contains only non-signature fields, the request fails with a 400 Bad Request error. See Error responses.

Create from source files

When you create a request from source_files, you define signature, initials, and other placeholders directly in the document using template tags. Box extracts these placeholders asynchronously while converting the document, so it can’t validate them at request time. For this reason, the is_document_preparation_needed field becomes mandatory for 21 CFR Part 11 requests created from source files. The value you set determines when validation runs:

`is_document_preparation_needed`	When validation runs
`true`	When you review the document in the Box Sign preparation page, before the request is sent.
`false`	Automatically, during the asynchronous document conversion after the request is sent.

Review the document before sending

When you set is_document_preparation_needed to true, the response includes a prepare_url. Open this URL in a browser to review the document in the Box Sign preparation page before the request is sent. During preparation, Box:

Validates signature and initials placeholders.
Automatically adjusts those placeholders to meet 21 CFR Part 11 requirements.
Displays a warning when any placeholder is resized, so you can review the changes before sending.

From the preparation page, you can accept the adjustments and send the request, or cancel it.

cURL

curl -i -X POST "https://api.box.com/2.0/sign_requests" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "request_flow": "cfr11",
       "is_document_preparation_needed": true,
       "source_files": [
         {
           "type": "file",
           "id": "1358047520478"
         }
       ],
       "signers": [
         {
           "role": "signer",
           "email": "signer@example.com"
         }
       ],
       "parent_folder": {
         "type": "folder",
         "id": "234102987614"
       }
     }'

Validate during conversion

When you set is_document_preparation_needed to false, Box validates the placeholders during the asynchronous document conversion. If validation fails:

The request moves to the error state, with the error_code field set to cfr11_validation_failed.
Box emails the requester to report the failure and points them to the API documentation.
You need to revise the file to meet 21 CFR Part 11 requirements and submit a new request.

Create from a template and source files

You can pass both a template_id and source_files. In this case, the source files overwrite the template’s document, while other information from the template, such as signers, stays linked to the request. Box validates the request the same way as when you create from source files, so is_document_preparation_needed is mandatory.

Read CFR Part 11 requests and templates

When you retrieve or list signature requests and templates, the response includes fields that describe the 21 CFR Part 11 flow and signing details.

Field	Type	Description
`request_flow`	String	The flow the request or template uses: `cfr11` or `standard`.
`signers[].login_required`	Boolean	Always `true` when `request_flow` is `cfr11`.
`signers[].inputs[].reason`	String, nullable	The signing reason captured for the input. Populated only for applicable inputs, such as signature or initials fields in a `cfr11` request. `null` otherwise.
`signers[].inputs[].is_validated`	Boolean, nullable	Whether the signer re-authenticated for the input. `true` after a successful re-authentication, `false` if the signer filled the field but hasn’t re-authenticated yet, and `null` for standard requests or inputs where it doesn’t apply.

The following example shows a retrieved 21 CFR Part 11 request:

{
  "request_flow": "cfr11",
  "signers": [
    {
      "login_required": true,
      "inputs": [
        {
          "text_value": "John Doe",
          "type": "signature",
          "content_type": "signature",
          "page_index": 0,
          "read_only": false,
          "reason": "I read and approve this document",
          "is_validated": true
        }
      ]
    }
  ]
}

You can retrieve, list, cancel, and resend a 21 CFR Part 11 request or template as long as you have access to it, even if 21 CFR Part 11 isn’t enabled for your account. Box verifies permission to use a template when you create a request from it, not when you retrieve the template.

Error responses

21 CFR Part 11 requests return the following errors synchronously when validation fails at request time:

Scenario	Status	Reason
`login_required` is set to `false` for a `cfr11` request.	`400`	`invalid_parameter`
`signature_color` is set to `red` for a `cfr11` request.	`400`	`invalid_parameter`
A `cfr11` request contains only non-signature fields.	`400`	`invalid_template`
The specified `template_id` doesn’t exist.	`404`	`not_found`
You don’t have permission to use the specified `template_id`.	`404`	`not_found`
You don’t have access to the specified `request_flow`.	`403`	`forbidden_by_policy`

For example, setting login_required to false returns:

{
  "type": "error",
  "code": "bad_request",
  "status": 400,
  "message": "Bad request",
  "request_id": "122afdc1863c8713a175148aa614578ff",
  "context_info": {
    "errors": [
      {
        "name": "login_required",
        "message": "The 'login_required' field cannot be set to false when the request flow is 'cfr11'. Please ensure that 'login_required' is true for 'cfr11' requests.",
        "reason": "invalid_parameter"
      }
    ]
  }
}

Placeholder errors for requests created from source files using template tags aren’t returned at request time, because Box extracts placeholders asynchronously during document conversion. When this validation fails, the request moves to the error state with the error_code field set to cfr11_validation_failed. For more information, see Validate during conversion.

Backward compatibility

Existing requests and templates that were created before 21 CFR Part 11 support was added to the API are classified automatically. For these items, Box determines the request_flow value based on the user’s permissions, so older requests and templates return a valid request_flow when you retrieve them.

​Choose a request flow

​Requirements for 21 CFR Part 11 requests

​Create a 21 CFR Part 11 request

​Create from a template

​Create from source files

​Review the document before sending

​Validate during conversion

​Create from a template and source files

​Read CFR Part 11 requests and templates

​Error responses

​Backward compatibility

Choose a request flow

Requirements for 21 CFR Part 11 requests

Create a 21 CFR Part 11 request

Create from a template

Create from source files

Review the document before sending

Validate during conversion

Create from a template and source files

Read CFR Part 11 requests and templates

Error responses

Backward compatibility