Skip to main content

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

5 replies

rbarbosa Box
  • Developer Advocate
  • 553 replies
  • December 8, 2023

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.


Forum|alt.badge.img
  • Known Participant
  • 15 replies
  • December 12, 2023

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.


rbarbosa Box
  • Developer Advocate
  • 553 replies
  • December 13, 2023

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


  • Author
  • New Participant
  • 1 reply
  • December 14, 2023

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


rbarbosa Box
  • Developer Advocate
  • 553 replies
  • December 14, 2023

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


Cookie policy

We use cookies to enhance and personalize your experience. If you accept you agree to our full cookie policy. Learn more about our cookies.

 
Cookie settings