Teleza Quickstart

What you need

Teleza API base URL.
Customer-scoped X-API-Key.
A saved report definition or a starter blueprint selected from the gallery.
Rows from your own app, or an optional customer-scoped data source key for SQL Server, PostgreSQL, REST, CSV, or Excel data.
Optional admin JWT only when creating customers or API keys yourself.

After you receive your key

Your onboarding email includes a one-time API key. Use it from your own code or terminal; do not send database passwords or API tokens through the beta request form or by email.

Run API examples in a terminal, not in a browser. On Windows PowerShell, use the PowerShell examples. On macOS, Linux, Git Bash, or a terminal with real curl, use the curl examples.

Call the templates endpoint to confirm the key works.
For the safest hosted path, query your own database locally and send rows to /render.
For direct Teleza connectivity, create and test a customer-scoped data source first.
Select a polished starter document with templateKey or branding.templateKey.

Golden workflow

Create or receive a customer-scoped API key.
Render directly from caller-supplied rows, or create and test a customer-scoped data source when Teleza should connect to customer-owned SQL Server, PostgreSQL, REST, CSV, or Excel data.
Create a report definition with dataSourceId, sql, format, and optional parameters when using the saved-report path.
Preview the report.
Execute JSON.
Export PDF, Excel/XLSX, CSV, JSONL, or NDJSON.
Optionally schedule delivery.
Read usage.

API contract

X-API-Key: <customer-scoped-api-key>
GET  /api/whiteLabelEngine/v1/templates
GET  /api/whiteLabelEngine/v1/templates?documentType=quotation
GET  /api/whiteLabelEngine/v1/templates/{key}/schema
GET  /api/whiteLabelEngine/v1/templates/{key}/sample
GET  /api/whiteLabelEngine/v1/templates/design-themes
POST /api/whiteLabelEngine/v1/render/preview
POST /api/whiteLabelEngine/v1/render
POST /api/whiteLabelEngine/v1/template-mappings/validate
GET  /api/whiteLabelEngine/v1/template-mappings
POST /api/whiteLabelEngine/v1/template-mappings
PUT  /api/whiteLabelEngine/v1/template-mappings/{key}
GET  /api/whiteLabelEngine/v1/data-sources
POST /api/whiteLabelEngine/v1/data-sources
PUT  /api/whiteLabelEngine/v1/data-sources/{key}
POST /api/whiteLabelEngine/v1/data-sources/{key}/test
POST /api/whiteLabelEngine/v1/reports
POST /api/whiteLabelEngine/v1/reports/{reportId}/preview
POST /api/whiteLabelEngine/v1/reports/{reportId}/execute?format=json
POST /api/whiteLabelEngine/v1/reports/{reportId}/execute?format=pdf|excel|xlsx|csv|jsonl|ndjson
POST /api/whiteLabelEngine/v1/reports/{reportId}/schedule
GET  /api/whiteLabelEngine/v1/reports/{reportId}/usage
              

Discover template fields

Every hosted starter template exposes a schema endpoint. Use it before wiring a database view to a template. The response shows required canonical names, accepted aliases, formatting hints, the hosted row limit, and an example fieldMap.

Invoke-RestMethod `
  -Method GET `
  -Uri "$ApiBaseUrl/api/whiteLabelEngine/v1/templates/sales-quotation-v1/schema" `
  -Headers $Headers
              

A field map is written as canonicalField = sourceField. For AccPro-style quotation rows, that can mean quoteNumber = quoteno, description = itmdescr, and lineTotal = amountincl.

Do not pre-calculate ordinary display totals in your integration script. Send detail rows and formatting preferences; Teleza computes subtotal, tax, debit/credit, quantity, and bottom-of-page totals during render. If your ERP supplies an authoritative total, Teleza preserves it for reconciliation.

If rows should be grouped, send grouping.field. Teleza sorts by that field and adds groupLabel, groupIndex, groupRowCount, groupSubtotal, groupTaxTotal, and groupQuantityTotal metadata for PDF, Excel, and JSON output.

If payload rows contain sensitive fields, send masking.rules. Teleza masks those fields before preview and export. Supported modes are full, last4, email, custom, and regex, with bounded field names, replacements, and regex patterns.

Preview responses include lineage.contractHash plus template key, schema version, design theme, mapping key, hashed field-map/options, normalized columns, row count, and generated-at time. Use that compact fingerprint in support notes or demo evidence without storing raw customer rows in the lineage manifest.

Compliance and field-service payloads can include photo evidence. Send photoDataUri, beforePhotoDataUri, or afterPhotoDataUri as PNG/JPEG data URIs, plus photoCaption. If you send photoReference or photoUrl, Teleza displays the reference and validates URL shape, but does not fetch remote caller-supplied images.

Terminal examples

Replace sk_live_... with the API key from your onboarding email.

Windows PowerShell

$ApiBaseUrl = "https://api.teleza.tech"
$ApiKey = "sk_live_..."
$Headers = @{ "X-API-Key" = $ApiKey }

Invoke-RestMethod `
  -Method GET `
  -Uri "$ApiBaseUrl/api/whiteLabelEngine/v1/templates" `
  -Headers $Headers

$DataSource = Invoke-RestMethod `
  -Method POST `
  -Uri "$ApiBaseUrl/api/whiteLabelEngine/v1/data-sources" `
  -Headers $Headers `
  -ContentType "application/json" `
  -Body (@{
    name = "Production SQL Server"
    key = "production-sqlserver"
    providerType = "sqlserver"
    connectionString = "Server=...;Database=...;User Id=...;Password=...;TrustServerCertificate=True"
  } | ConvertTo-Json -Depth 10)

Invoke-RestMethod `
  -Method POST `
  -Uri "$ApiBaseUrl/api/whiteLabelEngine/v1/data-sources/$($DataSource.key)/test" `
  -Headers $Headers
              

macOS, Linux, or Git Bash

API_BASE_URL="https://api.teleza.tech"
API_KEY="sk_live_..."

curl -H "X-API-Key: $API_KEY" "$API_BASE_URL/api/whiteLabelEngine/v1/templates"

curl -X POST "$API_BASE_URL/api/whiteLabelEngine/v1/data-sources" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"Production SQL Server",
    "key":"production-sqlserver",
    "providerType":"sqlserver",
    "connectionString":"Server=...;Database=...;User Id=...;Password=...;TrustServerCertificate=True"
  }'

curl -X POST "$API_BASE_URL/api/whiteLabelEngine/v1/data-sources/production-sqlserver/test" \
  -H "X-API-Key: $API_KEY"
              

Render from your own rows

This is the recommended hosted-beta path. Your application queries its own database, then sends the rows needed for one document to Teleza. No public SQL port or database password is required by Teleza.

The row safety limit still applies. On the standard hosted beta, keep data.rows at or below 1,000 rows per document. Over-limit render requests are rejected instead of silently truncated.

Windows PowerShell

$ApiBaseUrl = "https://api.teleza.tech"
$ApiKey = "sk_live_..."
$Headers = @{ "X-API-Key" = $ApiKey }
$QuoteNo = "QU072810"

# Replace this with your application query result.
$Rows = @(
  @{
    quoteno = $QuoteNo
    customerEmail = "finance@example.com"
    cardNumber = "4111111111111234"
    orderdate = "2026-06-04"
    itmdescr = "Teleza reporting API pilot"
    Qty = 1
    AmtExclNet = 490.00
    vatamt = 73.50
    amountincl = 563.50
  }
)

if ($Rows.Count -gt 1000) {
  throw "Teleza hosted beta render limit is 1000 rows per document."
}

$RenderRequest = @{
  templateKey = "sales-quotation-v1"
  format = "pdf"
  reportName = "Quotation $QuoteNo"
  data = @{ rows = $Rows }
  fieldMap = @{
    quoteNumber = "quoteno"
    quoteDate = "orderdate"
    description = "itmdescr"
    quantity = "Qty"
    unitPrice = "AmtExclNet"
    tax = "vatamt"
    lineTotal = "amountincl"
  }
  formatting = @{
    currency = "USD"
    locale = "en-US"
    decimalPlaces = 2
    totalsPlacement = "bottom"
  }
  grouping = @{
    field = "category"
    sortDirection = "asc"
    includeGroupTotals = $true
  }
  masking = @{
    rules = @(
      @{ field = "customerEmail"; mode = "email" },
      @{ field = "cardNumber"; mode = "last4" }
    )
  }
  branding = @{
    designTheme = "corporate-high-contrast"
    companyName = "AccPro Technologies"
    logoText = "AP"
    primaryColor = "#123E6B"
    backgroundColor = "#F8FAFC"
    footerNote = "Generated from customer application data"
  }
}

$Preview = Invoke-RestMethod `
  -Method POST `
  -Uri "$ApiBaseUrl/api/whiteLabelEngine/v1/render/preview" `
  -Headers $Headers `
  -ContentType "application/json" `
  -Body ($RenderRequest | ConvertTo-Json -Depth 20)

if ($Preview.missingRequiredFields.Count -gt 0) {
  throw "Template fields still missing after mapping: $($Preview.missingRequiredFields -join ', ')"
}

Write-Host "Preview contract hash: $($Preview.lineage.contractHash)"

Invoke-WebRequest `
  -Method POST `
  -Uri "$ApiBaseUrl/api/whiteLabelEngine/v1/render" `
  -Headers $Headers `
  -ContentType "application/json" `
  -Body ($RenderRequest | ConvertTo-Json -Depth 20) `
  -OutFile ".\quotation-$QuoteNo.pdf"
              

Save the map once

When a customer database uses stable column names, save a reusable template mapping. Future render calls can send mappingKey = "accpro-quotation" instead of repeating the full map.

$Mapping = Invoke-RestMethod `
  -Method POST `
  -Uri "$ApiBaseUrl/api/whiteLabelEngine/v1/template-mappings" `
  -Headers $Headers `
  -ContentType "application/json" `
  -Body (@{
    name = "AccPro quotation fields"
    key = "accpro-quotation"
    templateKey = "sales-quotation-v1"
    fieldMap = @{
      quoteNumber = "quoteno"
      quoteDate = "orderdate"
      description = "itmdescr"
      quantity = "Qty"
      unitPrice = "AmtExclNet"
      tax = "vatamt"
      lineTotal = "amountincl"
    }
  } | ConvertTo-Json -Depth 10)
              

Use a hosted starter template with your data source

Starter keys are available through the API catalog for the full document gallery. Create a customer-scoped data source first, test it, put its key in dataSourceId, and put the selected template key in branding.templateKey.

{
  "name": "AccPro SQL Server",
  "key": "accpro-sqlserver",
  "providerType": "sqlserver",
  "connectionString": "Server=sql.example.com,1433;Database=AccPro;User Id=readonly_user;Password=change-me;TrustServerCertificate=True;Encrypt=False"
}
              

{
  "name": "AccPro Quotation QU072810",
  "dataSourceId": "accpro-sqlserver",
  "sql": "SELECT * FROM dbo.teleza_quotation_lines WHERE quoteNumber = @quoteNo ORDER BY lineNumber",
  "parameters": { "quoteNo": "QU072810" },
  "format": "pdf",
  "branding": {
    "companyName": "AccPro Technologies",
    "logoText": "AP",
    "primaryColor": "#123E6B",
    "backgroundColor": "#F8FAFC",
    "templateKey": "sales-quotation-v1"
  }
}
              

To rotate a password or change a connection host later, update the existing key with PUT /api/whiteLabelEngine/v1/data-sources/{key}. Secrets are write-only; omitted secrets remain unchanged.

Invoke-RestMethod `
  -Method PUT `
  -Uri "$ApiBaseUrl/api/whiteLabelEngine/v1/data-sources/production-sqlserver" `
  -Headers $Headers `
  -ContentType "application/json" `
  -Body (@{
    name = "Production SQL Server"
    connectionString = "Server=sql.example.com,1433;Database=AccPro;User Id=readonly_user;Password=new-secret;TrustServerCertificate=True;Encrypt=False"
  } | ConvertTo-Json -Depth 10)
              

Environment

# Local beta
TELEZA_API_URL=http://localhost:8587
TELEZA_API_KEY=sk_live_...

# Hosted or private-cloud beta
TELEZA_API_URL=https://api.teleza.tech
TELEZA_API_KEY=sk_live_...
              

Use the hosted endpoint from your invitation, or run the same workflow against a private-cloud Teleza deployment controlled by your team.

From API key to first document export.

What you need

After you receive your key

Golden workflow

API contract

Discover template fields

Terminal examples

Windows PowerShell

macOS, Linux, or Git Bash

Render from your own rows

Windows PowerShell

Save the map once

Use a hosted starter template with your data source

Environment