> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL.
>
> Documentation indexes by section:
> - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt
> - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt
> - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt
> - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt
>
> Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth
> Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks
>
> OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json
> MCP server: https://docusign.docs.buildwithfern.com/_mcp/server

# How to request a signature with third-party notarization

eSignature REST API 2.1 only

This topic demonstrates how to use the [eSignature REST API](/docs/esign-rest-api) to send a signature request with a third-party notary service using the [Notary On-Demand](/docs/notary-api/notary101/notary-on-demand) feature.

> **Note**
>
> Run this code example from our [Quickstart](/docs/esign-rest-api/quickstart) or launcher projects: [Bash](https://github.com/docusign/code-examples-bash), [C#](https://github.com/docusign/code-examples-csharp), [Java](https://github.com/docusign/code-examples-java), [Node.js](https://github.com/docusign/code-examples-node), [PHP](https://github.com/docusign/code-examples-php), [PowerShell](https://github.com/docusign/code-examples-powershell), [Python](https://github.com/docusign/code-examples-python), or [Ruby](https://github.com/docusign/code-examples-ruby).

## Required data

Running the code in this how-to requires this data:

| Data element          | Description                                                                                                                                                                                                                                                                                                            |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| \{API_ACCOUNT_ID}     | A [GUID](http://guid.one/) value that identifies your account. This value is automatically generated by Docusign for any account you create. Copy the value from the **API Account ID** field on the [Apps and Keys](https://admindemo.docusign.com/authenticate?goTo=appsAndKeys) page.                               |
| \{BASE_PATH}          | A string value that forms the root of the URL required to make API calls. The base path value in the example code is set to target the developer environment at https\://\<domain>/restapi Where \<domain> is demo.docusign.net for the developer environment and is the result of the GetUserInfo call in production. |
| \{CLIENT_USER_ID}     | A string value that serves as an identifier of an individual signer throughout the signing process. The combination of this value, the signer's name, and the signer's email is used to uniquely identify them.                                                                                                        |
| Document to be signed | You must provide at least one document to be signed. Document used in this how-to:- [DOCX file](https://github.com/docusign/code-examples-java/blob/master/src/main/resources/World_Wide_Corp_Battle_Plan_Trafalgar.docx)                                                                                              |
| \{RECIPIENT_ID}       | A unique string value that you assign to identify each recipient. This value assigns tabs on a per-[recipient](/docs/esign-rest-api/esign101/concepts/recipients) basis.                                                                                                                                               |
| \{SIGNER_EMAIL}       | A string value for the email address where the signer will receive a notification of the signing request.                                                                                                                                                                                                              |
| \{SIGNER_NAME}        | A string value for the full name of the signer.                                                                                                                                                                                                                                                                        |

## Step 1. Obtain your OAuth token

To make the API call shown in this how-to, you need a valid OAuth access token. Docusign supports access tokens for three different recommended OAuth grant types: Public Authorization Code Grant, Confidential Authorization Code Grant, and JSON Web Token (JWT) Grant. Choose the OAuth grant type appropriate for your scenario.

> **Note**
>
> See [Confidential Authorization Code Grant](/platform/auth/authcode#confidential-authorization-code-grant) for guidance on your options to get an Confidential Authorization Code Grant  OAuth token.

![Three icons that represent the three methods a user can use to obtain an OAuth token: JSON Web Token (JWT), Public Authorization Code Grant (ACG), and Confidential Authorization Code grant](/_fern-files/_img/64f473773042ee439449a096bf7673292b1585b86a4ccc55f82ba0dda41f61a1.webp)

## Step 2. Construct your API headers

After you have a valid OAuth access token, you are ready to construct the API headers that you will pass to the API call. Construct your headers like this, but make sure to substitute your valid OAuth access token for `{ACCESS_TOKEN}`.

**`Bash`**

```bash title="Bash"
declare -a Headers=('--header' "Authorization: Bearer ${ACCESS_TOKEN}" \
    '--header' "Accept: application/json" \
    '--header' "Content-Type: application/json")
```

**`C#`**

```csharp title="C#"
EnvelopeDefinition env = MakeEnvelope(signerEmail, signerName, envStatus);
var docuSignClient = new DocuSignClient(basePath);
docuSignClient.Configuration.DefaultHeader.Add("Authorization", "Bearer " + accessToken);
```

**`Java`**

```java title="Java"
protected static ApiClient createApiClient(String basePath, String userAccessToken) {
    ApiClient apiClient = new ApiClient(basePath);
    apiClient.addDefaultHeader(HttpHeaders.AUTHORIZATION, BEARER_AUTHENTICATION + userAccessToken);
    apiClient.addAuthorization("docusignAccessCode", new OAuth());
    return apiClient;
}
```

**`Node.js`**

```javascript title="Node.js"
let dsApiClient = new docusign.ApiClient();
dsApiClient.setBasePath(args.basePath);
dsApiClient.addDefaultHeader('Authorization', 'Bearer ' + args.accessToken);
let envelopesApi = new docusign.EnvelopesApi(dsApiClient);
```

**`PHP`**

```php title="PHP"
$config = new Configuration();
$config->setHost($args['base_path']);
$config->addDefaultHeader('Authorization', 'Bearer ' . $args['ds_access_token']);
$this->apiClient = new ApiClient($config);
```

**`PowerShell`**

```text title="PowerShell"
$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.add("Authorization", "Bearer $accessToken")
$headers.add("Content-Type", "application/json")
$headers.add("Accept", "application/json")
```

**`Python`**

```python title="Python"
api_client = create_api_client(base_path=args["base_path"], access_token=args["access_token"])
envelopes_api = EnvelopesApi(api_client)
```

**`Ruby`**

```ruby title="Ruby"
configuration = DocuSign_eSign::Configuration.new
configuration.host = args[:base_path]
api_client = DocuSign_eSign::ApiClient.new configuration

api_client.default_headers['Authorization'] = "Bearer #{args[:access_token]}"
```

## Step 3. Construct the envelope definition

Next, create the request body. The envelope definition will include at least two recipients: one notary and up to four signers. For each recipient, be sure to include the required properties and objects listed in the tables below.

### Notary recipient definition

The notary recipient definition must include, at minimum, these properties and objects.

| Property or object                                      | Set the value to                                                                                                                                                                                                                                                                          |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                                                  | A placeholder value for the name of the notary. Can be set to any value, including Notary or an empty string. After a notary has been assigned by the third-party provider, GET requests that return recipient information will include the name of the assigned notary in this property. |
| `recipientId`                                           | A unique numeric or GUID value.                                                                                                                                                                                                                                                           |
| `routingOrder`                                          | A value that indicates the order in which the envelope is to be delivered to this recipient. This value must be the same as the routingOrder for all signer recipients whose document is to be notarized by this notary.                                                                  |
| `notaryType`                                            | `remote`                                                                                                                                                                                                                                                                                  |
| `notarySourceType`                                      | `thirdparty`                                                                                                                                                                                                                                                                              |
| `notaryThirdPartyPartner`                               | `onenotary`                                                                                                                                                                                                                                                                               |
| `recipientSignatureProviders.sealDocumentsWithTabsOnly` | `false`                                                                                                                                                                                                                                                                                   |
| `recipientSignatureProviders.signatureProviderName`     | `ds_authority_idv`                                                                                                                                                                                                                                                                        |
| `tabs`                                                  | Any tabs that the notary must complete in the envelope. A notary recipient's tabs must include, at minimum, both of the following:- A `signHereTab` or an `initialHereTab`
- A `notarySealTab`                                                                                            |

### Signer recipient definition

The signer recipient definition must include, at minimum, these properties and objects.

| Property or object                                      | Set the value to                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                                                  | The signer’s name.                                                                                                                                                                                                                                                                                                                                                                                                  |
| `email`                                                 | The email address to which the online notary session invitation will be sent.                                                                                                                                                                                                                                                                                                                                       |
| `clientUserId`                                          | A value unique to this user. Although a `clientUserId` typically marks a recipient as signing in an embedded signing scenario, for Notary On-Demand, the signer receives an emailed link to the signing session rather than the signing session being embedded into your web application.                                                                                                                           |
| `recipientId`                                           | A unique numeric or GUID value.                                                                                                                                                                                                                                                                                                                                                                                     |
| `routingOrder`                                          | A value that indicates the order in which the envelope is to be delivered to this recipient. This value must be the same as the `routingOrder` for the notary recipient who will notarize this signer's document. All signers with the same `routingOrder` are members of the same notary group and are required to be signed into the online notary session concurrently in order for the session to be completed. |
| `notaryId`                                              | The `recipientId` of the notary recipient who will notarize this signer's envelope.                                                                                                                                                                                                                                                                                                                                 |
| `recipientSignatureProviders.sealDocumentsWithTabsOnly` | `false`                                                                                                                                                                                                                                                                                                                                                                                                             |
| `recipientSignatureProviders.signatureProviderName`     | `universalsignaturepen_imageonly`                                                                                                                                                                                                                                                                                                                                                                                   |
| `tabs`                                                  | Any tabs that the signer must complete in the envelope. A signer recipient must have, at minimum, a `signHereTab`.                                                                                                                                                                                                                                                                                                  |

**`Bash`**

```bash title="Bash"
printf \
'{
  "emailSubject": "Please sign this document set",
  "documents": [
        {
            "documentBase64": "' >> $request_data
                cat $doc_base64 >> $request_data
                printf '",
            "name": "Order acknowledgement",
            "fileExtension": "html",
            "documentId": "1",
        },
  ],
  "recipients": {
    "signers": [
      {
        "clientUserId": "1000",
        "email": "'"${SIGNER_EMAIL}"'",
        "name": "'"${SIGNER_NAME}"'",
        "recipientId": "2",
        "routingOrder": "1",
        "notaryId": "1",
        "tabs": {
          "signHereTabs": [
            {
              "documentId": "1",
              "xPosition": "200",
              "yPosition": "235",
              "pageNumber": "1",
            },
            {
              "stampType": "stamp",
              "documentId": "1",
              "xPosition": "200",
              "yPosition": "150",
              "pageNumber": "1",
            },
          ],
        },
      }
    ],
    "notaries": [
      {
        "name": "Notary",
        "recipientId": "1",
        "routingOrder": "1",
        "recipientSignatureProviders": [
          {
            "sealDocumentsWithTabsOnly": "false",
            "signatureProviderName": "ds_authority_idv"
          }
        ],
        "tabs": {
          "notarySealTabs": [
            {
              "xPosition": "300",
              "yPosition": "235",
              "documentId": "1",
              "pageNumber": "1",
            },
        ],
          "signHereTabs": [
            {
              "xPosition": "300",
              "yPosition": "150",
              "documentId": "1",
              "pageNumber": "1",
            },
          ]
        },
        "notaryType": "remote",
        "notarySourceType": "thirdparty",
        "notaryThirdPartyPartner": "onenotary"
      }
    ]
  },
  "status": "sent"
}' >> $request_data
```

**`C#`**

```csharp title="C#"
private static EnvelopeDefinition MakeEnvelope(string signerEmail, string signerName, string envStatus)
{
    var env = new EnvelopeDefinition
    {
        EmailSubject = "Please sign this document set",
    };

    env.Documents = GetDocuments(signerEmail, signerName);

    var signers = GetSigners(signerEmail, signerName);

    var notaryRecipients = GetNotaryRecipients();

    // Add the recipients to the envelope object
    var recipients = new Recipients
    {
        Signers = signers,
        Notaries = notaryRecipients,
    };
    env.Recipients = recipients;

    // Request that the envelope be sent by setting |status| to "sent".
    // To request that the envelope be created as a draft, set to "created"
    env.Status = envStatus;

    return env;
}

private static List<Document> GetDocuments(string signerEmail, string signerName)
{
    // Create document objects, one per document
    var doc1 = new Document();
    var b64 = Convert.ToBase64String(GetDocumentExample(signerEmail, signerName));
    doc1.DocumentBase64 = b64;
    doc1.Name = "Order acknowledgement"; // can be different from actual file name
    doc1.FileExtension = "html"; // Source data format. Signed docs are always pdf.
    doc1.DocumentId = "1"; // a label used to reference the doc

    return new List<Document> { doc1 };
}

private static byte[] GetDocumentExample(string signerEmail, string signerName)
{
    return Encoding.UTF8.GetBytes(" <!DOCTYPE html>\n"
                                  + "    <html>\n"
                                  + "        <head>\n"
                                  + "          <meta charset=\"UTF-8\">\n"
                                  + "        </head>\n"
                                  + "        <body style=\"font-family:sans-serif;margin-left:2em;\">\n"
                                  + "        <h1 style=\"font-family: 'Trebuchet MS', Helvetica, sans-serif;\n"
                                  + "            color: darkblue;margin-bottom: 0;\">World Wide Corp</h1>\n"
                                  + "        <h2 style=\"font-family: 'Trebuchet MS', Helvetica, sans-serif;\n"
                                  + "          margin-top: 0px;margin-bottom: 3.5em;font-size: 1em;\n"
                                  + "          color: darkblue;\">Order Processing Division</h2>\n"
                                  + "        <h4>Ordered by "
                                  + signerName
                                  + "</h4>\n"
                                  + "        <p style=\"margin-top:0em; margin-bottom:0em;\">Email: "
                                  + signerEmail
                                  + "</p>\n"
                                  + "        <p style=\"margin-top:3em;\">\n"
                                  + "  Candy bonbon pastry jujubes lollipop wafer biscuit biscuit. Topping brownie sesame snaps sweet roll pie. Croissant danish biscuit soufflé caramels jujubes jelly. Dragée danish caramels lemon drops dragée. Gummi bears cupcake biscuit tiramisu sugar plum pastry. Dragée gummies applicake pudding liquorice. Donut jujubes oat cake jelly-o. Dessert bear claw chocolate cake gummies lollipop sugar plum ice cream gummies cheesecake.\n"
                                  + "        </p>\n"
                                  + "        <!-- Note the anchor tag for the signature field is in white. -->\n"
                                  + "        <h3 style=\"margin-top:3em;\">Agreed: <span style=\"color:white;\">**signature_1**/</span></h3>\n"
                                  + "        </body>\n"
                                  + "    </html>");
}

private static List<Signer> GetSigners(string signerEmail, string signerName)
{
    // create a signer recipient to sign the document, identified by name and email
    // We're setting the parameters via the object creation
    var signer1 = new Signer
    {
        ClientUserId = "1000",
        Email = signerEmail,
        Name = signerName,
        RecipientId = "2",
        RoutingOrder = "1",
        NotaryId = "1",
    };

    // Create signHere fields (also known as tabs) on the documents,
    // We're using anchor (autoPlace) positioning
    //
    // The DocuSign platform searches throughout your envelope's
    // documents for matching anchor strings. So the
    // signHere2 tab will be used in both document 2 and 3 since they
    // use the same anchor string for their "signer 1" tabs.
    var signHere1 = new SignHere
    {
        DocumentId = "1",
        XPosition = "200",
        YPosition = "235",
        PageNumber = "1",
    };

    var signHere2 = new SignHere
    {
        StampType = "stamp",
        DocumentId = "1",
        XPosition = "200",
        YPosition = "150",
        PageNumber = "1",
    };

    // Tabs are set per recipient
    var signer1Tabs = new Tabs
    {
        SignHereTabs = new List<SignHere> { signHere1, signHere2 },
    };
    signer1.Tabs = signer1Tabs;

    return new List<Signer> { signer1 };
}

private static List<NotaryRecipient> GetNotaryRecipients()
{
    var notarySealTabs = new NotarySeal
    {
        XPosition = "300",
        YPosition = "235",
        DocumentId = "1",
        PageNumber = "1",
    };

    var notarySignHere = new SignHere
    {
        XPosition = "300",
        YPosition = "150",
        DocumentId = "1",
        PageNumber = "1",
    };

    var notaryTabs = new Tabs
    {
        SignHereTabs = new List<SignHere> { notarySignHere },
        NotarySealTabs = new List<NotarySeal> { notarySealTabs },
    };

    var notaryRecipient = new List<NotaryRecipient>
    {
        new NotaryRecipient
        {
            Email = string.Empty,
            Name = "Notary",
            RecipientId = "1",
            RoutingOrder = "1",
            Tabs = notaryTabs,
            NotaryType = "remote",
            NotarySourceType = "thirdparty",
            NotaryThirdPartyPartner = "onenotary",
            RecipientSignatureProviders = new List<RecipientSignatureProvider>
            {
                new RecipientSignatureProvider
                {
                    SealDocumentsWithTabsOnly = "false",
                    SignatureProviderName = "ds_authority_idv",
                    SignatureProviderOptions = new RecipientSignatureProviderOptions(),
                },
            },
        },
    };

    return notaryRecipient;
}
```

**`Java`**

```java title="Java"
private static EnvelopeDefinition makeEnvelope(String signerEmail, String signerName, WorkArguments args)
        throws IOException {
    EnvelopeDefinition envelopeDefinition = new EnvelopeDefinition();
    envelopeDefinition.setEmailSubject("Please sign this document set");

    envelopeDefinition.setDocuments(getDocuments(signerEmail, signerName, args));

    Recipients recipients = new Recipients();
    recipients.setSigners(getSigners(signerEmail, signerName));
    recipients.setNotaries(getNotaryRecipients());

    envelopeDefinition.setRecipients(recipients);
    envelopeDefinition.setStatus("sent");

    return envelopeDefinition;
}

private static java.util.List<Document> getDocuments(String signerEmail, String signerName, WorkArguments args)
        throws IOException {
    byte[] htmlDoc = EnvelopeHelpers.createHtmlFromTemplateFile(HTML_DOCUMENT_FILE_NAME, "args", args)
            .getBytes(StandardCharsets.UTF_8);
    Document document = EnvelopeHelpers.createDocument(htmlDoc, HTML_DOCUMENT_NAME,
            DocumentType.HTML.getDefaultFileExtention(), "1");

    return Collections.singletonList(document);
}

private static java.util.List<Signer> getSigners(String signerEmail, String signerName) {
    Signer signer = new Signer();
    signer.setClientUserId("1000");
    signer.setEmail(signerEmail);
    signer.setName(signerName);
    signer.setRecipientId("2");
    signer.setRoutingOrder("1");
    signer.setNotaryId("1");

    SignHere signHere1 = new SignHere();
    signHere1.setDocumentId("1");
    signHere1.setXPosition("200");
    signHere1.setYPosition("235");
    signHere1.setPageNumber("1");

    SignHere signHere2 = new SignHere();
    signHere2.setStampType("stamp");
    signHere2.setDocumentId("1");
    signHere2.setXPosition("200");
    signHere2.setYPosition("150");
    signHere2.setPageNumber("1");

    Tabs signerTabs = new Tabs();
    signerTabs.setSignHereTabs(java.util.Arrays.asList(signHere1, signHere2));
    signer.setTabs(signerTabs);

    return Collections.singletonList(signer);
}

private static java.util.List<NotaryRecipient> getNotaryRecipients() {
    NotarySeal notarySealTabs = new NotarySeal();
    notarySealTabs.setXPosition("300");
    notarySealTabs.setYPosition("235");
    notarySealTabs.setDocumentId("1");
    notarySealTabs.setPageNumber("1");

    SignHere notarySignHere = new SignHere();
    notarySignHere.setXPosition("300");
    notarySignHere.setYPosition("150");
    notarySignHere.setDocumentId("1");
    notarySignHere.setPageNumber("1");

    Tabs notaryTabs = new Tabs();
    notaryTabs.setSignHereTabs(Collections.singletonList(notarySignHere));
    notaryTabs.setNotarySealTabs(Collections.singletonList(notarySealTabs));

    NotaryRecipient notaryRecipient = new NotaryRecipient();
    notaryRecipient.setName("Notary");
    notaryRecipient.setRecipientId("1");
    notaryRecipient.setRoutingOrder("1");
    notaryRecipient.setTabs(notaryTabs);
    notaryRecipient.setNotaryType("remote");
    notaryRecipient.setNotarySourceType("thirdparty");
    notaryRecipient.setNotaryThirdPartyPartner("onenotary");

    RecipientSignatureProvider signatureProvider = new RecipientSignatureProvider();
    signatureProvider.setSealDocumentsWithTabsOnly("false");
    signatureProvider.setSignatureProviderName("ds_authority_idv");
    signatureProvider.setSignatureProviderOptions(new RecipientSignatureProviderOptions());

    notaryRecipient.setRecipientSignatureProviders(Collections.singletonList(signatureProvider));

    return Collections.singletonList(notaryRecipient);
}
```

**`Node.js`**

```javascript title="Node.js"
let envelope = makeEnvelope(args.envelopeArgs);
function makeEnvelope(args) {
// Data for this method
// args.signerEmail
// args.signerName
// args.status

// document 1 (html) has tag **signature_1**
//
// The envelope has two recipients.
// recipient 1 - signer
// The envelope will be sent first to the signer.
// After it is signed, a copy is sent to the cc person.

// create the envelope definition
let env = new docusign.EnvelopeDefinition();
env.emailSubject = 'Please sign this document set';

// add the documents
let doc1 = new docusign.Document();
  let doc1b64 = Buffer.from(document1(args)).toString('base64');
doc1.documentBase64 = doc1b64;
doc1.name = 'Order acknowledgement'; // can be different from actual file name
doc1.fileExtension = 'html'; // Source data format. Signed docs are always pdf.
doc1.documentId = '1'; // a label used to reference the doc

// The order in the docs array determines the order in the envelope
env.documents = [doc1];

// create a signer recipient to sign the document, identified by name and email
// We're setting the parameters via the object constructor
let signer1 = docusign.Signer.constructFromObject({
  email: args.signerEmail,
  name: args.signerName,
  recipientId: '2',
  routingOrder: '1',
  notaryId: '1',
  clientUserId: '1000',
});
// routingOrder (lower means earlier) determines the order of deliveries
// to the recipients. Parallel routing order is supported by using the
// same integer as the order for two or more recipients.

// Create signHere fields (also known as tabs) on the documents,
// We're using anchor (autoPlace) positioning
//
// The DocuSign platform searches throughout your envelope's
// documents for matching anchor strings. So the
// use the same anchor string for their "signer 1" tabs.
let signHere1 = docusign.SignHere.constructFromObject({
    xPosition: '200',
    yPosition: '235',
    pageNumber: '1',
    documentId: '1'
  });
  let signHere2 = docusign.SignHere.constructFromObject({
    stampType: 'stamp',
    documentId: '1',
    xPosition: '200',
    yPosition: '150',
    pageNumber: '1',

  });
// Tabs are set per recipient / signer
let signer1Tabs = docusign.Tabs.constructFromObject({
  signHereTabs: [signHere1, signHere2],
});
signer1.tabs = signer1Tabs;

const notarySealTab = {
  xPosition: '300',
  yPosition: '235',
  documentId: '1',
  pageNumber: '1',
};

const notarySignHereTab = {
  xPosition: '300',
  yPosition: '150',
  documentId: '1',
  pageNumber: '1',
};

const notaryTabs = {
  signHereTabs: [notarySignHereTab],
  notarySealTabs: [notarySealTab],
};

const notaryRecipient = [
  {
      name: 'Notary',
      recipientId: '1',
      routingOrder: '1',
      tabs: notaryTabs,
      notaryType: 'remote',
      notarySourceType: 'thirdparty',
      notaryThirdPartyPartner: 'onenotary',
      recipientSignatureProviders: [
        {
          sealDocumentsWithTabsOnly: 'false',
          signatureProviderName: 'ds_authority_idv',
          signatureProviderOptions: {}
        }
      ],
  },
];

// Add the recipients to the envelope object
let recipients = docusign.Recipients.constructFromObject({
  signers: [signer1],
  notaries: [...notaryRecipient],
});
env.recipients = recipients;

// Request that the envelope be sent by setting |status| to "sent".
// To request that the envelope be created as a draft, set to "created"
env.status = args.status;

return env;
}
```

**`PHP`**

```php title="PHP"
private static function makeEnvelope($signerEmail, $signerName, $demoPath): EnvelopeDefinition
{
    $env = new EnvelopeDefinition();
    $env->setEmailSubject("Please sign this document set");

    $env->setDocuments(SendWithThirdPartyNotaryService::getDocuments($signerEmail, $signerName, $demoPath));

    $recipients = new Recipients();
    $recipients->setSigners(SendWithThirdPartyNotaryService::getSigners($signerEmail, $signerName));
    $recipients->setNotaries(SendWithThirdPartyNotaryService::getNotaryRecipients());

    $env->setRecipients($recipients);
    $env->setStatus("sent");

    return $env;
}

private static function getDocuments($signerEmail, $signerName, $demoPath): array
{
    $doc = new Document();
    $b64 = base64_encode(SendWithThirdPartyNotaryService::getDocumentExample($signerEmail, $signerName, $demoPath));

    $doc->setDocumentBase64($b64);
    $doc->setName("Order acknowledgement");
    $doc->setFileExtension("html");
    $doc->setDocumentId("1");

    return [$doc];
}

private static function getDocumentExample($signerEmail, $signerName, $demoPath): string
{
    $htmlMarkupFileName = "order_form.html";
    $htmlMarkup = file_get_contents($demoPath . $htmlMarkupFileName);
    $htmlWithData = str_replace(
        [
            "{signer_name}",
            "{signer_email}"
        ],
        [
            $signerName,
            $signerEmail
        ],
        $htmlMarkup
    );
    return $htmlWithData;
}

private static function getSigners($signerEmail, $signerName)
{
    $signer = new Signer();
    $signer->setClientUserId("1000");
    $signer->setEmail($signerEmail);
    $signer->setName($signerName);
    $signer->setRecipientId("2");
    $signer->setRoutingOrder("1");
    $signer->setNotaryId("1");

    $signHere = new SignHere();
    $signHere->setDocumentId("1");
    $signHere->setXPosition("200");
    $signHere->setYPosition("235");
    $signHere->setPageNumber("1");

    $signHereWithStamp = new SignHere();
    $signHereWithStamp->setDocumentId("1");
    $signHereWithStamp->setXPosition("200");
    $signHereWithStamp->setYPosition("150");
    $signHereWithStamp->setPageNumber("1");
    $signHereWithStamp->setStampType("stamp");

    $tabs = new Tabs();
    $tabs->setSignHereTabs([$signHere, $signHereWithStamp]);
    $signer->setTabs($tabs);

    return [$signer];
}

private static function getNotaryRecipients(): array
{
    $notarySeal = new NotarySeal();
    $notarySeal->setXPosition("300");
    $notarySeal->setYPosition("235");
    $notarySeal->setDocumentId("1");
    $notarySeal->setPageNumber("1");

    $signHere = new SignHere();
    $signHere->setDocumentId("1");
    $signHere->setXPosition("300");
    $signHere->setYPosition("150");
    $signHere->setPageNumber("1");

    $tabs = new Tabs();
    $tabs->setSignHereTabs([$signHere]);
    $tabs->setNotarySealTabs([$notarySeal]);

    $notaryRecipient = new NotaryRecipient();
    $notaryRecipient->setEmail("");
    $notaryRecipient->setName("Notary");
    $notaryRecipient->setRecipientId("1");
    $notaryRecipient->setRoutingOrder("1");
    $notaryRecipient->setNotaryType("remote");
    $notaryRecipient->setNotarySourceType("thirdparty");
    $notaryRecipient->setNotaryThirdPartyPartner("onenotary");
    $notaryRecipient->setTabs($tabs);

    $signatureProvider = new RecipientSignatureProvider();
    $signatureProvider->setSignatureProviderName("ds_authority_idv");
    $signatureProvider->setSignatureProviderOptions(new RecipientSignatureProviderOptions());

    $notaryRecipient->setRecipientSignatureProviders([$signatureProvider]);

    return [$notaryRecipient];
}
```

**`PowerShell`**

```text title="PowerShell"
@{
    emailSubject = "Please sign this document set";
    documents    = @(
        @{
            documentBase64 = "$(Get-Content $docBase64)";
            name           = "Order acknowledgement";
            fileExtension  = "html";
            documentId     = "1";
        };
    );
    recipients   = @{
        signers      = @(
            @{
                clientUserId = "1000";
                email        = $variables.SIGNER_EMAIL;
                name         = $variables.SIGNER_NAME;
                recipientId  = "2";
                routingOrder = "1";
                notaryId     = "1";
                tabs         = @{
                    signHereTabs = @(
                        @{
                            documentId  = "1";
                            xPosition   = "200";
                            yPosition   = "235";
                            pageNumber  = "1";
                        };
                        @{
                            stampType   = "stamp";
                            documentId  = "1";
                            xPosition   = "200";
                            yPosition   = "150";
                            pageNumber  = "1";
                        };
                    );
                };
            };
        );
        notaries = @(
            @{
                name            = "Notary";
                recipientId     = "1";
                routingOrder    = "1";
                tabs            = @{
                    notarySealTabs = @(
                        @{
                            xPosition   = "300";
                            yPosition   = "235";
                            documentId  = "1";
                            pageNumber  = "1";
                        };
                    );
                    signHereTabs = @(
                        @{
                            xPosition   = "300";
                            yPosition   = "150";
                            documentId  = "1";
                            pageNumber  = "1";
                        };
                    );
                };
                notaryType              = "remote";
                notarySourceType        = "thirdparty";
                notaryThirdPartyPartner = "onenotary";
                recipientSignatureProviders = @(
                    @{
                        sealDocumentsWithTabsOnly   = "false";
                        signatureProviderName       = "ds_authority_idv";
                        signatureProviderOptions    = @{};
                    };
                );
            };
        );
    };
    status       = "sent";
} | ConvertTo-Json -Depth 32 > $requestData
```

**`Python`**

```python title="Python"
@classmethod
def make_envelope(cls, args):
    """
    Creates envelope
    Document 1: An HTML document.
    DocuSign will convert all of the documents to the PDF format.
    The recipients" field tags are placed using <b>anchor</b> strings.
    """

    # document 1 (html) has sign here anchor tag **signature_1**
    #
    # The envelope has two recipients.
    # recipient 1 - signer
    # The envelope will be sent first to the signer.

    # create the envelope definition
    env = EnvelopeDefinition(
        email_subject="Please sign this document set"
    )
    doc1_b64 = base64.b64encode(bytes(cls.create_document1(args), "utf-8")).decode("ascii")

    # Create the document models
    document1 = Document(  # create the DocuSign document object
        document_base64=doc1_b64,
        name="Order acknowledgement",  # can be different from actual file name
        file_extension="html",  # many different document types are accepted
        document_id="1"  # a label used to reference the doc
    )
    # The order in the docs array determines the order in the envelope
    env.documents = [document1]

    # Create the signer recipient model
    signer1 = Signer(
        email=args["signer_email"],
        name=args["signer_name"],
        recipient_id="2",
        routing_order="1",
        client_user_id="1000",
        notary_id="1"
    )
    # routingOrder (lower means earlier) determines the order of deliveries
    # to the recipients. Parallel routing order is supported by using the
    # same integer as the order for two or more recipients.

    # Create signHere fields (also known as tabs) on the documents,
    # We"re using anchor (autoPlace) positioning
    #
    # The DocuSign platform searches throughout your envelope"s
    # documents for matching anchor strings. So the
    # signHere2 tab will be used in both document 2 and 3 since they
    # use the same anchor string for their "signer 1" tabs.
    sign_here1 = SignHere(
        document_id="1",
        x_position="200",
        y_position="235",
        page_number="1"
    )

    sign_here2 = SignHere(
        stamp_type="stamp",
        document_id="1",
        x_position="200",
        y_position="150",
        page_number="1"

    )

    # Add the tabs model (including the sign_here tabs) to the signer
    # The Tabs object wants arrays of the different field/tab types
    signer1.tabs = Tabs(sign_here_tabs=[sign_here1, sign_here2])

    notary_seal_tab = NotarySeal(
        x_position = "300",
        y_position = "235",
        document_id = "1",
        page_number = "1",
    )

    notary_sign_here = SignHere(
        x_position = "300",
        y_position = "150",
        document_id = "1",
        page_number = "1",
    )

    notary_tabs = Tabs(
        sign_here_tabs = [notary_sign_here],
        notary_seal_tabs = [ notary_seal_tab ],
    )

    recipient_signature_provider = RecipientSignatureProvider(
        seal_documents_with_tabs_only = "false",
        signature_provider_name = "ds_authority_idv",
        signature_provider_options = RecipientSignatureProviderOptions()
    )

    notary_recipient = NotaryRecipient(
        name = "Notary",
        recipient_id = "1",
        routing_order = "1",
        tabs = notary_tabs,
        notary_type = "remote",
        notary_source_type = "thirdparty",
        notary_third_party_partner = "onenotary",
        recipient_signature_providers = [recipient_signature_provider]
    )

    # Add the recipients to the envelope object
    recipients = Recipients(signers=[signer1], notaries= [notary_recipient])
    env.recipients = recipients

    # Request that the envelope be sent by setting |status| to "sent".
    # To request that the envelope be created as a draft, set to "created"
    env.status = args["status"]

    return env

@classmethod
def create_document1(cls, args):
    """ Creates document 1 -- an html document"""

    return f"""
    <!DOCTYPE html>
    <html>
        <head>
          <meta charset="UTF-8">
        </head>
        <body style="font-family:sans-serif;margin-left:2em;">
        <h1 style="font-family: "Trebuchet MS", Helvetica, sans-serif;
            color: darkblue;margin-bottom: 0;">World Wide Corp</h1>
        <h2 style="font-family: "Trebuchet MS", Helvetica, sans-serif;
          margin-top: 0px;margin-bottom: 3.5em;font-size: 1em;
          color: darkblue;">Order Processing Division</h2>
        <h4>Ordered by {args["signer_name"]}</h4>
        <p style="margin-top:0em; margin-bottom:0em;">Email: {args["signer_email"]}</p>
        <p style="margin-top:3em;">
            Candy bonbon pastry jujubes lollipop wafer biscuit biscuit. Topping brownie sesame snaps sweet roll pie.
            Croissant danish biscuit soufflé caramels jujubes jelly. Dragée danish caramels lemon drops dragée.
            Gummi bears cupcake biscuit tiramisu sugar plum pastry. Dragée gummies applicake pudding liquorice.
            Donut jujubes oat cake jelly-o.
            Dessert bear claw chocolate cake gummies lollipop sugar plum ice cream gummies cheesecake.
        </p>
        <!-- Note the anchor tag for the signature field is in white. -->
        <h3 style="margin-top:3em;">Agreed: <span style="color:white;">**signature_1**/</span></h3>
        </body>
    </html>
    """
```

**`Ruby`**

```ruby title="Ruby"
def make_envelope(envelope_args)
  # The envelope has two recipients:
  # recipient 1 - notary
  # recipient 2 - signer
  # The envelope will be sent first to the signer.
  # After it is signed, a copy is sent to the cc person

  # Create the envelope definition
  envelope_definition = DocuSign_eSign::EnvelopeDefinition.new

  envelope_definition.email_subject = 'Please sign this document set'

  # Add the document
  doc_b64 = Base64.encode64(File.binread(envelope_args[:doc_path]))

  # Create the document model
  document = DocuSign_eSign::Document.new(
    # Create the Docusign document object
    documentBase64: doc_b64,
    name: 'Order acknowledgement', # Can be different from actual file name
    fileExtension: 'html', # Many different document types are accepted
    documentId: '1' # A label used to reference the doc
  )

  # The order in the docs array determines the order in the envelope
  envelope_definition.documents = [document]

  sign_here_1 = DocuSign_eSign::SignHere.new(
    documentId: '1',
    xPosition: '200',
    yPosition: '235',
    pageNumber: '1'
  )
  sign_here_2 = DocuSign_eSign::SignHere.new(
    stampType: 'stamp',
    documentId: '1',
    xPosition: '200',
    yPosition: '150',
    pageNumber: '1'
  )

  # Add the tabs model (including the sign_here tabs) to the signer
  # The Tabs object takes arrays of the different field/tab types
  signer_tab = DocuSign_eSign::Tabs.new(
    signHereTabs: [sign_here_1, sign_here_2]
  )

  # Create the signer recipient model
  signer = DocuSign_eSign::Signer.new(
    clientUserId: '1000',
    email: envelope_args[:signer_email],
    name: envelope_args[:signer_name],
    recipientId: '2',
    routingOrder: '1',
    notaryId: '1',
    tabs: signer_tab
  )

  notary_seal = DocuSign_eSign::NotarySeal.new(
    xPosition: '300',
    yPosition: '235',
    documentId: '1',
    pageNumber: '1'
  )

  notary_sign_here = DocuSign_eSign::SignHere.new(
    xPosition: '300',
    yPosition: '150',
    documentId: '1',
    pageNumber: '1'
  )

  notary_tabs = DocuSign_eSign::Tabs.new(
    signHereTabs: [notary_sign_here],
    notarySealTabs: [notary_seal]
  )

  notary_recipient = DocuSign_eSign::NotaryRecipient.new(
    name: 'Notary',
    recipientId: '1',
    routingOrder: '1',
    tabs: notary_tabs,
    notaryType: 'remote',
    notarySourceType: 'thirdparty',
    notaryThirdPartyPartner: 'onenotary',
    recipientSignatureProviders: [
      {
        sealDocumentsWithTabsOnly: 'false',
        signatureProviderName: 'ds_authority_idv',
        signatureProviderOptions: {}
      }
    ]
  )

  # Add the recipients to the envelope object
  recipients = DocuSign_eSign::Recipients.new(
    signers: [signer],
    notaries: [notary_recipient]
  )
  # Request that the envelope be sent by setting status to "sent".
  # To request that the envelope be created as a draft, set status to "created"
  envelope_definition.recipients = recipients
  envelope_definition.status = 'sent'
  envelope_definition
end
```

## Step 4. Call the eSignature REST API

Now that you have constructed your API headers and request body, make a POST request to the [Envelopes:create](/docs/esign-rest-api/reference/envelopes/envelopes/create) endpoint and include the request body to send the envelope. Here’s how you make the call, but make sure to substitute your API account ID for `{ACCOUNT_ID}`.

> **Note**
>
> View the source code for this how-to on GitHub: [Bash](https://github.com/docusign/code-examples-bash/blob/master/examples/Notary/eg004SendWithThirdPartyNotary.sh), [C#](https://github.com/docusign/code-examples-csharp/blob/master/launcher-csharp/Notary/Examples/SendWithThirdPartyNotary.cs), [Java](https://github.com/docusign/code-examples-java/blob/master/src/main/java/com/docusign/controller/notary/services/SendWithThirdPartyNotaryService.java), [Node.js](https://github.com/docusign/code-examples-node/blob/master/lib/notary/examples/sendThirdPartyNotary.js),  [PHP](https://github.com/docusign/code-examples-php/blob/master/src/Services/Examples/Notary/SendWithThirdPartyNotaryService.php), [PowerShell](https://github.com/docusign/code-examples-powershell/blob/master/examples/Notary/sendWithThirdPartyNotary.ps1), [Python](https://github.com/docusign/code-examples-python/blob/master/app/notary/examples/eg004_send_with_third_party_notary.py) or [Ruby](https://github.com/docusign/code-examples-ruby/blob/master/app/services/notary/eg004_send_with_third_party_notary_service.rb).

**`Bash`**

```bash title="Bash"
curl --data-binary @${request_data} \
     --request POST ${base_path}/v2.1/accounts/${ACCOUNT_ID}/envelopes \
     "${Headers[@]}" \
     --output ${response}
```

**`C#`**

```csharp title="C#"
var envelopesApi = new EnvelopesApi(docuSignClient);
ApiResponse<EnvelopeSummary> results = envelopesApi.CreateEnvelopeWithHttpInfo(accountId, env);

results.Headers.TryGetValue("X-RateLimit-Remaining", out string remaining);
results.Headers.TryGetValue("X-RateLimit-Reset", out string reset);

if (reset != null && remaining != null)
{
    DateTime resetDate = DateTimeOffset.FromUnixTimeSeconds(long.Parse(reset)).UtcDateTime;
    Console.WriteLine("API calls remaining: " + remaining);
    Console.WriteLine("Next Reset: " + resetDate);
}

return results.Data.EnvelopeId;
```

**`Java`**

```java title="Java"
public static String sendWithNotary(String signerEmail, String signerName, String accountId,
        EnvelopesApi envelopesApi, WorkArguments args)
        throws ApiException, com.docusign.esign.client.ApiException, IOException {
    EnvelopeDefinition envelopeDefinition = makeEnvelope(signerEmail, signerName, args);

    ApiResponse<EnvelopeSummary> envelopeSummary = envelopesApi.createEnvelopeWithHttpInfo(accountId,
            envelopeDefinition, (CreateEnvelopeOptions) null);

    Map<String, List<String>> headers = envelopeSummary.getHeaders();
    List<String> remaining = headers.get("X-RateLimit-Remaining");
    List<String> reset = headers.get("X-RateLimit-Reset");

    if (remaining != null & reset != null) {
        Instant resetInstant = Instant.ofEpochSecond(Long.parseLong(reset.get(0)));
        System.out.println("API calls remaining: " + remaining);
        System.out.println("Next Reset: " + resetInstant);
    }

    return envelopeSummary.getData().getEnvelopeId();
}
```

**`Node.js`**

```javascript title="Node.js"
results = await envelopesApi.createEnvelope(args.accountId, {
  envelopeDefinition: envelope,
}, (error, data, response) => {
    const headers = response?.headers;

    const remaining = headers?.['x-ratelimit-remaining'];
    const reset = headers?.['x-ratelimit-reset'];

    if (remaining && reset) {
      const resetInstant = new Date(Number(reset) * 1000);

      console.log(`API calls remaining: ${remaining}`);
      console.log(`Next Reset: ${resetInstant.toISOString()}`);
    }
});
let envelopeId = results.data.envelopeId;
```

**`PHP`**

```php title="PHP"
public static function sendWithNotary($signerEmail, $signerName, $envelopesApi, $accountId, $demoPath): mixed
{
    $env = SendWithThirdPartyNotaryService::makeEnvelope($signerEmail, $signerName, $demoPath);

    $results = $envelopesApi->createEnvelopeWithHttpInfo($accountId, $env);
    $remaining = $results[2]['X-RateLimit-Remaining'] ?? null;
    $reset = $results[2]['X-RateLimit-Reset'] ?? null;

    if ($remaining !== null && $reset !== null) {
        $resetInstant = (new DateTime())->setTimestamp((int)$reset);
        error_log("API calls remaining: $remaining");
        error_log("Next Reset: " . $resetInstant->format(\DateTime::ATOM));
    }
    return $results[0];
}
```

**`PowerShell`**

```text title="PowerShell"
Invoke-RestMethod `
    -Uri "${apiUri}/v2.1/accounts/${accountId}/envelopes" `
    -Method 'POST' `
    -Headers $headers `
    -InFile (Resolve-Path $requestData).Path `
    -OutFile $response
```

**`Python`**

```python title="Python"
(results, status, headers) = envelopes_api.create_envelope_with_http_info(account_id=args["account_id"], envelope_definition=envelope_definition)

remaining = headers.get("X-RateLimit-Remaining")
reset = headers.get("X-RateLimit-Reset")

if remaining is not None and reset is not None:
    reset_date = dt.fromtimestamp(int(reset), tz=timezone.utc)
    print(f"API calls remaining: {remaining}")
    print(f"Next Reset: {reset_date}")
```

**`Ruby`**

```ruby title="Ruby"
envelope_definition = make_envelope args[:envelope_args]
# Call Envelopes::create API method
# Exceptions will be caught by the calling function
envelope_api = create_envelope_api(args)

results, _status, headers = envelope_api.create_envelope_with_http_info args[:account_id], envelope_definition

remaining = headers['X-RateLimit-Remaining']
reset = headers['X-RateLimit-Reset']

if remaining && reset
  reset_date = Time.at(reset.to_i).utc
  puts "API calls remaining: #{remaining}"
  puts "Next Reset: #{reset_date}"
end

envelope_id = results.envelope_id
{ 'envelope_id' => envelope_id }
```

## Expected response

If you run this code example from our Quickstart or launcher projects, you should see a JSON response similar to the code shown.

> **Note**
>
> On the developer environment, if **Suppress emails to embedded signers** is enabled in your account’s Signing Settings, notary session invitation emails are not sent to signers. On production, by default, enabling this setting does not prevent invitation emails from being sent. If you would like to enable this behavior for your account on production, contact [Docusign Support](https://support.docusign.com/s/contactSupport). See [Envelope Delivery](https://support.docusign.com/s/document-item?bundleId=pik1583277475390\&topicId=fur1583277359739.html) for more information about the setting.

**`Sample response`**

```json title="Sample response"
{
"envelopeId":"7afe0361-xxxx-xxxx-xxxx-7c17623b0555",
"uri":"/envelopes/7afe0361-xxxx-xxxx-xxxx-7c17623b0555",
"statusDateTime":"2025-01-21T22:33:16.9870000Z",
"status":"sent"
}
```

## Next steps

* Run this code example from our [Quickstart](/docs/esign-rest-api/quickstart) or launcher projects:    [Bash](https://github.com/docusign/code-examples-bash), [C#](https://github.com/docusign/code-examples-csharp), [Java](https://github.com/docusign/code-examples-java), [Node.js](https://github.com/docusign/code-examples-node), [PHP](https://github.com/docusign/code-examples-php), [PowerShell](https://github.com/docusign/code-examples-powershell), [Python](https://github.com/docusign/code-examples-python), or [Ruby](https://github.com/docusign/code-examples-ruby).
* Learn more about [Notary On-Demand](/docs/notary-api/notary101/notary-on-demand).
* Get an overview of other notary options in the [Notary feature comparison](/docs/notary-api/notary101/notary-feature-comparison).
* See how to [Go-Live](/docs/esign-rest-api/go-live) with a completed app and find the base path for API calls in the production environment.