Example: Fill Form via API

In this example, we will fill out a form using an API key, then loop and sleep until the job is done. Full example here (NodeJS/Typescript): https://github.com/cptrodgers/takeform-examples/tree/master/nodejs

Step 1: Prepare API Key

To integrate TakeForm into your application, you need to generate a new API key. Follow section API Key.

You also need the form ID of the form you want to fill. You can find it in the list of forms in your web app, or retrieve it using cURL with your API key.

curl -L \
  --url 'https://api.takeform.app/developer/v1/forms' \
  --header 'X-API-Key: YOUR_API_KEY'
  

### Example return
[
  {
    "id": "5c79b048-587b-4974-8f0d-afef0aa829e4", # We need this id
    "name": "Japan Visa Visitor",
    "description": "Japan Visa Visitor",
    "file_id": "123e4567-e89b-12d3-a456-426614174000",
    "index": 1,
    "updated_at": 1,
    "created_at": 1,
    "status": "Done",
    "is_draft": false,
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "cost": 1
  }
]

Step 2: Call the Fill Form API

Now that we have the TAKEFORM_API_KEY and FORM_ID, we can start calling the Fill Form API. This will create a job in the background and begin filling the form using your data source.

// API server URL and form ID to fill
const apiServer = "https://api.takeform.app";
const formId = "5c79b048-587b-4974-8f0d-afef0aa829e4";
let filledFormId = ""; // Variable to store the ID of the filled form

const filePath = resolve(__dirname, "../japan_visa_intake.txt");
const buffer = await readFile(filePath); // Reading the file as a buffer
const uint8Array = new Uint8Array(buffer); // Converting buffer to Uint8Array for transmission

// Making a POST request to the API to fill the form
const response = await fetch(
  `${apiServer}/developer/v1/forms/${formId}/fill`,
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.TAKEFORM_API_KEY || "", // API key for authentication
      "Content-Type": "application/json; charset=utf-8", // Content type of the request
    },
    body: JSON.stringify({
      sources: [
        {
          type: "Text", // First source: plain text
          text: JAPAN_VISITOR_VISA_INTAKE_TEXT, // The text used to fill the form
        },
        {
          type: "SourceFile", // Second source: file content
          content_type: "plain/text", // Content type of the file
          data: Array.from(uint8Array), // Converting Uint8Array to an array for transmission
        },
      ],
    }),
  },
);

And get the result

// Filled Form Object
{
  created_at: 1744022701,
  file_id: '80bd63cb-1efb-46bc-9843-2d8a4568978e',
  filled_via: 'Api',
  form_id: '5c79b048-587b-4974-8f0d-afef0aa829e4',
  id: 'a73063c3-b26e-4b9d-9507-dce732ec17bf',
  name: 'Japan Visitor - Letter of Guarantee',
  status: 'Filling',
  updated_at: 1744022701,
  user_id: 'df0bebb1-c460-4263-a654-6d9f5dda7428'
}

Step 3: Get the download URL when the filled form is completed

Based on the ID from the Filled Object in step 2, you can check its status and wait to download the latest Filled Form Object. If the object's status is Done , you can download it using the Download URL API.

// Helper function to pause execution for a set amount of time
const timer = (ms: number) => new Promise((res) => setTimeout(res, ms));

// Function to check the status of the filled form and download it once completed
async function getFilledFormDownloadUrl() {
  console.log("Checking filled form job", filledFormId);

  while (true) {
    await timer(10000); // Wait for 10 seconds before checking again
    try {
      // Making a GET request to check the status of the filled form
      const response = await fetch(
        `${apiServer}/developer/v1/filled-forms/${filledFormId}`,
        {
          method: "GET",
          headers: {
            "X-API-Key": process.env.TAKEFORM_API_KEY || "", // API key for authentication
          },
        },
      );

      const data = await response.json();

      // If the form is done, proceed to download it
      if (data["status"] === "Done") {
        // Making another GET request to retrieve the download URL for the filled form
        const downloadResponse = await fetch(
          `${apiServer}/developer/v1/filled-forms/${filledFormId}/download-url`,
          {
            method: "GET",
            headers: {
              "X-API-Key": process.env.TAKEFORM_API_KEY || "", // API key for authentication
            },
          },
        );

        const downloadData = await downloadResponse.json();
        console.log("DOWNLOAD FILLED FORM AT", downloadData); // Logging the download URL
        break; // Exit the loop once the form is downloaded
      }
    } catch (err) {
      console.error("❌ Error while checking the form status:", err);
    }
  }
}

Step 4 (Recommendation): Instead of using wait and sleep in Step 3, you can use a Webhook to receive the latest status of the filled form.

Checkout API Webhook to add a webhook url and received latest Filled Form object data.