HelloSign API Getting Started: Account, Keys, First Request (2026)

Getting started overview

Integrating with the HelloSign API involves a series of steps designed to get developers sending e-signature requests from their applications. The process begins with account creation, followed by obtaining API credentials, and subsequently making an initial API call. HelloSign provides a dedicated API documentation resource for detailed guidance.

The HelloSign API primarily facilitates the programmatic sending, tracking, and management of e-signature requests. Developers can use it to embed e-signature capabilities directly into custom applications, automate document workflows, and integrate with existing business systems. The API is suitable for a range of use cases, from simple document signing to complex enterprise-level solutions requiring compliance with standards like HIPAA and eIDAS.

To streamline development, HelloSign offers software development kits (SDKs) for several popular programming languages, including Python, Ruby, PHP, Node.js, Java, and .NET. These SDKs handle common API interactions, such as request formatting and response parsing, reducing the boilerplate code needed for integration. Alternatively, developers can interact directly with the RESTful API endpoints using standard HTTP clients.

The Developer Plan offers a free tier that includes 50 test signatures, allowing for full functionality testing in a sandbox environment before transitioning to a production setup. This enables developers to validate their integration logic and user experience without incurring costs for initial development and testing phases.

Here is a quick reference table outlining the initial steps for getting started with the HelloSign API:

Create an account and get keys

To begin using the HelloSign API, you must first create a HelloSign account. The HelloSign API pricing page provides details on available plans, including the free Developer Plan. This plan is designed for testing and development, offering 50 free test signatures, which are sufficient for initial integration and validation. Account creation typically involves providing an email address and setting a password.

Once your account is established, navigating to the HelloSign dashboard is the next step to obtain your API credentials. The API key serves as your primary means of authenticating requests to the HelloSign API. To generate an API key:

1. Log in to your HelloSign account.
2. Access the API settings or Integrations section within your dashboard.
3. Locate the option to generate a new API key.
4. Copy the generated API key. It is crucial to store this key securely, as it grants access to your HelloSign account's API functionalities.

HelloSign's API Key documentation provides specific instructions and best practices for managing API keys, including recommendations for rotating keys and restricting access. For production environments, consider using environment variables or a secrets management service to store API keys rather than embedding them directly in code. This practice is aligned with general security principles for API consumption, as outlined in guides such as Google Cloud's best practices for securing API keys.

HelloSign also supports OAuth 2.0 for applications that need to act on behalf of other HelloSign users. While API keys are suitable for direct server-to-server integrations, OAuth is preferred for user-facing applications requiring delegated access without sharing user credentials.

Your first request

After acquiring your API key, the next step is to make your first API request. This typically involves sending a simple signature request to test the authentication and basic functionality. HelloSign provides a selection of SDKs that simplify this process by abstracting HTTP requests and JSON parsing.

For example, using the Python SDK, a basic signature request might look like this:

from hellosign_sdk import HSClient

# Replace with your actual API key
api_key = "YOUR_API_KEY"
client = HSClient(api_key=api_key)

# Define the signature request parameters
signers = [
    {'email_address': '[email protected]', 'name': 'Signer One'}
]

# Example of a simple file-based signature request
try:
    signature_request = client.send_signature_request_with_template( 
        template_id='YOUR_TEMPLATE_ID', # Replace with a valid template ID
        subject='Test Document for Signature',
        message='Please sign this document.',
        signers=signers,
        test_mode=True
    )
    print(f"Signature request sent successfully. Request ID: {signature_request.signature_request_id}")
except Exception as e:
    print(f"Error sending signature request: {e}")

This example demonstrates sending a signature request using a pre-configured template. Before running this code, you would need to:

1. Install the HelloSign Python SDK: pip install hellosign-sdk.
2. Replace "YOUR_API_KEY" with your actual API key.
3. Replace "YOUR_TEMPLATE_ID" with an ID of a template configured in your HelloSign account. Templates are reusable documents with predefined fields and signer roles, simplifying recurring signature requests.
4. Ensure the email address for [email protected] is valid for testing.

If you prefer to make requests without an SDK, you can use a tool like curl or any HTTP client. The general structure for sending a signature request via the API directly involves a POST request to the /signature_request/send endpoint, including your API key for authentication and the request parameters in the body. The HelloSign API reference for signature request send provides detailed examples for various programming languages and direct HTTP calls.

Always perform initial testing in the sandbox environment by setting test_mode=True in your requests. This ensures that documents sent are not legally binding and do not count towards your plan's signature limits. A successful response will typically include a unique signature_request_id, which can be used to track the status of the document.

Common next steps

After successfully sending your first signature request, several common next steps can further enhance your integration:

• Implement Webhooks: HelloSign supports webhooks for real-time notifications about the status of signature requests (e.g., signed, declined, voided). Configuring webhooks allows your application to react to events without constantly polling the API, which is more efficient and scalable. The HelloSign Webhooks documentation provides setup instructions.
• Handle Callbacks and Events: When a signature request is completed or its status changes, HelloSign can send data back to your application via a callback URL. Properly handling these callbacks is essential for updating your application's internal records and triggering subsequent workflows.
• Embed Signing Experiences: For a more integrated user experience, HelloSign offers an embedded signing feature. This allows signers to complete documents directly within your application's UI, rather than being redirected to the HelloSign website. Refer to the HelloSign embedded signing client app basics for implementation details.
• Explore Advanced Features: Investigate other API capabilities such as creating templates, managing signers, adding custom fields, or integrating with cloud storage providers. The full API reference details all available endpoints and their functionalities.
• Monitor API Usage: Keep an eye on your API usage through your HelloSign dashboard to ensure you stay within your plan's limits.
• Review Security Best Practices: Regularly review HelloSign's security guidelines and general OAuth 2.0 security principles if you're using OAuth. Ensure your application securely handles API keys, tokens, and sensitive document data.

Troubleshooting the first call

Encountering issues during the first API call is common. Here are some troubleshooting tips:

• Invalid API Key: Double-check that your API key is correct and has not expired. Ensure there are no leading or trailing spaces if copied manually. The API key should be included correctly in the request header or as specified by the SDK.
• Incorrect Endpoint or HTTP Method: Verify that you are sending the request to the correct HelloSign API endpoint and using the appropriate HTTP method (e.g., POST for creating resources, GET for retrieving). The HelloSign API reference specifies these for each operation.
• Missing Required Parameters: All API requests have required parameters. If any are missing, the API will return a 400 Bad Request error. Consult the documentation for the specific endpoint you are calling to ensure all mandatory fields are present in your request body or parameters.
• Rate Limiting: While less common for initial calls, persistent errors might indicate you've hit a rate limit. HelloSign's API has rate limits to prevent abuse. Check the API response headers for X-RateLimit-Limit and X-RateLimit-Remaining.
• Network Issues: Ensure your development environment has stable network connectivity and is not blocked by firewalls from reaching HelloSign's servers.
• SDK Configuration: If using an SDK, ensure it's correctly installed and initialized. SDKs may have specific configuration requirements for API keys or environments.
• Error Messages: Pay close attention to the error messages returned by the API. They often provide specific details about what went wrong. Common HTTP status codes to look for include:
  • 400 Bad Request: Malformed request, missing parameters.
  • 401 Unauthorized: Invalid or missing API key.
  • 403 Forbidden: API key lacks necessary permissions or access.
  • 404 Not Found: Incorrect endpoint URL.
  • 429 Too Many Requests: Rate limit exceeded.
  • 500 Internal Server Error: Server-side issue (less common to be user-caused).
• Test Mode Verification: For initial testing, ensure test_mode is set to True in your requests. If you attempt to send a live request without proper configuration for a paid plan, you might encounter errors related to plan limits or billing.
• HelloSign Support: If you've exhausted troubleshooting steps, HelloSign's developer support resources are available to assist with specific integration challenges.