メインコンテンツへスキップ
POST
/
sign_requests
cURL
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"
          }
     }'
{
  "is_document_preparation_needed": true,
  "redirect_url": "https://www.example.com",
  "declined_redirect_url": "https://declined-redirect.com",
  "are_text_signatures_enabled": true,
  "email_subject": "Sign Request from Acme",
  "email_message": "Hello! Please sign the document below",
  "are_reminders_enabled": true,
  "name": "name",
  "prefill_tags": [
    {
      "document_tag_id": "1234",
      "text_value": "text",
      "checkbox_value": true,
      "date_value": "2021-04-26"
    }
  ],
  "days_valid": 2,
  "external_id": "123",
  "template_id": "123075213-af2c8822-3ef2-4952-8557-52d69c2fe9cb",
  "external_system_name": "Box",
  "type": "sign-request",
  "source_files": [
    {
      "id": "12345",
      "type": "file",
      "etag": "1"
    }
  ],
  "signers": [
    {
      "email": "example@gmail.com",
      "role": "signer",
      "is_in_person": true,
      "order": 2,
      "embed_url_external_user_id": "1234",
      "redirect_url": "https://example.com",
      "declined_redirect_url": "https://declined-example.com",
      "login_required": true,
      "verification_phone_number": "6314578901",
      "signer_group_id": "cd4ff89-8fc1-42cf-8b29-1890dedd26d7",
      "suppress_notifications": false,
      "has_viewed_document": true,
      "signer_decision": {
        "type": "signed",
        "finalized_at": "2021-04-26T08:12:13.982Z",
        "additional_info": "Requesting changes before signing."
      },
      "inputs": [
        {
          "page_index": 4,
          "document_tag_id": "1234",
          "text_value": "text",
          "checkbox_value": true,
          "date_value": "2021-04-26",
          "type": "text",
          "content_type": "signature",
          "read_only": true,
          "validation": {
            "validation_type": "email"
          }
        }
      ],
      "embed_url": "https://example.com",
      "iframeable_embed_url": "https://app.box.com/embed/sign/document/gfhr4222-a331-494b-808b-79bc7f3992a3/f14d7098-a331-494b-808b-79bc7f3992a4",
      "attachments": [
        {
          "id": "12345",
          "name": "proof_of_identity.pdf"
        }
      ]
    }
  ],
  "signature_color": "blue",
  "id": "12345",
  "prepare_url": "https://prepareurl.com",
  "signing_log": {
    "id": "12345",
    "type": "file",
    "etag": "1",
    "sequence_id": "3",
    "name": "Contract.pdf",
    "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
    "file_version": {
      "id": "12345",
      "type": "file_version",
      "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
    }
  },
  "status": "converting",
  "sign_files": {
    "files": [
      {
        "id": "12345",
        "type": "file",
        "etag": "1",
        "sequence_id": "3",
        "name": "Contract.pdf",
        "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
        "file_version": {
          "id": "12345",
          "type": "file_version",
          "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
        }
      }
    ],
    "is_ready_for_download": true
  },
  "auto_expire_at": "2021-04-26T08:12:13.982Z",
  "parent_folder": {
    "id": "12345",
    "type": "folder",
    "etag": "1",
    "sequence_id": "3",
    "name": "Contracts"
  },
  "collaborator_level": "owner",
  "short_id": "SR-12345",
  "created_at": "2025-02-01T12:00:00Z",
  "finished_at": "2025-02-02T12:00:00Z",
  "sender_email": "sender@box.com",
  "sender_id": 12345
}
このリソースは、バージョン2024.0のエンドポイントで使用されています。 詳細については、 Box APIのバージョン管理を参照してください。「Box SDKのバージョニング戦略について詳しく学ぶ。」

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json

Box Signリクエストオブジェクトを作成します。 署名リクエストオブジェクトのStandard版の表示。

​
signers
Box Signリクエストオブジェクトを作成するための署名者フィールド。 · object[]
required

署名リクエストの署名者の配列。許可されている署名者の最大数は35です。

注: 一部の署名者が競合するセグメント (ユーザーグループ) に属している可能性もあります。これは、セキュリティポリシーにより、倫理的な競合につながる可能性のあるやり取りやコミュニケーションを防ぐためにユーザーがセグメントに割り当てられていることを意味します。このような場合、署名リクエストを送信しようとすると、エラーが発生します。

セグメントと情報バリアの詳細については、こちらを参照してください。

​
is_document_preparation_needed
boolean

UIを使用してドキュメントの準備を完了するために送信者がレスポンスでprepare_urlを受け取る必要があるかどうかを示します。

Example:

true

​
redirect_url
string | null

指定した場合、ドキュメントに署名された時点で、署名リクエストがこのURLにリダイレクトされます。

Example:

"https://www.example.com"

​
declined_redirect_url
string | null

署名者がドキュメントへの署名を拒否した後にリダイレクトされるURI。

Example:

"https://declined-redirect.com"

​
are_text_signatures_enabled
boolean
default:true

(テキストの) 入力で生成された署名の使用を無効にします。

Example:

true

​
email_subject
string | null

署名リクエストメールの件名。これは、署名リクエストによって消去されます。このフィールドを渡さない場合は、デフォルトの件名が使用されます。

Example:

"Sign Request from Acme"

​
email_message
string | null

署名リクエストメールに含めるメッセージ。このフィールドは、特定の文字のサニタイズによって消去されます。ただし、一部のHTMLタグは使用できます。また、このメッセージに含まれているリンクはメールではハイパーリンクに変換されます。このメッセージには、HTMLタグa、abbr、acronym、b、blockquote、code、em、i、ul、li、ol、strongを含めることができます。HTMLに対するテキストの比率が大きすぎると、メールがスパムフィルタに入る可能性があることに注意してください。これらのタグにカスタムスタイルを適用することはできません。このフィールドを渡さない場合は、デフォルトのメッセージが使用されます。

Example:

"Hello! Please sign the document below"

​
are_reminders_enabled
boolean

3、8、13、18日目にドキュメントに署名するよう署名者に促します。リマインダは未署名の署名者にのみ送信されます。

Example:

true

​
name
string

署名リクエストの名前。

Example:

"name"

​
prefill_tags
署名リクエスト事前入力タグ · object[]

署名に関連するタグがドキュメントのコンテンツに含まれている場合、このprefill_tagsを使用してタグを事前入力できます。その際、タグの「id」を事前入力タグのexternal_idフィールドとして参照します。

​
days_valid
integer | null

作成した署名リクエストが完了しなかった場合に自動的に期限切れになるまでの日数を設定します。デフォルトでは、署名リクエストに有効期限を適用しないため、署名リクエストは期限切れになりません。

必須範囲: 0 <= x <= 730
Example:

2

​
external_id
string | null

これは、署名リクエストが関連する外部システムのIDを参照する際に使用できます。

Example:

"123"

​
template_id
string | null

署名リクエストがテンプレートから作成された場合、このフィールドはそのテンプレートのIDを示します。

Example:

"123075213-af2c8822-3ef2-4952-8557-52d69c2fe9cb"

​
external_system_name
string | null

署名ログで、embed_url_external_idが割り当てられている署名者の横に表示するシステム名 (省略可) として使用されます。

Example:

"Box"

​
source_files
(ファイル (Base) · object | null)[] | null

署名するドキュメントの作成元ファイルのリスト。現在は、10ファイルに制限されています。ファイルごとにIDフィールドとtypeフィールドのみが必要です。

Maximum array length: 10

最も基本的なファイルのBase版の表示。fieldsクエリパラメータを使用すると、最小限の数のフィールドが返されます。

​
signature_color
enum<string> | null

署名に特定の色 (青、黒、または赤) を強制します。

利用可能なオプション:
blue,
black,
red
Example:

"blue"

​
parent_folder
フォルダ (Mini) · object

最終的な署名済みドキュメントと署名ログの保存先フォルダ。IDフィールドとtypeフィールドのみが必須です。ルートフォルダ (フォルダID 0) は使用できず、nullにすることもできません。

署名リクエストの作成時にこの値が渡されない場合は、デフォルトのフォルダを使用することになります。デフォルトのフォルダは、ペイロードの最初のソースファイルの親フォルダ (そのフォルダへのアップロード権限がある場合) または「My Sign Requests」という名前のフォルダになります。

Response

Box Signリクエストオブジェクトを返します。

Box Signリクエストオブジェクト。 署名リクエストオブジェクトのStandard版の表示。

​
is_document_preparation_needed
boolean

UIを使用してドキュメントの準備を完了するために送信者がレスポンスでprepare_urlを受け取る必要があるかどうかを示します。

Example:

true

​
redirect_url
string | null

指定した場合、ドキュメントに署名された時点で、署名リクエストがこのURLにリダイレクトされます。

Example:

"https://www.example.com"

​
declined_redirect_url
string | null

署名者がドキュメントへの署名を拒否した後にリダイレクトされるURI。

Example:

"https://declined-redirect.com"

​
are_text_signatures_enabled
boolean
default:true

(テキストの) 入力で生成された署名の使用を無効にします。

Example:

true

​
email_subject
string | null

署名リクエストメールの件名。これは、署名リクエストによって消去されます。このフィールドを渡さない場合は、デフォルトの件名が使用されます。

Example:

"Sign Request from Acme"

​
email_message
string | null

署名リクエストメールに含めるメッセージ。このフィールドは、特定の文字のサニタイズによって消去されます。ただし、一部のHTMLタグは使用できます。また、このメッセージに含まれているリンクはメールではハイパーリンクに変換されます。このメッセージには、HTMLタグa、abbr、acronym、b、blockquote、code、em、i、ul、li、ol、strongを含めることができます。HTMLに対するテキストの比率が大きすぎると、メールがスパムフィルタに入る可能性があることに注意してください。これらのタグにカスタムスタイルを適用することはできません。このフィールドを渡さない場合は、デフォルトのメッセージが使用されます。

Example:

"Hello! Please sign the document below"

​
are_reminders_enabled
boolean

3、8、13、18日目にドキュメントに署名するよう署名者に促します。リマインダは未署名の署名者にのみ送信されます。

Example:

true

​
name
string

署名リクエストの名前。

Example:

"name"

​
prefill_tags
署名リクエスト事前入力タグ · object[]

署名に関連するタグがドキュメントのコンテンツに含まれている場合、このprefill_tagsを使用してタグを事前入力できます。その際、タグの「id」を事前入力タグのexternal_idフィールドとして参照します。

​
days_valid
integer | null

作成した署名リクエストが完了しなかった場合に自動的に期限切れになるまでの日数を設定します。デフォルトでは、署名リクエストに有効期限を適用しないため、署名リクエストは期限切れになりません。

必須範囲: 0 <= x <= 730
Example:

2

​
external_id
string | null

これは、署名リクエストが関連する外部システムのIDを参照する際に使用できます。

Example:

"123"

​
template_id
string | null

署名リクエストがテンプレートから作成された場合、このフィールドはそのテンプレートのIDを示します。

Example:

"123075213-af2c8822-3ef2-4952-8557-52d69c2fe9cb"

​
external_system_name
string | null

署名ログで、embed_url_external_idが割り当てられている署名者の横に表示するシステム名 (省略可) として使用されます。

Example:

"Box"

​
type
enum<string>

値は常にsign-requestになります。

利用可能なオプション:
sign-request
Example:

"sign-request"

​
source_files
(ファイル (Base) · object | null)[]

署名するドキュメントの作成元ファイルのリスト。現在は、10ファイルに制限されています。ファイルごとにIDフィールドとtypeフィールドのみが必要です。

最も基本的なファイルのBase版の表示。fieldsクエリパラメータを使用すると、最小限の数のフィールドが返されます。

​
signers
Box Signリクエストのレスポンスの署名者フィールド · object[]

署名リクエストの署名者の配列。

​
signature_color
string | null

署名に特定の色 (青、黒、または赤) を強制します。

Example:

"blue"

​
id
string

Box SignリクエストID。

Example:

"12345"

​
prepare_url
string | null

このURLは、リクエストでis_document_preparation_neededがtrueに設定されている場合に返されます。このパラメータは、UIを使用して署名リクエストを準備する際に使用されます。署名リクエストは、準備段階が完了するまで送信されません。

Example:

"https://prepareurl.com"

​
signing_log
ファイル (Mini) · object

リクエストに対する署名者のアクティビティがすべて記録されているファイルへの参照。

​
status
enum<string>

署名リクエストのステータスを説明します。

利用可能なオプション:
converting,
created,
sent,
viewed,
signed,
cancelled,
declined,
error_converting,
error_sending,
expired,
finalizing,
error_finalizing
Example:

"converting"

​
sign_files
object

署名されるファイル (元のソースファイルのコピー) のリスト。署名者が署名すると、これらのファイルの新しいバージョンが作成され、署名プロセスのどの時点でもダウンロードできます。

​
auto_expire_at
string<date-time> | null

days_validを使用すると、未署名の場合に署名リクエストの有効期限となる日時 (GMT) が計算されます。

Example:

"2021-04-26T08:12:13.982Z"

​
parent_folder
フォルダ (Mini) · object

最終的な署名済みドキュメントと署名ログの保存先フォルダ。

署名リクエストの作成時にこの値が渡されなかった場合は、デフォルトのフォルダを使用することになります。デフォルトのフォルダは、ペイロードの最初のソースファイルの親フォルダ (そのフォルダへのアップロード権限がある場合) または「My Sign Requests」という名前のフォルダになります。

​
collaborator_level
string | null

署名リクエストに対するユーザーのコラボレータレベル。値には「owner」、「editor」、「viewer」を指定できます。

Example:

"owner"

​
short_id
string

署名リクエストの短い識別子。

Example:

"SR-12345"

​
created_at
string<date-time>

署名リクエストが作成された日時をマークするタイムスタンプ。

Example:

"2025-02-01T12:00:00Z"

​
finished_at
string<date-time> | null

すべての署名操作が完了した日時を示すタイムスタンプ。

Example:

"2025-02-02T12:00:00Z"

​
sender_email
string | null

署名リクエストの送信者のメールアドレス。

Example:

"sender@box.com"

​
sender_id
integer | null

署名リクエストの送信者のユーザーID。

Example:

12345