Retrieving URL from box sign request

GOAL: I would like to retrieve the document URL from the box-sign api request and have the e-signature email sent out.

Option 1:
Option 1 sends a e-signature request email but no URL in the request

payload = {
“template_id”: template_id,
“email_message”: ‘message’,
“email_subject”: subject,
“days_valid”: 5,
“parent_folder”: {
“id”: folder_id,
“type”: “folder”
},
“signers”: [
{
“email”: email,
“role”: “signer”,
},
],
“prefill_tags”: prefill_tags
}

Option 2:
Option 2 DOES NOT send a e-signature request email but there IS* a URL in the request

payload = {
“template_id”: template_id,
“email_message”: ‘message’,
“email_subject”: subject,
“days_valid”: 5,
“parent_folder”: {
“id”: folder_id,
“type”: “folder”
},
“signers”: [
{
“email”: email,
“role”: “signer”,
“embed_url_external_user_id”: ‘1234’,
},
],
“prefill_tags”: prefill_tags
}
response = client.make_request(
‘POST’,
endpoint,
data=json.dumps(payload),
headers={‘Content-Type’: ‘application/json’}
)
response_data = response.json()
iframeable_embed_url = response_data[‘signers’][1][‘embed_url’]

NOTE: embed_url_external_user_id is the only different between the two methods

1 Like

Hi @SDK_nerd , welcome to the forum!

I’m not sure what is the question here, but I’ll try to clarify some of the points. Please elaborate if needed.

If you send an embed_url_external_user_id in the signer, you get back both an embed_url and an iframeable_embed_url.

The embed_url can be opened directly, so it is suitable for your app to send it in an email for the signer to open.

The iframeable_embed_url is suited to be used with the Box Embedded Sign Client. In essence you can embed the sign client on an iframe within your own web app.

For example consider this request:

curl --location 'https://api.box.com/2.0/sign_requests' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer fN...dD' 
--data-raw '{
    "is_document_preparation_needed": false,
    "parent_folder": {
        "id": "234102987614",
        "type": "folder"
    },
    "source_files": [
        {
            "id": "1355143830404",
            "type": "file"
        }
    ],
    "signers": [
        {
            "email": "example@gmail.com",
            "embed_url_external_user_id":"1234",
            "role": "signer"
        }
    ]
}'

returns (simplified):

{
    "is_document_preparation_needed": false,
    "signers": [
        {
            "email": "...@gmail.com",
            "role": "final_copy_reader",
        },
        {
            "email": "example@gmail.com",
            "role": "signer",
            "embed_url_external_user_id": "1234",
            "embed_url": "https://app.box.com/sign/document/22a990ce-4e24-463b-b2f4-124820fe161a/9331fe9ac85650d61645d4b0fd30fe3e0ebee7921720ab6ecca587654d3cd875/",
            "iframeable_embed_url": "https://app.box.com/embed/sign/document/22a990ce-4e24-463b-b2f4-124820fe161a/9331fe9ac85650d61645d4b0fd30fe3e0ebee7921720ab6ecca587654d3cd875/"
        }
    ],
    "id": "22a990ce-4e24-463b-b2f4-124820fe161a",
    "source_files": [
        {
            "id": "1355143830404",
            "type": "file",
            "name": "Simple-PDF.pdf",
        }
    ],
    "parent_folder": {
        "id": "234102987614",
        "type": "folder",
        "name": "signed docs"
    },
    "name": "Simple-PDF (12).pdf",
    "type": "sign-request",
    "status": "converting",
    "sign_files": {
        "files": [
            {
                "id": "1383430698091",
                "etag": "0",
                "type": "file",
                "sequence_id": "0",
                "name": "Simple-PDF (12).pdf",
                "sha1": "9dd80f8a4be064208179e62a29db1cf1e37f66bc",
                "file_version": {
                    "id": "1515702726091",
                    "type": "file_version",
                    "sha1": "9dd80f8a4be064208179e62a29db1cf1e37f66bc"
                }
            }
        ],
        "is_ready_for_download": true
    },
    "auto_expire_at": null,
    "template_id": null
}

Using the embed_url_external_user_id assumes you want to take over the email send (or any other notification system), so that the user does not get an email from Box.com, and possibly have the sign be done inside your own web app.

Let us know if this helps.

Using the embed_url_external_user_id assumes you want to take over the email send (or any other notification system), so that the user does not get an email from Box.com

@rbarbosa Could we get some version of this added to the Box Sign API documentation? It’s not clear from the docs that these are mutually exclusive. Just ran into that issue of emails not going out when I added embed_url_external_user_id. Would be great to make it clear in the docs.

Hi @doc2doc

I was just checking that, and you’re right, it’s no clear at all. I suspect the documentation might be outdated.

I’ll ping the documentation folks.

Cheers

Based on the documentation, I did not know that was how the iframeable_embed_url worked. Our intended purpose was to send the link through multiple methods such as SMS, but in order to do that we needed to somehow catch the URL.

We found a work around by using the sign_request resend function. For some reason it sends the email when using it but will not send the email through the make_request.

response_data = response.json()  
sign_id = response_data['id']
sign_request = client.sign_request(sign_request_id = sign_id)
sign_request.resend()
  1. So we grab the embed_URL from the make_request,
  2. Then we send the email through sign_request resend
2 Likes

Interesting @SDK_nerd,

In the mean time I’ve pinged the product manager, to try to understand how this is intended to be used, and I’ll report back.

Cheers