# Embedded request

The Embedded request allows users to create, upload, and send documents on your website or mobile app using an iFrame, popup window, or new tab. It is beneficial when your application user needs to review or make other changes before sending it out for signature.

You can either create a new document or use an existing template in order to generate the embedded request link for embedding within your application.

The document created using the embedded request will remain in the `draft` state until the user completes and sends it out for signature.

## Create embedded request link

{% post /%}
{% path text="/v1/document/createEmbeddedRequestUrl" /%}   

Generating the embedded request link is the same as sending the regular document, but with additional properties to customize the embedded process. For detailed information on the send document API specific properties, please refer to the {% customlink href="/documents/send-document/" text="Send document" /%} article.

This API supports both `multipart/form-data` and `application/json` content types.

### Asynchronous document processing

The document creation process is asynchronous in nature. You will receive an embedded request URL and document ID immediately, but the uploaded document might still be processing in the background. In the meantime, if you open the embedded request URL in the browser, you will see the progress of the document processing.


### Example request using multipart/form-data

{% codetab id="codetab1" %}

cURL

```shell 
curl -X POST 'https://api.boldsign.com/v1/document/createEmbeddedRequestUrl' \
    -H 'X-API-KEY={your API key}' \
    -F 'Title=Sent from API Curl' \
    -F 'ShowToolbar=true' \
    -F 'ShowNavigationButtons=true' \
    -F 'ShowPreviewButton=true' \
    -F 'ShowSendButton=true' \
    -F 'ShowSaveButton=true' \
    -F 'SendViewOption=PreparePage' \
    -F 'ShowTooltip=false' \
    -F 'Locale=EN' \
    -F 'SendLinkValidTill=2022-10-21T06:37:57.424Z' \
    -F 'RedirectUrl=https://boldsign.dev/sign/redirect' \
    -F 'Message=This is document message sent from API Curl' \
    -F 'EnableSigningOrder=false' \
    -F 'Signers[0][Name]=Signer Name 1' \
    -F 'Signers[0][EmailAddress]=alexgayle@cubeflakes.com' \
    -F 'Signers[0][SignerOrder]=1' \
    -F 'Signers[0][AuthenticationCode]=1123' \
    -F 'Signers[0][PrivateMessage]=This is private message for signer' \
    -F 'Signers[0][FormFields][0][FieldType]=Signature' \
    -F 'Signers[0][FormFields][0][Id]=Sign' \
    -F 'Signers[0][FormFields][0][PageNumber]=1' \
    -F 'Signers[0][FormFields][0][IsRequired]=True' \
    -F 'Signers[0][FormFields][0][Bounds][X]=50' \
    -F 'Signers[0][FormFields][0][Bounds][Y]=50' \
    -F 'Signers[0][FormFields][0][Bounds][Width]=200' \
    -F 'Signers[0][FormFields][0][Bounds][Height]=30' \
    -F 'Files=@NDA.pdf;type=application/pdf'
```

C#

```csharp
var apiClient = new ApiClient("https://api.boldsign.com", "Your_API_Key");

var documentClient = new DocumentClient(apiClient);

List<FormField> formField = new List<FormField>
{
    new FormField(
        id: "Signature",
        type: FieldType.Signature,
        pageNumber: 1,
        bounds: new Rectangle(x: 50, y: 50, width: 200, height: 30))
};

var documentRequest = new EmbeddedDocumentRequest
{
    Title = "Sent from API SDK",
    Signers = new List<DocumentSigner>
    {
        new DocumentSigner(
            signerName: "David",
            signerType: SignerType.Signer,
            signerEmail: "david@cubeflakes.com",
            formFields: formField)
    },
    Files = new List<IDocumentFile>
    {
        new DocumentFilePath
        {
            ContentType = "application/pdf",
            FilePath = "YOUR_FILE_PATH",
        }
    },
    SendViewOption = PageViewOption.PreparePage,
    ShowToolbar = true
};

var embeddedSendCreated = documentClient.CreateEmbeddedRequestUrl(documentRequest);
var documentSendUrl = embeddedSendCreated.SendUrl;
```

Python

```python
import boldsign

configuration = boldsign.Configuration(host = "https://api.boldsign.com", api_key="YOUR_API_KEY")

with boldsign.ApiClient(configuration) as api_client:
    
    document_api = boldsign.DocumentApi(api_client)
	
    form_field = boldsign.FormField(
        fieldType="Signature",
        pageNumber=1,
        bounds=boldsign.Rectangle(x=50, y=50, width=200, height=30))
       
    document_signer = boldsign.DocumentSigner(
        name="Signer Name 1",
        emailAddress="signer1@boldsign.dev",
        signerType="Signer",
        formFields=[form_field])
    
    embedded_document_request = boldsign.EmbeddedDocumentRequest(
        title="Sent from API Python SDK",
        showToolbar=True,
        sendViewOption="FillingPage",
        signers=[document_signer],
        files=["YOUR_FILE_PATH"])
    
    embedded_send_created = document_api.create_embedded_request_url_document(embedded_document_request)
```

PHP

```php
<?php require_once "vendor/autoload.php";

use BoldSign\Configuration;
use BoldSign\Api\DocumentApi;
use BoldSign\Model\{FormField, Rectangle, DocumentSigner, EmbeddedDocumentRequest};

$config = new Configuration();
$config->setHost('https://api.boldsign.com');
$config->setApiKey('YOUR_API_KEY');

$document_api = new DocumentApi($config);

$form_field = new FormField();
$form_field->setFieldType('Signature');
$form_field->setPageNumber(1);
$bounds = new Rectangle([50, 100, 100, 60]);
$form_field->setBounds($bounds);

$document_signer = new DocumentSigner();
$document_signer->setName('Signer Name 1');
$document_signer->setEmailAddress('signer1@boldsign.dev');
$document_signer->setSignerType('Signer');
$document_signer->setFormFields([$form_field]);

$embedded_document_request = new EmbeddedDocumentRequest();
$embedded_document_request->setTitle('Sent from API Php SDK');
$embedded_document_request->setSendViewOption('FillingPage');
$embedded_document_request->setShowToolbar(true);
$embedded_document_request->setSigners([$document_signer]);
$embedded_document_request->setFiles(['YOUR_FILE_PATH']);

$embedded_send_created = $document_api->createEmbeddedRequestUrlDocument($embedded_document_request);
```

Java

```java
ApiClient client = Configuration.getDefaultApiClient();
client.setBasePath("https://api.boldsign.com");
client.setApiKey("YOUR_API_KEY");

DocumentApi documentApi = new DocumentApi(client);

FormField signatureField = new FormField();
signatureField.setFieldType(FormField.FieldTypeEnum.SIGNATURE);
signatureField.setPageNumber(1);
Rectangle bounds = new Rectangle().x(100f).y(100f).width(100f).height(50f);
signatureField.setBounds(bounds);

DocumentSigner signer = new DocumentSigner();
signer.setName("Signer Name 1");
signer.setEmailAddress("signer1@boldsign.dev");
signer.setSignerType(DocumentSigner.SignerTypeEnum.SIGNER);
signer.setFormFields(Arrays.asList(signatureField));
				
EmbeddedDocumentRequest embeddedDocumentRequest = new EmbeddedDocumentRequest();
File file = new File("YOUR_FILE_PATH");  
embeddedDocumentRequest.setFiles(Arrays.asList(file));
embeddedDocumentRequest.setSigners(Arrays.asList(signer));
embeddedDocumentRequest.setSendViewOption(EmbeddedDocumentRequest.SendViewOptionEnum.FILLING_PAGE);
embeddedDocumentRequest.setShowToolbar(true);
embeddedDocumentRequest.setTitle("Sent from API java SDK");

EmbeddedSendCreated embeddedSendCreated = documentApi.createEmbeddedRequestUrlDocument(embeddedDocumentRequest);
```

NodeJS

```js
import { DocumentApi, DocumentSigner, EmbeddedDocumentRequest, FormField, Rectangle } from "boldsign"; 
import * as fs from 'fs';

const documentApi = new DocumentApi("https://api.boldsign.com");
documentApi.setApiKey("YOUR_API_KEY");

const bounds = new Rectangle();
bounds.x = 100;
bounds.y = 50;
bounds.width = 100;
bounds.height = 100;

const formField = new FormField();
formField.fieldType = FormField.FieldTypeEnum.Signature;
formField.pageNumber = 1;
formField.bounds = bounds;

const documentSigner = new DocumentSigner();
documentSigner.name = "Signer Name 1";
documentSigner.emailAddress = "signer1@boldsign.dev";
documentSigner.signerType = DocumentSigner.SignerTypeEnum.Signer;
documentSigner.formFields = [formField];

const files = fs.createReadStream("YOUR_FILE_PATH");

const embeddedDocumentRequest = new EmbeddedDocumentRequest();
embeddedDocumentRequest.title = "Sent from API Node SDK";
embeddedDocumentRequest.showToolbar = true;
embeddedDocumentRequest.sendViewOption = EmbeddedDocumentRequest.SendViewOptionEnum.FillingPage;
embeddedDocumentRequest.files = [files];
embeddedDocumentRequest.signers = [documentSigner];

const embeddedSendCreated = documentApi.createEmbeddedRequestUrlDocument(embeddedDocumentRequest);
```

{% /codetab %}

### Code snippet using application/json

{% codetab id="codetab2" %}

cURL
```shell 
curl -X POST 'https://api.boldsign.com/v1/document/createEmbeddedRequestUrl' \
    -H 'X-API-KEY: {your API key}' \
    -H 'Content-Type: application/json' \
    -d '{
        "Title": "Sent from API Curl",
        "ShowToolbar": true,
        "ShowNavigationButtons": true,
        "ShowPreviewButton": true,
        "ShowSendButton": true,
        "ShowSaveButton": true,
        "SendViewOption": "PreparePage",
        "ShowTooltip": false,
        "Locale": "EN",
        "SendLinkValidTill": "2022-10-21T06:37:57.424Z",
        "RedirectUrl": "https://boldsign.dev/sign/redirect",
        "Message": "This is document message sent from API Curl",
        "EnableSigningOrder": false,
        "Signers": [
            {
                "Name": "Signer Name 1",
                "EmailAddress": "alexgayle@cubeflakes.com",
                "SignerOrder": 1,
                "AuthenticationCode": "1123",
                "PrivateMessage": "This is private message for signer",
                "FormFields": [
                    {
                        "FieldType": "Signature",
                        "Id": "Sign",
                        "PageNumber": 1,
                        "IsRequired": true,
                        "Bounds": {
                            "X": 50,
                            "Y": 50,
                            "Width": 200,
                            "Height": 30
                        }
                    }
                ]
            }
        ],
        "Files": [
            "data:application/pdf;base64,JVBERi0xLjcKJcfs..." 
        ]
    }'
```

{% /codetab %}

### Request body

{% nestedtable %}

- {% arguments name="RedirectUrl" /%}{% batch datatype="string" /%}
- The redirect URI will be redirected after the document creation process is completed. The string should be in URI format.

---

- {% arguments name="ShowToolbar" /%}{% batch datatype="boolean" /%}
- Controls the visibility of the toolbar at the top of the document editor.  
  Defaults to false.

---

- {% arguments name="SendViewOption" /%}{% batch datatype="string" /%}
- Configures the initial view page to be loaded from the generated URL. The FillingPage is used to customize signers, authentication, etc. The PreparePage is used to configure signers form fields.  
  Either PreparePage or FillingPage. Defaults to PreparePage.

---

- {% arguments name="ShowSaveButton" /%}{% batch datatype="boolean" /%}
- Controls the visibility of the `Save and Close` button from the `More Action` drop-down menu. Set to false if you don't want your users to save the document as draft instead of sending it out for signature.  
  Defaults to true.

---

- {% arguments name="ShowSendButton" /%}{% batch datatype="boolean" /%}
- Controls the visibility of the `Send` button at the top right corner of the page. Set to false if you want your users to save the document as only drafts instead of sending it out for signature.  
  Defaults to true.

---

- {% arguments name="ShowPreviewButton" /%}{% batch datatype="boolean" /%}
- Controls the visibility of the `Preview` button from the `More Action` drop-down menu. Set to false if you don't want your users to preview the document before sending it out for signature.  
  Defaults to true.

---

- {% arguments name="ShowNavigationButtons" /%}{% batch datatype="boolean" /%}
- Controls the visibility of the `Back` button. Set to false if you don't want your users to navigate away from the current page.  
  Defaults to true.

---

- {% arguments name="SendLinkValidTill" /%}{% batch datatype="string" /%}
- Configures the expiration for the generated URL. A maximum of 180 days can be assigned. The String should be in date-time format.

---

- {% arguments name="Locale" /%}{% batch datatype="string" /%}
- By default, while opening the embedded request link, all the static contents available in the page will be loaded in the English language. This property is used to load the contents with different languages. The supported languages are EN(English), FR(French), NO(Norwegian), DE(German), ES(Spanish), BG(Bulgarian), CS(Czech), DA(Danish), IT(Italian), NL(Dutch), PL(Polish), PT(Portuguese), RO(Romanian), RU(Russian), and SV(Swedish)

---

- {% arguments name="ShowTooltip" /%}{% batch datatype="boolean" /%}
- To control the visibility of the `Tooltip` near the assignee field on the prepare page, set it to "true" if you want to show the tooltip to the user.  
  Defaults to false.

---

- {% arguments name="AllowScheduledSend" /%}{% batch datatype="boolean" /%}
- This property enables or disables the scheduling option. When enabled, it allows scheduling the document for future sending. The default value is `false`.

{% /nestedtable %}

### Example response

```json
{
    "documentId": "625cff3d...",
    "sendUrl": "https://app.boldsign.com/document/embed/?documentId=625cff3d..."
}
```