Create a Box Sign request

To create a Box Sign request you need a file you want signed, a destination folder for the signed document, a signing log, and at least one signer. Use this page for every option you set when you create a request.

curl -i -X POST "https://api.box.com/2.0/sign_requests" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -d '{
       "signers": [
          {
            "role": "signer",
            "email": "example_email@box.com"
          }
        ],
       "source_files": [
          {
            "type": "file",
            "id": "123456789"
          }
       ],
       "parent_folder":
          {
            "type": "folder",
            "id": "0987654321"
          }
     }'

await client.signRequests.createSignRequest({
  signers: [
    {
      email: signerEmail,
      suppressNotifications: true,
      declinedRedirectUrl: 'https://www.box.com',
      embedUrlExternalUserId: '123',
      isInPerson: false,
      loginRequired: false,
      password: 'password',
      role: 'signer' as SignRequestCreateSignerRoleField,
    } satisfies SignRequestCreateSigner,
  ],
  areRemindersEnabled: true,
  areTextSignaturesEnabled: true,
  daysValid: 30,
  declinedRedirectUrl: 'https://www.box.com',
  emailMessage: 'Please sign this document',
  emailSubject: 'Sign this document',
  externalId: '123',
  externalSystemName: 'BoxSignIntegration',
  isDocumentPreparationNeeded: false,
  name: 'Sign Request',
  parentFolder: new FolderMini({ id: destinationFolder.id }),
  redirectUrl: 'https://www.box.com',
  prefillTags: [
    {
      dateValue: dateFromString('2035-01-01'),
      documentTagId: '0',
    } satisfies SignRequestPrefillTag,
  ],
  sourceFiles: [new FileBase({ id: fileToSign.id })],
} satisfies SignRequestCreateRequest);

const signRequest = await client.signRequests.create({
	signers: [
		{
			role: 'signer',
			email: 'user@example.com',
		},
	],
	source_files: [
		{
			type: 'file',
			id: '12345',
		},
	],
	parent_folder: {
		type: 'folder',
		id: '1234567',
	},
});
console.log(`Created a new sign request id ${signRequest.id}`);

client.sign_requests.create_sign_request(
    [
        SignRequestCreateSigner(
            email=signer_email,
            suppress_notifications=True,
            declined_redirect_url="https://www.box.com",
            embed_url_external_user_id="123",
            is_in_person=False,
            login_required=False,
            password="password",
            role=SignRequestCreateSignerRoleField.SIGNER,
        )
    ],
    source_files=[FileBase(id=file_to_sign.id)],
    parent_folder=FolderMini(id=destination_folder.id),
    is_document_preparation_needed=False,
    redirect_url="https://www.box.com",
    declined_redirect_url="https://www.box.com",
    are_text_signatures_enabled=True,
    email_subject="Sign this document",
    email_message="Please sign this document",
    are_reminders_enabled=True,
    name="Sign Request",
    prefill_tags=[
        SignRequestPrefillTag(
            date_value=date_from_string("2035-01-01"), document_tag_id="0"
        )
    ],
    days_valid=30,
    external_id="123",
    external_system_name="BoxSignIntegration",
)

source_file = {
    'id': '12345',
    'type': 'file'
}
files = [source_file]

signer = {
    'name': 'John Doe',
    'email': 'signer@mail.com'
}
signers = [signer]
parent_folder_id = '123456789'

new_sign_request = client.create_sign_request_v2(signers, files=files, parent_folder_id=parent_folder_id)
print(f'(Sign Request ID: {new_sign_request.id})')

await client.SignRequests.CreateSignRequestAsync(requestBody: new SignRequestCreateRequest(signers: Array.AsReadOnly(new [] {new SignRequestCreateSigner() { Email = signerEmail, SuppressNotifications = true, DeclinedRedirectUrl = "https://www.box.com", EmbedUrlExternalUserId = "123", IsInPerson = false, LoginRequired = false, Password = "password", Role = SignRequestCreateSignerRoleField.Signer }}), areRemindersEnabled: true, areTextSignaturesEnabled: true, daysValid: 30, declinedRedirectUrl: "https://www.box.com", emailMessage: "Please sign this document", emailSubject: "Sign this document", externalId: "123", externalSystemName: "BoxSignIntegration", isDocumentPreparationNeeded: false, name: "Sign Request", parentFolder: new FolderMini(id: destinationFolder.Id), redirectUrl: "https://www.box.com", prefillTags: Array.AsReadOnly(new [] {new SignRequestPrefillTag() { DateValue = Utils.DateFromString(date: "2035-01-01"), DocumentTagId = "0" }}), sourceFiles: Array.AsReadOnly(new [] {new FileBase(id: fileToSign.Id)})));

var sourceFiles = new List<BoxSignRequestCreateSourceFile>
{
    new BoxSignRequestCreateSourceFile()
    {
        Id = "12345"
    }
};

var signers = new List<BoxSignRequestSignerCreate>
{
    new BoxSignRequestSignerCreate()
    {
        Email = "example@gmail.com"
    }
};

var parentFolder = new BoxRequestEntity()
{
    Id = "12345",
    Type = BoxType.folder
};

var request = new BoxSignRequestCreateRequest
{
    SourceFiles = sourceFiles,
    Signers = signers,
    ParentFolder = parentFolder
};

BoxSignRequest signRequest = await client.SignRequestsManager.CreateSignRequestAsync(request);

try await client.signRequests.createSignRequest(requestBody: SignRequestCreateRequest(signers: [SignRequestCreateSigner(email: signerEmail, suppressNotifications: true, declinedRedirectUrl: "https://www.box.com", embedUrlExternalUserId: "123", isInPerson: false, loginRequired: false, password: "password", role: SignRequestCreateSignerRoleField.signer)], areRemindersEnabled: true, areTextSignaturesEnabled: true, daysValid: Int64(30), declinedRedirectUrl: "https://www.box.com", emailMessage: "Please sign this document", emailSubject: "Sign this document", externalId: "123", externalSystemName: "BoxSignIntegration", isDocumentPreparationNeeded: false, name: "Sign Request", parentFolder: FolderMini(id: destinationFolder.id), redirectUrl: "https://www.box.com", prefillTags: [SignRequestPrefillTag(dateValue: try Utils.Dates.dateFromString(date: "2035-01-01"), documentTagId: "0")], sourceFiles: [FileBase(id: fileToSign.id)]))

client.getSignRequests().createSignRequest(new SignRequestCreateRequest.Builder(Arrays.asList(new SignRequestCreateSigner.Builder().email(signerEmail).role(SignRequestCreateSignerRoleField.SIGNER).isInPerson(false).embedUrlExternalUserId("123").declinedRedirectUrl("https://www.box.com").loginRequired(false).password("password").suppressNotifications(true).build())).sourceFiles(Arrays.asList(new FileBase(fileToSign.getId()))).parentFolder(new FolderMini(destinationFolder.getId())).isDocumentPreparationNeeded(false).redirectUrl("https://www.box.com").declinedRedirectUrl("https://www.box.com").areTextSignaturesEnabled(true).emailSubject("Sign this document").emailMessage("Please sign this document").areRemindersEnabled(true).name("Sign Request").prefillTags(Arrays.asList(new SignRequestPrefillTag.Builder().documentTagId("0").dateValue(dateFromString("2035-01-01")).build())).daysValid(30L).externalId("123").externalSystemName("BoxSignIntegration").build())

List<BoxSignRequestFile> files = new ArrayList<BoxSignRequestFile>();
BoxSignRequestFile file = new BoxSignRequestFile("12345");
files.add(file);
        
// you can also use specific version of the file
BoxFile file = new BoxFile(api, "12345");
List<BoxFileVersion> versions = file.getVersions();
BoxFileVersion firstVersion = versions.get(0);
BoxSignRequestFile file = new BoxSignRequestFile(firstVersion.getFileID(), firstVersion.getVersionID());

List<BoxSignRequestSigner> signers = new ArrayList<BoxSignRequestSigner>();
BoxSignRequestSigner newSigner = new BoxSignRequestSigner("signer@mail.com");
signers.add(newSigner);

String destinationParentFolderId = "55555";

BoxSignRequest.Info signRequestInfo = BoxSignRequest.createSignRequest(api, files,
        signers, destinationParentFolderId);

Creating a request is asynchronous. Check the request status before you treat the request as sent, and handle conversion or sending errors.

Choose a document type

How you create the request depends on whether Box Sign already knows where to place signatures and other fields.

Unstructured document: The file has no tags or templates. Set is_document_preparation_needed to true so the sender can place fields before anyone signs. See Signing unstructured documents.
Structured document: The file already contains document tags. You can skip preparation. See Signing structured documents.
Template: Pass template_id instead of, or in addition to, source_files. See Templates.

Files

Each Box Sign request begins with a file that needs to be signed. If the file does not already exist in Box, it must be uploaded in a separate API call, before you create the request. Multiple files can be signed in one request. The file ID of the first file in a request is specified in the source_files body parameter.

The requester must have download permissions to the file in Box. Review the collaboration levels to ensure this requirement is met.

Supported file types include:

All documents
All presentations
Images: png, jpg, jpeg, tiff
Text-based files: .csv, .txt

All file types are converted to .pdf for the signature process. This converted document is stored in the parent_folder after the request is sent. The final signed document is always a .pdf, regardless of the original file type. As each signer completes the request, Box Sign adds a new file version. File size limits are determined by your account type. See the uploads guide for more information.

Parent folder

The folder ID specified in the parent_folder body parameter determines the destination of the final signed document and signing log. This folder cannot be the All Files or root level, which is represented by folder ID 0.

Document preparation

Preparing a document before you send a Box Sign request lets you add date, text, checkbox, and signature placeholders for signers. You can do this in the prepare UI or with tags in the document. If you skip preparation, signers receive an unprepared document and can place signatures and fields themselves. You can still turn unprepared document features on or off in the request. Set is_document_preparation_needed to true to get a prepare_url in the response. Open that URL in a browser to place fields and send the request. Until someone visits prepare_url, the request stays in the created status. Once someone visits prepare_url, the request status changes to sent. For unstructured files, always set is_document_preparation_needed to true so the requester can place fields before the signer receives the request. Structured documents and templates already define field placement, so you can skip the preparation step.

Prefill tags created in a template with the Box web app cannot be accessed through the API.

Signers

Each signer must have a role (signer, approver, or final_copy_reader) and can have a signing order. For what each role can do, how ordering works, and a multi-signer example, see Multiple signers and signing order. Signers do not need a Box account. Invite them by email address, not by Box’s user_id.

Box Sign sends signing emails only to the addresses you provide. For Box users, that does not include email aliases unless you specify them. Confirm that every signer email is valid.

Signer verification

To require a CAC/PIV smart card, SMS, Box login, or a password before a signer can sign, see Verify signer identity.

Signer language

Set language on a signer to force emails and the signing page to that language, regardless of the signer’s Box account or browser. If you omit language, Box Sign uses the signer’s Box account language when they are logged in, or English when they are not. Use a supported code from the language codes page, for example en, nl, fr, de, es, or ja. An unsupported code returns a 400 Bad Request error. If the signer has an account, they can change their language in their account settings.

curl -i -X POST "https://api.box.com/2.0/sign_requests" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -d '{
       "signers": [
          {
            "role": "signer",
            "email": "signer@example.com",
            "language": "nl"
          }
        ],
       "source_files": [
          {
            "type": "file",
            "id": "123456789"
          }
       ],
       "parent_folder": {
          "type": "folder",
          "id": "0987654321"
       }
     }'

In-person signatures

To collect a signature on the requester’s device, set is_in_person to true and see In-person signing.

Signature properties and prefill tags

Signature properties are the fields a signer can interact with. Use prefill_tags with document_tag_id to populate signature properties when you create the request. Signers can still change prefilled values they own. For more information, see Signature properties and prefill tags. When you use a template, keep signer order in the POST body the same as the order on the template so the correct person gets each field.

{
  "template_id": "6ae28666-03c4-4ac1-80db-06a90d3b1361",
  "parent_folder": {
    "id": "123456789000",
    "type": "folder"
  },
  "signers": [
    {
      "email": "signer1@example.com",
      "role": "signer"
    },
    {
      "email": "signer2@example.com",
      "role": "signer"
    }
  ],
  "prefill_tags": [
    {
      "document_tag_id": "signer1_full_name",
      "text_value": "Ebenezer Scrooge"
    },
    {
      "document_tag_id": "signer2_full_name",
      "text_value": "Bob Cratchit"
    }
  ]
}

For listing templates, tag IDs, and a full walkthrough, see Create a sign request with a template.

Redirects

Set redirect_url and declined_redirect_url to send signers to a custom page after they sign or decline. You can set these URLs on the request for each signer, and override them on individual signers. If you omit both, Box Sign uses the default completion page.

The default completion page tells signers that a limited-time link to the finalized copy is emailed to them, and that a copy is available in Box if they have an account. A custom redirect URL does not include that message.

Custom completion pages after sign or decline

Email and notifications

To customize Box Sign email, send the signing link yourself, or embed the client, see How signers get the request.

Request expiration

Set days_valid to expire the request after that many days. After expiration, the request status is expired and remaining signers cannot complete it.

Request flow

Set request_flow to cfr11 for a 21 CFR Part 11 (GxP) request, or standard for the default flow. See 21 CFR Part 11 requests.

Request status

Creating a request is asynchronous, so the response returns a status that changes as the file converts, signers are notified, and the document is completed. For what each value means and which actions each one allows, see Box Sign request status.

Getting started

Applications & integrations

Identity & access

Using the API

Troubleshooting

Content

Collaboration

Metadata & search

Events & webhooks

Users

Intelligent workflow

E-signatures

Security & compliance

Create a Box Sign request

Choose a document type

Files

Parent folder

Document preparation

Signers

Signer verification

Signer language

In-person signatures

Signature properties and prefill tags

Redirects

Email and notifications

Request expiration

Request flow

Request status

​Choose a document type

​Files

​Parent folder

​Document preparation

​Signers

​Signer verification

​Signer language

​In-person signatures

​Signature properties and prefill tags

​Redirects

​Email and notifications

​Request expiration

​Request flow

​Request status

Choose a document type

Files

Parent folder

Document preparation

Signers

Signer verification

Signer language

In-person signatures

Signature properties and prefill tags

Redirects

Email and notifications

Request expiration

Request flow

Request status