Skip to main content

Create Your First Signature Request

This guide will get you up and running with Covosign by sending your first signature request.

We designed our platform with a Sandbox-first approach. You will build and test your integration using a Sandbox API Key in our isolated environment before switching to Production.

Prerequisites​

Before you begin, ensure you have a Sandbox API Key.

  • Format: csk_sandbox_...
  • Environment: Sandbox data is isolated and purged every 30 days.
  • Cost: Sandbox usage is free and unlimited for development.
tip

If you don't have a key yet, please create one in your dashboard or generate one via the API.

Step 1: Configure Environment​

Set your base URL to the Sandbox environment to test safely without affecting live data or incurring costs.

# Covosign Sandbox Configuration
API_KEY=csk_sandbox_your_key_here
BASE_URL=https://api-sandbox.covosign.com/api/v1/enterprise

Step 2: Create Draft Request​

The signature workflow starts by creating a request in DRAFT status and uploading the document you want signed.

POST /signature-requests

Headers

X-API-Key: csk_sandbox_...
Content-Type: multipart/form-data

Body (Multipart)

  • file: [your_document.pdf]
  • title: "NDA Agreement"
  • delivery_mode: "email"

Response

{ 
  "code": 201,
  "message": "Signature request created successfully",
  "data": { 
    "id": "550e8400-e29b-41d4-a716-446655440000", 
    "status": "DRAFT", 
    "title": "NDA Agreement" 
  } 
}

Step 3: Add a Signer​

Register the recipient who needs to sign the document.

POST /signature-requests/{id}/recipients

Request Body

{ 
  "email": "alice@example.com", 
  "name": "Alice Tests", 
  "role": "SIGNER", 
  "order": 1 
}

Step 4: Add Fields​

Define where the signer should place their signature on the document.

POST /signature-requests/{id}/fields

Request Body

{
  "recipientId": "650e8400-e29b-41d4-a716-446655440001",
  "type": "SIGNATURE",
  "page": 1,
  "x": 100,
  "y": 200,
  "width": 200,
  "height": 50
}

Step 5: Send Request​

Once the document, recipients, and fields are configured, send the request to trigger email delivery.

POST /signature-requests/{id}/send

Response

{ 
  "code": 200,
  "message": "Signature request sent successfully",
  "data": { 
    "id": "550e8400-e29b-41d4-a716-446655440000", 
    "status": "IN_PROGRESS" 
  } 
}

In the Sandbox environment, this will send a real email to the defined recipient, but the signature will clearly be marked as "Not a valid legal signature".

Going Live: Moving to Production​

Once you have verified your integration in the Sandbox, moving to Production is seamless.

  1. Get a Production Key: Contact support or use the request production key endpoint. Production keys require an active Enterprise Plan.
  2. Update Configuration:
    • Change your API Key to your Live key (csk_live_...).
    • Update your Base URL to the production endpoint: https://api.covosign.com/api/v1/enterprise

Your code logic and endpoints remain exactly the same.