Skip to main content
POST
/
v1
/
excel
/
jobs
Populate Template
curl --request POST \
  --url https://api.stru.ai/v1/excel/jobs \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '{
  "operation": "<string>",
  "template_file": "<string>",
  "data_mappings": {}
}'
{
  "422": {}
}

​
Overview

Populate existing company Excel templates with data using named ranges or table references. Perfect for maintaining standard formatting while dynamically filling in project-specific values.
Asynchronous Operation: Returns immediately with a job ID. Poll for the populated file download URL.

​
Authentication

​
Authorization
string
required
Bearer token (API key from app.stru.ai)

​
Request Body

​
operation
string
required
Must be "populate_template"
"operation": "populate_template"
​
template_file
string
required
Base64-encoded .xlsx template file
"template_file": "UEsDBBQAAAAIAOiG..."
​
data_mappings
object
required
Key-value pairs mapping named ranges to data values
"data_mappings": {
  "ProjectName": "Building A Foundation",
  "EngineerName": "John Doe, PE",
  "DesignDate": "2025-10-17",
  "BeamSpan": 20,
  "LoadValue": 2.5
}

​
Named Ranges

Excel templates must use named ranges for the cells you want to populate:
  1. In Excel, select a cell or range
  2. Go to Formulas → Define Name
  3. Give it a descriptive name (e.g., ProjectName, BeamSpan)
  4. Reference that name in data_mappings

​
Example Request

# Encode template
TEMPLATE_B64=$(base64 -i template.xlsx)

curl -X POST https://api.stru.ai/v1/excel/jobs \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d "{
    \"operation\": \"populate_template\",
    \"template_file\": \"$TEMPLATE_B64\",
    \"data_mappings\": {
      \"ProjectName\": \"Building A - Level 3 Framing\",
      \"Engineer\": \"John Doe, PE\",
      \"Date\": \"2025-10-17\",
      \"BeamSpan_ft\": 20,
      \"UniformLoad_klf\": 2.5,
      \"Deflection_in\": 0.45
    }
  }"

​
Example Response

{
  "job_id": "job_xls_pop_abc123",
  "status": "completed",
  "created_at": "2025-10-17T10:30:00Z",
  "completed_at": "2025-10-17T10:30:05.789Z",
  "results": {
    "file_url": "https://storage.stru.ai/temp/populated-calc.xlsx?signature=...",
    "file_type": "xlsx",
    "expires_at": "2025-10-18T10:30:05.789Z"
  }
}

​
Template Setup Guide

1

Design Your Template

Create your Excel template with standard formatting, headers, and placeholders.
2

Define Named Ranges

For each cell you want to populate:
  1. Select the cell
  2. Go to Formulas → Define Name
  3. Enter a descriptive name (e.g., ProjectName)
  4. Click OK
3

Test Locally

Verify named ranges are correct:
  1. Press Ctrl+F3 (Windows) or Cmd+F3 (Mac)
  2. Review the Name Manager
  3. Ensure all names are correct
4

Use with API

Reference named ranges in data_mappings using exact names (case-sensitive).

​
Use Cases

Maintain company-standard calculation templates and populate with project-specific data.
data = {
    "ProjectNumber": "2025-042",
    "ClientName": "ABC Developers",
    "BeamSpan": 20,
    "LoadFactor": 1.2
}

populate_template('std-beam-calc-template.xlsx', data)
Generate monthly reports with consistent formatting but dynamic data.
monthly_data = {
    "ReportMonth": "October 2025",
    "TotalProjects": 15,
    "RevenueAmount": 450000,
    "ActiveEngineers": 8
}

populate_template('monthly-report-template.xlsx', monthly_data)
Use different templates for different clients while populating with the same data structure.
# Same data, different templates
for client in clients:
    template = f"templates/{client}_template.xlsx"
    populate_template(template, project_data)
Generate reports for multiple projects using the same template.
for project in projects:
    data = extract_project_data(project)
    file_url = populate_template('template.xlsx', data)
    save_to_project_folder(project, file_url)

​
Best Practices

Use descriptive names - Name ranges clearly: BeamSpan_ft, not B5
Test template locally - Verify all named ranges exist and are correct before using with API
Maintain template library - Version control your templates for consistency
Handle missing data - Provide default values for optional fields
data_mappings = {
    "Required Field": value,
    "OptionalField": data.get("optional", "N/A")
}
Formulas in templates: Your template can contain formulas that reference populated cells. The formulas will recalculate when the file is opened in Excel.
Named range names are case-sensitive: Ensure your data_mappings keys exactly match the named range names in your template.

​
Error Responses

​
422
Validation Error
Named range not found in template
{
  "error": {
    "code": "NAMED_RANGE_NOT_FOUND",
    "message": "Named range 'ProjectName' not found in template",
    "details": {
      "missing_ranges": ["ProjectName", "EngineerName"]
    }
  }
}

​
Next Steps

After population:
  1. Download the populated file
  2. Open in Excel to verify
  3. Distribute to client or archive in project folder