HelloSign Getting Started: API Integration & First Request (2026)

Getting started overview

Integrating HelloSign into an application involves creating a developer account, generating API credentials, and sending a request to the HelloSign API. This process typically begins in a sandbox environment to facilitate testing and development without affecting production data or incurring live costs. HelloSign provides a RESTful API and client libraries (SDKs) to streamline integration across various programming languages. The platform supports key e-signature workflows, including sending documents for signature, embedding signing experiences, and managing signed documents.

The following table outlines the foundational steps for initiating a HelloSign integration:

Create an account and get keys

To begin using the HelloSign API, you must first create a HelloSign account. While a personal account allows for manual document signing, API access requires a plan that includes developer features. HelloSign offers a free tier that supports up to three documents per month, which is suitable for initial API exploration and testing. For more extensive API usage, paid plans starting at $99/month are available.

1. Sign Up: Navigate to the HelloSign pricing page and select a plan. The free plan is sufficient for initial API key generation and sandbox testing.
2. Access API Dashboard: Once your account is active, log in and access the API section of your HelloSign dashboard. This is typically found under 'Integrations' or 'API' settings.
3. Generate API Key: Within the API dashboard, locate the option to generate a new API key. HelloSign API keys are unique identifiers used to authenticate your application with the HelloSign API. Treat your API key as sensitive information, similar to a password. It grants access to your HelloSign account's API functionalities.
4. Copy API Key: After generation, copy the API key. It will be a long alphanumeric string. Store it securely in your application's environment variables or a secure configuration management system rather than hardcoding it directly into your source code. This practice aligns with security best practices for API key management, as recommended by organizations like Google Cloud's API key security guidelines.

HelloSign provides separate API keys for its production and sandbox environments. When developing, always use your sandbox API key to avoid accidental charges or impacting live documents. The sandbox environment allows for unlimited testing without consuming your document allowance.

Your first request

After obtaining your API key, the next step is to make your first API request. This section demonstrates sending a basic signature request using the HelloSign API. We will use a simplified example that sends a document for signing to a specified email address. HelloSign supports various methods for sending documents, including uploading a file, providing a URL to a file, or using a template.

For this example, we'll demonstrate a simple request using curl, which is useful for understanding the raw API interaction:

Example: Send a Signature Request via curl

curl -X POST \ 
  https://api.hellosign.com/v3/signature_request/send \ 
  -u "YOUR_API_KEY:" \ 
  -F "file_url=https://www.africau.edu/images/default/sample.pdf" \ 
  -F "title=My First Document" \ 
  -F "subject=Please sign this document" \ 
  -F "message=Hello, please sign the attached document." \ 
  -F "signers[0][name]=John Doe" \ 
  -F "signers[0][email_address][email protected]" \ 
  -F "test_mode=1"

Explanation of Parameters:

• -X POST: Specifies the HTTP POST method.
• https://api.hellosign.com/v3/signature_request/send: The API endpoint for sending a signature request.
• -u "YOUR_API_KEY:": Basic authentication. Replace YOUR_API_KEY with your actual API key. The colon after the key is important as it signifies an empty password.
• -F "file_url=...": Specifies the URL of the document to be signed. You can replace this with a publicly accessible PDF or use file[]=@/path/to/your/file.pdf to upload a local file.
• -F "title=...": The title of the signature request.
• -F "subject=...": The subject line of the email sent to the signers.
• -F "message=...": The custom message included in the email to signers.
• -F "signers[0][name]=..." and -F "signers[0][email_address]=...": Defines the first signer's name and email address. For multiple signers, increment the index (e.g., signers[1]).
• -F "test_mode=1": Crucially, this parameter ensures the request is processed in HelloSign's sandbox environment. Documents sent in test mode are not legally binding and do not count towards your document quota.

Upon successful execution, the API will return a JSON response containing details about the signature request, including its ID and status. The signer ([email protected] in this example) will receive an email prompting them to sign the document.

For language-specific examples and to leverage the benefits of type safety and object-oriented interaction, consult the HelloSign SDK documentation for Node.js, Python, Ruby, .NET, Java, or PHP. Using an SDK is generally recommended for production applications as it handles authentication, request formatting, and response parsing, reducing boilerplate code.

Common next steps

After successfully sending your first signature request, consider these common next steps to further integrate HelloSign:

1. Implement Webhooks: Webhooks are essential for receiving real-time notifications about the status of your signature requests (e.g., document viewed, signed, declined). This allows your application to react to events without constantly polling the API. Configure a webhook URL in your HelloSign API settings and implement a listener in your application to process these POST requests. HelloSign's webhook documentation provides detailed guidance.
2. Explore Embedded Signing: For a seamless user experience, integrate embedded signing. This allows signers to complete documents directly within your application's interface, rather than being redirected to HelloSign. The HelloSign API provides URLs that can be embedded in an iframe.
3. Use Templates: If you frequently send the same documents, create templates in HelloSign. Templates pre-define the document, signer roles, and signature fields, simplifying the API request by requiring only variable data (e.g., signer names, custom fields) to be passed. This reduces API payload complexity and ensures consistency.
4. Error Handling and Logging: Implement robust error handling to gracefully manage API failures or unexpected responses. Log API requests and responses to aid in debugging and monitoring your integration's health.
5. Go Live: Once development and testing in the sandbox are complete, switch to your production API key and endpoints. Ensure you have a paid plan that supports your expected volume of signature requests.
6. Secure API Keys: Review your API key management practices. Best practices include using environment variables, dedicated secrets management services, and rotating keys periodically. The HelloSign API settings also allow for key regeneration.

Troubleshooting the first call

Encountering issues during your initial API call is common. Here are some troubleshooting steps:

• Check API Key: Double-check that your API key is correct and includes the trailing colon when using basic authentication with curl (e.g., -u "YOUR_API_KEY:"). Ensure you are using the correct key for the environment (sandbox vs. production).
• Verify Endpoint: Confirm that you are sending requests to the correct API endpoint (e.g., https://api.hellosign.com/v3/signature_request/send).
• Review Request Parameters: Ensure all required parameters are present and correctly formatted. Common issues include missing signer email addresses, incorrect file URLs, or malformed JSON/form data. Refer to the HelloSign API reference for exact parameter requirements.
• Test Mode Flag: Always include test_mode=1 during development to ensure you are operating in the sandbox. If omitted, and you are using a production key, the request will be live and count against your quota.
• Publicly Accessible File URL: If using file_url, ensure the URL points to a publicly accessible document (e.g., PDF, DOCX). HelloSign's servers must be able to retrieve it.
• HTTP Status Codes: Pay attention to the HTTP status code returned by the API.
• 200 OK: Success.
• 400 Bad Request: Indicates an issue with your request parameters. The response body usually contains specific error messages.
• 401 Unauthorized: Typically means an incorrect or missing API key.
• 403 Forbidden: Your account may not have the necessary permissions for the requested action, or your API key might be restricted.
• 429 Too Many Requests: You have exceeded the API rate limits. Implement exponential backoff for retries.
• 5xx Server Error: An issue on HelloSign's side. Check the HelloSign status page for outages.
• Consult Documentation: The HelloSign API documentation is a comprehensive resource for error codes, examples, and best practices.
• SDK Debugging: If using an SDK, enable verbose logging to see the underlying HTTP requests and responses, which can help pinpoint issues.