> ## Documentation Index
> Fetch the complete documentation index at: https://docs.retab.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Template
> Create an edit template.
Stores a reusable form template from an empty `document` (PDF or Office
document) plus its `form_fields` and a `name`. Later edits can reference the
returned template id instead of re-uploading the document. An unsupported
document format responds with `400`; on success responds with `201`.
Register an `EditTemplate` — a PDF plus a set of pre-defined form fields that can be filled repeatedly via `POST /v1/edits` with `template_id`.
```python Python theme={null}
from retab import MIMEData, Retab
client = Retab()
document = MIMEData(
filename="w9_empty.pdf",
url="https://my-bucket.s3.us-east-1.amazonaws.com/documents/w9_empty.pdf",
)
template = client.edits.templates.create(
name="W-9 Form",
document=document,
form_fields=[
{
"key": "full_name",
"description": "Full legal name of the taxpayer",
"type": "text",
"bbox": {"left": 0.15, "top": 0.20, "width": 0.35, "height": 0.03, "page": 1},
},
{
"key": "tax_id",
"description": "Taxpayer Identification Number",
"type": "text",
"bbox": {"left": 0.15, "top": 0.28, "width": 0.25, "height": 0.03, "page": 1},
},
],
)
print(f"Template ID: {template.id}")
```
```typescript TypeScript theme={null}
import { Retab } from "@retab/node";
const client = new Retab({ apiKey: process.env.RETAB_API_KEY });
const document = {
filename: "w9_empty.pdf",
url: "https://my-bucket.s3.us-east-1.amazonaws.com/documents/w9_empty.pdf",
};
const template = await client.edits.templates.create("W-9 Form", document, [
{
key: "full_name",
description: "Full legal name of the taxpayer",
type: "text",
bbox: { left: 0.15, top: 0.2, width: 0.35, height: 0.03, page: 1 },
},
]);
console.log(`Template ID: ${template.id}`);
```
```go Go theme={null}
package main
import (
"context"
"fmt"
"log"
retab "github.com/retab-dev/retab/clients/go"
)
func ptr[T any](v T) *T { return &v }
func main() {
ctx := context.Background()
client, err := retab.NewClient("")
if err != nil {
log.Fatal(err)
}
document := retab.MIMEData{
Filename: "w9_empty.pdf",
URL: "https://my-bucket.s3.us-east-1.amazonaws.com/documents/w9_empty.pdf",
}
template, err := client.Edits.Templates.Create(ctx, &retab.EditTemplatesCreateParams{
Name: "W-9 Form",
Document: document,
FormFields: []*retab.FormField{
{
Key: "full_name",
Description: "Full legal name of the taxpayer",
Type: retab.FieldTypeText,
Bbox: retab.BBox{Left: 0.15, Top: 0.20, Width: 0.35, Height: 0.03, Page: 1},
},
{
Key: "tax_id",
Description: "Taxpayer Identification Number",
Type: retab.FieldTypeText,
Bbox: retab.BBox{Left: 0.15, Top: 0.28, Width: 0.25, Height: 0.03, Page: 1},
},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Template ID: %s\n", template.ID)
}
```
```ruby Ruby theme={null}
require 'retab'
client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])
document = {
filename: 'w9_empty.pdf',
url: 'https://my-bucket.s3.us-east-1.amazonaws.com/documents/w9_empty.pdf',
}
template = client.edits.templates.create(
name: 'W-9 Form',
document: document,
form_fields: [
{
'key' => 'full_name',
'description' => 'Full legal name of the taxpayer',
'type' => 'text',
'bbox' => { 'left' => 0.15, 'top' => 0.20, 'width' => 0.35, 'height' => 0.03, 'page' => 1 },
},
{
'key' => 'tax_id',
'description' => 'Taxpayer Identification Number',
'type' => 'text',
'bbox' => { 'left' => 0.15, 'top' => 0.28, 'width' => 0.25, 'height' => 0.03, 'page' => 1 },
},
],
)
puts "Template ID: #{template.id}"
```
```rust Rust theme={null}
use retab::enums::FieldType;
use retab::models::{BBox, FormField};
use retab::resources::edit_templates::CreateParams;
use retab::{MimeData, Retab};
#[tokio::main]
async fn main() -> Result<(), Box> {
let client = Retab::new(std::env::var("RETAB_API_KEY")?);
let document = MimeData::new(
"w9_empty.pdf",
"https://my-bucket.s3.us-east-1.amazonaws.com/documents/w9_empty.pdf",
);
let form_fields = vec![
FormField {
bbox: BBox { left: 0.15, top: 0.20, width: 0.35, height: 0.03, page: 1 },
description: "Full legal name of the taxpayer".into(),
type_: FieldType::Text,
key: "full_name".into(),
value: None,
},
FormField {
bbox: BBox { left: 0.15, top: 0.28, width: 0.25, height: 0.03, page: 1 },
description: "Taxpayer Identification Number".into(),
type_: FieldType::Text,
key: "tax_id".into(),
value: None,
},
];
let params = CreateParams::new("W-9 Form", document, form_fields);
let template = client.edits().templates().create(params).await?;
println!("Template ID: {}", template.id);
Ok(())
}
```
```php PHP theme={null}
edits()->templates()->create(
name: 'value',
document: [
'filename' => 'w9_empty.pdf',
'url' => 'https://my-bucket.s3.us-east-1.amazonaws.com/documents/w9_empty.pdf',
],
formFields: [],
);
print_r($result);
```
```csharp C# theme={null}
using System;
using System.Collections.Generic;
using Retab;
using RetabClient = Retab.Retab;
var apiKey = Environment.GetEnvironmentVariable("RETAB_API_KEY")!;
var client = new RetabClient(apiKey);
var document = MimeData.FromUrl(
new Uri("https://my-bucket.s3.us-east-1.amazonaws.com/documents/w9_empty.pdf"));
var template = await client.Edits.Templates.CreateAsync(new EditTemplatesCreateOptions
{
Name = "W-9 Form",
Document = document,
FormFields = new List
{
new FormField
{
Key = "full_name",
Description = "Full legal name of the taxpayer",
Type = FieldType.Text,
Bbox = new BBox { Left = 0.15, Top = 0.20, Width = 0.35, Height = 0.03, Page = 1 },
},
new FormField
{
Key = "tax_id",
Description = "Taxpayer Identification Number",
Type = FieldType.Text,
Bbox = new BBox { Left = 0.15, Top = 0.28, Width = 0.25, Height = 0.03, Page = 1 },
},
},
});
Console.WriteLine($"Template ID: {template.Id}");
```
```java Java theme={null}
import com.retab.RetabClient;
import com.retab.models.BBox;
import com.retab.models.EditTemplate;
import com.retab.models.FormField;
import com.retab.models.MimeData;
import com.retab.types.FieldType;
import java.net.URI;
import java.util.List;
public final class Example {
public static void main(String[] args) throws Exception {
RetabClient client = new RetabClient(System.getenv("RETAB_API_KEY"));
MimeData document =
MimeData.fromUrl(
URI.create("https://my-bucket.s3.us-east-1.amazonaws.com/documents/w9_empty.pdf"));
List formFields =
List.of(
new FormField(
new BBox(0.15, 0.20, 0.35, 0.03, 1L),
"Full legal name of the taxpayer",
FieldType.TEXT,
"full_name",
null),
new FormField(
new BBox(0.15, 0.28, 0.25, 0.03, 1L),
"Taxpayer Identification Number",
FieldType.TEXT,
"tax_id",
null));
EditTemplate template = client.edits().templates().create("W-9 Form", document, formFields);
System.out.println("Template ID: " + template.getId());
}
}
```
```curl cURL theme={null}
curl -X POST \
'https://api.retab.com/v1/edits/templates' \
-H "Authorization: Bearer $RETAB_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"name": "W-9 Form",
"document": {
"filename": "w9_empty.pdf",
"url": "https://my-bucket.s3.us-east-1.amazonaws.com/documents/w9_empty.pdf"
},
"form_fields": [
{
"key": "full_name",
"description": "Full legal name",
"type": "text",
"bbox": {"left": 0.15, "top": 0.20, "width": 0.35, "height": 0.03, "page": 1}
}
]
}'
```
```json 201 theme={null}
{
"id": "edittplt_abc123",
"name": "W-9 Form",
"file": {
"id": "file_6dd6eb00688ad8d1",
"filename": "w9_empty.pdf",
"mime_type": "application/pdf"
},
"form_fields": [
{
"key": "full_name",
"description": "Full legal name",
"type": "text",
"value": null,
"bbox": {
"left": 0.15,
"top": 0.2,
"width": 0.35,
"height": 0.03,
"page": 1
}
}
],
"field_count": 1,
"created_at": "2024-03-15T10:30:00Z",
"updated_at": "2024-03-15T10:30:00Z"
}
```
## OpenAPI
````yaml POST /v1/edits/templates
openapi: 3.1.0
info:
title: FastAPI
version: 0.1.0
servers:
- url: https://api.retab.com
security: []
paths:
/v1/edits/templates:
post:
tags:
- Edits
- Edit Templates
summary: Create Template
description: >-
Create an edit template.
Stores a reusable form template from an empty `document` (PDF or Office
document) plus its `form_fields` and a `name`. Later edits can reference
the
returned template id instead of re-uploading the document. An
unsupported
document format responds with `400`; on success responds with `201`.
operationId: create_template
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEditTemplateRequest'
required: true
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/EditTemplate'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
components:
schemas:
CreateEditTemplateRequest:
properties:
name:
type: string
title: Name
description: Name of the template.
document:
$ref: '#/components/schemas/MIMEData'
description: The PDF document to use as the empty template.
form_fields:
items:
$ref: '#/components/schemas/FormField'
type: array
title: Form Fields
description: Form fields to attach to the template.
type: object
required:
- document
- form_fields
- name
title: CreateEditTemplateRequest
description: Public create-edit-template request body.
EditTemplate:
properties:
id:
type: string
title: Id
description: Unique identifier of the template.
name:
type: string
title: Name
description: Name of the template.
file:
$ref: '#/components/schemas/FileRef'
description: File information for the empty PDF template.
form_fields:
anyOf:
- items:
$ref: '#/components/schemas/FormField'
type: array
- type: 'null'
title: Form Fields
description: Form fields attached to the template.
field_count:
anyOf:
- type: integer
- type: 'null'
title: Field Count
description: Number of form fields in the template.
default: 0
created_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Created At
description: Timestamp of creation.
updated_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Updated At
description: Timestamp of last update.
type: object
required:
- file
- id
- name
title: EditTemplate
description: >-
A reusable edit template: an empty PDF and the `form_fields` defined on
it.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
default: []
type: object
title: HTTPValidationError
MIMEData:
properties:
filename:
type: string
title: Filename
description: The filename of the file
examples:
- file.pdf
- image.png
- data.txt
url:
type: string
title: Url
description: The URL of the file in base64 format
examples:
- data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADIA...
additionalProperties: false
type: object
required:
- filename
- url
title: MIMEData
description: A file represented by its `filename` and a base64 data `url`.
FormField:
properties:
bbox:
$ref: '#/components/schemas/BBox'
description: Position and size of this field on the page.
description:
type: string
title: Description
description: >-
Human-readable description of the field, including label and
instructions.
type:
$ref: '#/components/schemas/FieldType'
description: 'Type of field. Currently supported: ''text'' and ''checkbox''.'
key:
type: string
title: Key
description: Stable key identifying the field in the form data.
value:
anyOf:
- type: string
- type: 'null'
title: Value
description: Filled value of the field as text. Null when no filled value is set.
type: object
required:
- bbox
- description
- key
- type
title: FormField
FileRef:
properties:
id:
type: string
title: Id
description: ID of the file
filename:
type: string
title: Filename
description: Filename of the file
mime_type:
type: string
title: Mime Type
description: MIME type of the file
type: object
required:
- filename
- id
- mime_type
title: FileRef
description: Public/shared file reference used across SDK and customer-facing APIs.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
default: null
ctx:
type: object
title: Context
default: {}
type: object
required:
- loc
- msg
- type
title: ValidationError
BBox:
properties:
left:
type: number
title: Left
description: >-
Left coordinate of the bounding box, relative to page width (0.0 =
left edge, 1.0 = right edge).
top:
type: number
title: Top
description: >-
Top coordinate of the bounding box, relative to page height (0.0 =
top edge, 1.0 = bottom edge).
width:
type: number
title: Width
description: Width of the bounding box, relative to page width (0.0–1.0).
height:
type: number
title: Height
description: Height of the bounding box, relative to page height (0.0–1.0).
page:
type: integer
title: Page
description: 1-based index of the page where this field appears.
type: object
required:
- height
- left
- page
- top
- width
title: BBox
FieldType:
type: string
enum:
- text
- checkbox
title: FieldType
securitySchemes:
HTTPBearer:
type: http
scheme: bearer
````