How to Migrate from API v1 to v2 - Beginner Guide

This guide helps developers move from Evia Sign's API v1 to API v2 with minimal changes, specifically for request type 3 (Auto Stamping).

⚠️ Note: This guide only covers the minimal migration path. A full guide for all API v2 features and request types will be released soon.

---

✅ What You Can Keep As-Is

• Document Upload: Your current implementation using API v1 can remain unchanged.

---

🔁 What’s Different in API v2

In v1, you sent everything (document, signers, stamps, OTP, etc.) in one big API call.

In v2, you break it down into 5 smaller, easier-to-manage steps:

1. Upload the document (same as v1)

2. Create the request (with ?type=0)

3. Add signatories

4. Add stamp positions

5. Send the request

---

⚙️ Migration Steps in API v2

1. Upload the Document (No Change)

✅ Returns: documentId

---

2. Create the Request (type=0)

POST /api/v2/requests?type=0
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Auto Stamping - Test",
  "message": "This is your document",
  "completedDocumentsAttached": true,
  "callbackTypes": [1],
  "documents": ["<documentId>"]
}

🔁 Returns: requestId

---

3. Add Each Signatory

POST /api/v2/requests/{requestId}/signatories

{
  "name": "Signer Name",
  "email": "[e-mail]",
  "order": 1,
  "signatoryType": 1,
  "otp": {
    "isRequired": true,
    "accessCode": "12345",
    "type": 3
  }
}

✔️ Returns: signatoryId

---

4. Add AutoStamp for the Signatory

POST /api/v2/requests/{requestId}/signatories/{signatoryId}/stamps

{
  "identifier": "<<vp_1_s>>",
  "color": "#7c95f4",
  "order": 1,
  "offset": {
    "xOffset": 0,
    "yOffset": 0,
    "offsetType": 2
  },
  "stampSize": {
    "height": 50,
    "width": 100
  },
  "type": "signature"
}

---

5. Send the Request

POST /api/v2/requests/{requestId}/send

✅ This triggers the document and sends it to signers.

---

📊 Summary Table

Step	v1	v2
Document Upload	Same	Same
Create Request	One big payload	/requests?type=0
Add Signers	Inline in request	Separate API call
Add Stamps	Inline in request	Separate API call
Send Request	Happens automatically	Explicit /send call

---

📌 Additional Notes

• type=0 must be passed as a query parameter in v2 request creation

• Webhooks are now handled via a separate API.

• API v2 provides more descriptive error responses and improves control.

This migration keeps your system stable while making use of v2’s improved modular design.