{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-products/namirialsignenterprise/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Send Your First Envelope","description":"Integration and usage documentation."},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"send-your-first-envelope","__idx":0},"children":["Send Your First Envelope"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide walks you through sending a signing request using the NSE API v1. By the end you will have created an envelope, uploaded a document, added a signer, placed a signature field, and sent the envelope — all via API."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":1},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A valid ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["JWT Bearer token"]}," or ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Personal Access Token"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["organization ID"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["organizationId"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A document ready to upload"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1--create-an-envelope","__idx":2},"children":["Step 1 — Create an Envelope"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Start by creating an envelope. This is the container for your documents and recipients. It is created in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["draft"]}," status and stays editable until you send it."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In most integrations you will at minimum give it a name and set an expiration. Here we use a relative expiration — 14 days after sending (expressed in seconds)."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /api/v1/organizations/{organizationId}/envelopes\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"name\": \"Lease Agreement\",\n  \"expiration\": {\n    \"mode\": \"relative\",\n    \"afterSendInSeconds\": 1209600\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201 Created"]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"a1b2c3d4-1234-1234-1234-ef1234567890\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Save the returned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," — this is your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["envelopeId"]}," for every subsequent call."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2--upload-a-document","__idx":3},"children":["Step 2 — Upload a Document"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Upload the PDF that your recipient will sign. This endpoint uses ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["multipart/form-data"]},", not JSON."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Note: The max file size is 10MB and an envelope can max have 10 documents."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/files\nContent-Type: multipart/form-data\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["file"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["binary"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The PDF file to attach"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201 Created"]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"3fa85f64-1234-1234-1234-2c963f66afa6\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Save the returned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," — this is your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fileId"]},", used when placing the signature field."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3--add-a-signing-stage","__idx":4},"children":["Step 3 — Add a Signing Stage"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A stage represents a step in the signing workflow. Recipients in the same stage sign in parallel; stages execute in order. For this example, one stage with one signer is enough."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/stages\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"name\": \"Signers\",\n  \"requiredRecipientCompletions\": 1,\n  \"type\": \"signer\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201 Created"]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"5c367bac-1234-1234-1234-08f3025e28ab\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Save the returned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," — this is your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stageId"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-4--add-a-recipient","__idx":5},"children":["Step 4 — Add a Recipient"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add the person who will sign the document to the stage you just created."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/stages/{stageId}/recipients\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"givenName\": \"John\",\n  \"surname\": \"Doe\",\n  \"email\": \"john.doe@example.com\",\n  \"notificationChannels\": [\n    \"email\"\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201 Created"]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"4e861e0f-1234-1234-1234-58bd9928b4a8\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Save the returned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," — this is your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipientId"]},", used when placing the signature field."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-5--place-a-signature-field","__idx":6},"children":["Step 5 — Place a Signature Field"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add now all the fields which should appear on the document and add who should sign it. This call fully replaces all tasks for the file, so send the complete list each time."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each task wraps a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["field"]}," definition with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipientId"]}," and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sortOrder"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"PUT /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/files/{fileId}/tasks\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"tasks\": [\n    {\n      \"field\": {\n        \"fieldType\": \"Signature\",\n        \"id\": \"field-001\",\n        \"page\": 1,\n        \"positionX\": 100,\n        \"positionY\": 650,\n        \"width\": 200,\n        \"height\": 60,\n        \"allowedSignatureTypes\": [\n          { \"signatureType\": \"ClickToSignSignature\" },\n          { \"signatureType\": \"DrawToSignSignature\" }\n        ]\n      },\n      \"recipientId\": \"4e861e0f-1234-1234-1234-58bd9928b4a8\",\n      \"sortOrder\": 1\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A few things worth noting:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["positionX"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["positionY"]}," are the coordinates of the field's top-left corner on the page."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowedSignatureTypes"]}," controls which signing methods the recipient can choose. If you leave it ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]},", the organization defaults apply."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sortOrder"]}," sets the sequence in which fields are presented to the signer."," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["204 No Content"]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-6--send-the-envelope","__idx":7},"children":["Step 6 — Send the Envelope"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once everything is configured, send the envelope. This transitions the envelope from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["draft"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sent"]}," and triggers the invitation email to your recipient."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/send\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["No request body required."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["204 No Content"]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-7--check-the-envelope-status","__idx":8},"children":["Step 7 — Check the Envelope Status"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Poll this endpoint to track progress."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"GET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200 OK"]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"a1b2c3d4-1234-1234-1234-ef1234567890\",\n  \"name\": \"Lease Agreement\",\n  \"status\": \"completed\",\n  \"sentAt\": \"2026-04-20T10:05:00Z\"\n  ...\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-8--download-the-signed-document","__idx":9},"children":["Step 8 — Download the Signed Document"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once the envelope is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["completed"]},", retrieve the signed file and the audit trail."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["List what is available:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"GET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/artifacts\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"artifacts\": [\n    {\n      \"id\": \"0a9e87c0-1234-1234-1234-99c8c87a9a33\",\n      \"name\": \"LeaseAgreement.pdf\",\n      \"type\": \"CompletedFile\"\n    },\n    {\n      \"id\": \"1b8f76b1-1234-1234-1234-aada9b8bab44\",\n      \"name\": \"Audit Trail.pdf\",\n      \"type\": \"AuditTrail\"\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Download a specific artifact:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"GET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/artifacts/{artifactId}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Returns the file as a binary stream (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/pdf"]},")."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"whats-next","__idx":10},"children":["What's Next"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide covered the essential flow. The full API reference describes additional options available at each step, including:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Envelope:"]}," automatic reminders, absolute expiration dates"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Stages:"]}," parallel signing, approval-only stages (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Approver"]},"), carbon copy (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CarbonCopy"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Recipients:"]}," SMS/OTP authentication, access codes, QES certificate configuration"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Fields:"]}," text inputs, checkboxes, dropdowns, read confirmations, and more"]}]}]},"headings":[{"value":"Send Your First Envelope","id":"send-your-first-envelope","depth":1},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Step 1 — Create an Envelope","id":"step-1--create-an-envelope","depth":2},{"value":"Step 2 — Upload a Document","id":"step-2--upload-a-document","depth":2},{"value":"Step 3 — Add a Signing Stage","id":"step-3--add-a-signing-stage","depth":2},{"value":"Step 4 — Add a Recipient","id":"step-4--add-a-recipient","depth":2},{"value":"Step 5 — Place a Signature Field","id":"step-5--place-a-signature-field","depth":2},{"value":"Step 6 — Send the Envelope","id":"step-6--send-the-envelope","depth":2},{"value":"Step 7 — Check the Envelope Status","id":"step-7--check-the-envelope-status","depth":2},{"value":"Step 8 — Download the Signed Document","id":"step-8--download-the-signed-document","depth":2},{"value":"What's Next","id":"whats-next","depth":2}],"frontmatter":{"seo":{"title":"Send Your First Envelope"}},"lastModified":"2026-10-20T09:21:39.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/namirialsignenterprise/namirialsignenterprise-knowledge-center/03-developer-documentation/01-api-reference/basic-envelope-workflow","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}