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.

.env

# 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.

HTTP

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.

HTTP

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.

You can place fields in two ways:

• Use coordinates when your PDF layout is fixed and you already know the page, x, and y position.
• Use PDF anchors when each PDF is generated dynamically and the final position may change per customer.

Coordinates

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
}

PDF Anchors

POST /signature-requests/{id}/fields/anchored

Use this option when the uploaded PDF contains text anchor tokens such as {{covosign:customer-signature}}. Covosign resolves the anchor location from the PDF text layer and then creates a normal field at that position.

Request Body

{
  "fields": [
    {
      "anchorKey": "{{covosign:customer-signature}}",
      "type": "SIGNATURE",
      "recipientId": "650e8400-e29b-41d4-a716-446655440001",
      "xOffset": 0,
      "yOffset": 12,
      "width": 200,
      "height": 50,
      "name": "Customer Signature"
    }
  ]
}

Use xOffset and yOffset to move the field relative to the anchor text. For example, if the anchor label appears just above a signature line, use a positive yOffset to place the field on the line.

Step 5: Send Request

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

HTTP

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".

Template Flow With Copytrack-Style Anchors

For Copytrack's internal integration, Copytrack already fills customer-specific names, addresses, claim IDs, and declarations before the document reaches Covosign. In that case, use the PDF flow and let Covosign handle only signing fields and optional evidence-image stamping.

Recommended PDF order:

1. Create or upload a customer-specific PDF from Copytrack. The visible customer content should already be final.
2. Add placeholder recipients to the template.
3. Add signer fields with POST /signature-requests/{templateId}/fields/anchored if using a PDF template, or POST /signature-requests/{requestId}/fields/anchored if using a one-off customer PDF.
4. Create a draft from the template with POST /signature-requests/templates/{templateId}/use when you are using a reusable PDF template.
5. Stamp customer-specific evidence images on the draft with POST /signature-requests/{draftId}/fields/anchored/image.
6. Send the draft with POST /signature-requests/{draftId}/send.

Example PDF template-use request:

{
  "title": "Copytrack Claim 247CCA",
  "recipients": [
    {
      "email": "alex@example.com",
      "name": "Alex Golke"
    }
  ]
}

Do not send templateData for PDF templates. PDF is the correct path when the document content is already final before it reaches Covosign.

DOCX remains available for other enterprise clients that need Covosign to fill dynamic text before signing. In that flow, call POST /signature-requests/templates/{templateId}/use with templateData, then add anchored fields on the generated draft PDF. The signer still receives a PDF, not a DOCX.

---

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.