Guides
Status PageRoadmapTestimonies

How to guide - Create your first Signature Request

You can create your first SR in three steps only.

Suggest Edits

Here is a step-by-step guide to create your first Signature Request.

  1. Initiate your Signature Request
  2. Add a Document
  3. Add a Signer
  4. Add a signature Field
  5. Activate the Signature Request
  6. Sign the document
  7. Retrieve the Signature Request status

➡️ Before getting started, make sure you have correctly setup your account. Follow this guide for more details.

➡️ To make your first steps using our API, you can use our Postman collection. Follow this guide for more details.

Step 1: Create the Signature Request

The delivery_mode is set to email, this means we will let Yousign deliver the Signature Request to the Signer by email. Learn more about deliver modes here.

{
    "name": "My Signature Request",
    "delivery_mode": "email"
}

{
    "id": "6f7001fc...",
    "source": "public_api",
    "status": "draft",
    "name": "My Signature Request",
    "created_at": "2025-01-10T16:59:20+00:00",
    "email_custom_note": null,
    "ordered_signers": false,
    "timezone": "Europe/Paris",
    "reminder_settings": null,
    "expiration_date": "2025-07-10T21:59:59+00:00",
    "delivery_mode": "email",
    "documents": [],
    "signers": [],
    "external_id": null,
    "branding_id": null,
    "custom_experience_id": null,
    "sender": null,
    "workspace_id": "8d49eedc...",
    "audit_trail_locale": "en",
    "signers_allowed_to_decline": false,
    "bulk_send_batch_id": null,
    "email_notification": {
        "sender": {
            "type": "organization",
            "custom_name": null
        },
        "custom_note": null
    }
}

Step 2: Add a Document to the Signature Request

The nature is set to signable_document, this means the document will be signed by a Signer (the other nature is attachment).

--form 'file=@"/path/to/the/document/my_document.pdf"' \
--form 'nature="signable_document"'

{
    "id": "c7afe88f...",
    "filename": "my_document.pdf",
    "nature": "signable_document",
    "content_type": "application/pdf",
    "sha256": "9c75416c8160...",
    "is_protected": false,
    "is_signed": false,
    "created_at": "2025-01-10T17:01:10+00:00",
    "total_pages": 3,
    "is_locked": false,
    "initials": null,
    "total_anchors": 0
}

Step 3: Add a Signer to the Signature Request

  • Endpoint: Create a new Signer (POST /signature_requests/{signatureRequestId}/signers)
  • Content type: application/json

The signature_level is set to electronic_signature, this means the document will be signed with the Simple Electronic Signature (SES) level. This is the simplest and fastest form of use for documents that do not require a formal identity verification process. Learn more about signature levels here.

The signature_authentication_mode is set to no_otp, this means the Signer will not be required to enter a one-time passowrd (OTP) to authenticate themselves before signing. Learn more about authentication modes here.

{
  "info": {
    "first_name": "Kelly",
    "last_name": "Smith",
    "email": "[email protected]",
    "locale": "en"
  },
  "signature_level": "electronic_signature",
  "signature_authentication_mode": "no_otp"
}

{
    "id": "a3e3bf85...",
    "info": {
        "first_name": "Kelly",
        "last_name": "Smith",
        "email": "[email protected]",
        "phone_number": null,
        "locale": "en"
    },
    "status": "initiated",
    "signature_link": null,
    "signature_link_expiration_date": null,
    "signature_image_preview": "https://api.yousign.tech/signature_requests/49176816...",
    "fields": null,
    "signature_level": "electronic_signature",
    "signature_authentication_mode": "no_otp",
    "redirect_urls": {
        "success": null,
        "error": null,
        "decline": null
    },
    "custom_text": {
        "request_subject": null,
        "request_body": null,
        "reminder_subject": null,
        "reminder_body": null
    },
    "delivery_mode": null,
    "identification_attestation_id": null,
    "sms_notification": {
        "otp_message": {
            "custom_text": null
        }
    },
    "email_notification": {
        "disabled": []
    }
}

Step 4: Add a signature Field

The Field type is set to signature, this means this field will contain the Signers’ signature image (the other types are mention, text, checkbox, etc.).

Don’t forget to replace the {signerId} variable with the actual Signer ID.

The page parameter determines the Document page on which the Field will appear.

The x and y parameters are the coordinates of the Field on the page.

💡

You can use our PlaceIt tool to help you find the coordinates.

{
  "type": "signature",
  "signer_id": "{signerId}",
  "page": 1,
  "x": 200,
  "y": 400
}

{
    "id": "48728d65...",
    "document_id": "c7afe88f...",
    "type": "signature",
    "page": 1,
    "x": 200,
    "y": 400,
    "signer_id": "a3e3bf85...",
    "width": 85,
    "height": 37,
    "reason": null
}

Step 5: Activate the Signature Request

Endpoint: Activate a Signature Request (POST /signature_requests/{signatureRequestId}/activate)

// no request body required

{
    "id": "49176816-00d1-44e2-93dd-25306663bd40",
    "status": "ongoing",
    "name": "My Signature Request",
    "created_at": "2025-01-10T17:22:38+00:00",
    "email_custom_note": null,
    "ordered_signers": false,
    "timezone": "Europe/Paris",
    "reminder_settings": null,
    "expiration_date": "2025-07-10T21:59:59+00:00",
    "signers": [
        {
            "id": "a3e3bf85...",
            "status": "initiated",
            "delivery_mode": null,
            "signature_link": "https://app.yousign.tech/signatures/49176816...",
            "signature_link_expiration_date": "2025-01-12T17:24:13+00:00"
        }
    ],
    "approvers": [],
    "labels": [],
    "documents": [
        {
            "id": "c7afe88f...",
            "nature": "signable_document"
        }
    ],
    "delivery_mode": "email",
    "external_id": null,
    "branding_id": null,
    "custom_experience_id": null,
    "sender": null,
    "workspace_id": "8d49eedc...",
    "audit_trail_locale": "en",
    "signers_allowed_to_decline": false,
    "email_notification": {
        "sender": {
            "type": "organization",
            "custom_name": null
        },
        "custom_note": null
    }
}

Congratulations! You have activated your first Signature Request🎉

The Signer will receive an email inviting them to sign the Document. The Signature Request’s status is now ongoing.

Step 6: Retrieve the Signature Request status

Endpoint: Fetch a Signature Request (GET /signature_requests/{signatureRequestId})

Once the Signer has signed the document, the Signature Request’s status will change from ongoing to done.

// no request body required

{
    "approvers": [],
    "labels": [],
    "decline_information": null,
    "id": "6f7001fc...",
    "source": "public_api",
    "status": "done",
    "name": "My Signature Request",
    "created_at": "2025-01-10T17:22:38+00:00",
    "email_custom_note": null,
    "ordered_signers": false,
    "timezone": "Europe/Paris",
    "reminder_settings": null,
    "expiration_date": "2025-07-10T21:59:59+00:00",
    "delivery_mode": "email",
    "documents": [
        {
            "id": "c7afe88f...",
            "nature": "signable_document"
        }
    ],
    "signers": [
        {
            "id": "a3e3bf85...",
            "status": "signed",
            "delivery_mode": null
        }
    ],
    "external_id": null,
    "branding_id": null,
    "custom_experience_id": null,
    "sender": null,
    "workspace_id": "8d49eedc...",
    "audit_trail_locale": "en",
    "signers_allowed_to_decline": false,
    "bulk_send_batch_id": null,
    "email_notification": {
        "sender": {
            "type": "organization",
            "custom_name": null
        },
        "custom_note": null
    }
}

You can subscribe to webhooks to can get real-time notifications about the Signature Request’s status changes.

⏩

Use Templates to create Signature Requests even more rapidly

You can create Templates in the Yousign app, and use those Templates to create Signature Requests in no time. These Templates allow you to pre-configure all aspects of a Signature Request, such as the Document, Signers, Fields, and settings.

Learn more about Templates here.

Updated 2 days ago