🚀 Complete API Guide (Beginner Friendly)

Welcome! This guide is written so that anyone can understand it, even if you are new to programming. We will show you exactly how to connect your app (Website, Telegram Bot, Make/Zapier) to our Document Generator using simple steps and clear examples.

🐣 Beginner’s Note: What is an API?

Think of an API like a waiter in a restaurant. You (the developer) tell the waiter what you want: “I want a document image with the name John Doe.” The waiter takes your order to the kitchen (our AI Server), waits for the food to be cooked, and brings the final image back to you! You don’t need to know how to cook; you just need to know how to place the order.

🔑 1. Your API Key (Your Secret Password)

To use the API, you need a key to prove your identity. Go to your Dashboard on our website. You will see a code starting with live_sk_....

⚠️ Security Warning: Treat this key like your bank password! Never expose it in client-side HTML or frontend JavaScript. Always make API calls securely from your backend server.

⚖️ 2. How Billing Works (Preview vs. Final)

We use a safe 2-step system so you don’t waste money by mistake:

Preview Mode (Free): You ask for a document, and we give you a draft with a watermark. It costs $0.
Final Mode (Paid): When you are happy with the preview, you ask for the final version. Only then is money deducted from your wallet (and you get an automatic 50% API Reseller Discount!).

🕵️‍♂️ Step 0: Find Out What Fields You Need

Every document is different. A Passport needs a “Date of Birth”, but a Utility Bill needs an “Address”. First, you must ask our server what fields it expects for a specific template.

GET https://veriftools.is/wp-json/engine/v1/template/{template_id}

If you visit this link in your browser (replace {template_id} with a real ID like 1420), the server will output a JSON list telling you the exact names of the variables (like first_name or main_photo). You will use these exact names in Step 1.

🛠️ Step 1: Ask the AI to Generate the Document

Now, you will send the user’s data to our server to start the creation process.

POST https://veriftools.is/wp-json/engine/v1/generate Headers: Content-Type: application/json

Here is the JSON you need to send us:

{
   "api_key": "live_sk_YOUR_SECRET_KEY_HERE",
   "template_id": 1420,
   "request_mode": "preview", // Use "final" to purchase
   "output_style": "photo", // Or "scanned"
   "scene_bg_url": "https://example.com/wooden-desk.jpg",
   "data": {
      "first_name": "John",
      "last_name": "Doe",
      "date_of_birth": "1990/05/24",
      
      // --- Images ---
      "main_photo": "iVBORw0KGgoAAAANSUhEUgAA...",
      "rmbg_main_photo": true,
      
      // --- Signatures ---
      "sig_source_type_customer_sign": "upload",
      "sig_data_customer_sign": "iVBORw0KGgoAAAAN..."
   }
}

📸 Important Note About Photos: Images must be converted to Base64 text. Important: Remove the text data:image/jpeg;base64, from the beginning! Send only the raw code. ✨ AI Background Removal: Want us to automatically remove the background from a portrait? Just add rmbg_ before the photo variable name and set it to true (Example: "rmbg_main_photo": true).

✍️ How to Send Signatures (Demystified)

Why do signatures look different in the JSON above? Because our system gives you two options for signatures: A user can draw/upload their own, OR they can pick a ready-made signature from a gallery. Because the system needs to know which option you chose, you cannot just send one line of data. If Step 0 tells you the signature variable name is customer_sign, you must send TWO fields to the server:

1. The Type (Source): You must add sig_source_type_ before your variable name.

Set it to "upload" if you are sending a Base64 image (custom signature).
Set it to "sample" if you want to send a URL to an existing signature image.

2. The Data: You must add sig_data_ before your variable name.

If the type is “upload”, put your raw Base64 image string here.
If the type is “sample”, put the image URL here.

Example A: Uploading a custom signature

"sig_source_type_customer_sign": "upload",
"sig_data_customer_sign": "iVBORw0KGgoAAAAN..." // Base64 string

Example B: Using a ready-made signature URL

"sig_source_type_customer_sign": "sample",
"sig_data_customer_sign": "https://veriftools.is/sample-sig.png"

What the server replies (Step 1 Response):

{
   "task_id": "job_987654321",
   "status": "processing"
}

Great! You got a task_id (like a receipt for your order). The AI is now drawing your image. Let’s move to Step 2.

⏳ Step 2: Ask “Is it ready yet?” (Polling)

The AI takes about 10 to 40 seconds to draw the document. Your code needs to ask the server “Is my document ready yet?” every 3 seconds. This loop is called “Polling”.

🐣 Beginner’s Note: What is Polling?

Imagine waiting for a pizza to bake. You don’t just stare unblinkingly at the oven; you sit down, and every few minutes, you ask the chef, “Is it ready?”. Polling is exactly that. Your code asks the server every 3 seconds, “Is my task done?” until the server says, “Yes, here is your image!”

POST https://veriftools.is/wp-json/engine/v1/task-status

Send this simple request every 3 seconds:

{
   "api_key": "live_sk_YOUR_SECRET_KEY_HERE",
   "task_id": "job_987654321",
   "template_id": 1420
}

If the server replies "status": "processing": Wait 3 seconds and ask again.

If the server replies "status": "failed": STOP asking. Something went wrong (you won’t be charged).

If the server replies "status": "success": Congratulations! Your image is ready. The server will give you the Base64 image code in the image_base64 field.

{
   "status": "success",
   "data": {
       "is_preview": true,
       "mime_type": "image/png",
       "file_ext": "png",
       "image_base64": "iVBORw0KGgoAAAANSUhEUgAA..."
   }
}

💻 Bonus: Complete JavaScript Example for Beginners

If you are new to coding and don’t know how to write the “Polling” loop, don’t worry! Here is a complete, copy-paste ready JavaScript code that does everything from start to finish. (You can test it directly in NodeJS or your browser’s console).

async function generateMyDocument() {
    const API_KEY = "live_sk_YOUR_SECRET_KEY_HERE";
    const TEMPLATE_ID = 1420;

    console.log("1. Sending data to AI Engine...");
    
    // Step 1: Request Generation
    let generateResponse = await fetch("https://veriftools.is/wp-json/engine/v1/generate", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
            api_key: API_KEY,
            template_id: TEMPLATE_ID,
            request_mode: "preview",
            output_style: "scanned",
            data: {
                "first_name": "John",
                "last_name": "Doe"
            }
        })
    });

    let generateResult = await generateResponse.json();
    
    if (generateResult.error) {
        console.error("Error generating:", generateResult.error);
        return;
    }

    let taskId = generateResult.task_id;
    console.log("Task created! ID: " + taskId);
    console.log("2. Waiting for AI to finish (Polling)...");

    // Step 2: Polling Loop (Check every 3 seconds)
    let isDone = false;

    while (!isDone) {
        // Wait for 3 seconds before asking again
        await new Promise(resolve => setTimeout(resolve, 3000));

        let statusResponse = await fetch("https://veriftools.is/wp-json/engine/v1/task-status", {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({
                api_key: API_KEY,
                task_id: taskId,
                template_id: TEMPLATE_ID
            })
        });

        let statusResult = await statusResponse.json();

        if (statusResult.status === "success") {
            console.log("🎉 Document is READY!");
            // Here is your final image in Base64
            console.log(statusResult.data.image_base64); 
            isDone = true; // Stop the loop
        } 
        else if (statusResult.status === "failed") {
            console.error("❌ AI Processing failed:", statusResult.error);
            isDone = true; // Stop the loop
        } 
        else {
            console.log("Still cooking... checking again in 3 seconds.");
        }
    }
}

// Run the function
generateMyDocument();

If you encounter any issues or get a “402 Insufficient wallet balance”, make sure your wallet is topped up. Happy coding! 💻✨