Template creation is processed asynchronously. The endpoint returns
immediately with a templateId that you can use to check the creation status.
Template creation usually takes a couple of minutes, but can vary based on
complexity and system load.
Request
curl --location 'https://api.pdfnoodle.com/v1/integration/templates/create' \
--header 'Authorization: Bearer pdfnoodle_api_123456789' \
--header 'Content-Type: application/json' \
--data '{
"prompt": "Create an invoice template with company logo, billing address, line items table, and total amount",
"displayName": "Standard Invoice",
"fileUrl": "https://example.com/reference-invoice.pdf"
}'
Response
{
"message": "Async template creation started. It usually takes a couple of minutes to finish creation. You can check the status of the template creation by fetching it using the templateId.",
"fetchTemplateUrl": "https://api.pdfnoodle.com/v1/integration/templates/a1b2c3d4e5",
"templateId": "a1b2c3d4e5"
}
202 Accepted immediately after starting the template creation process. The response includes a templateId that you can use to check the creation status.
Parameters
Text description of the template you want to create. This will be enriched by
AI to generate the final template. Provide detailed, specific prompts for
better results. Include information about: - Document type (invoice, receipt,
report, etc.) - Required sections (header, footer, body content) - Layout
preferences - Data fields that need to be included
Human-readable name for the template (e.g., “Invoice Template”, “Receipt
Template”)
Optional URL to a reference file (PDF, image, etc.) that the AI can use as
inspiration for the template design. This can help the AI understand your
design preferences if you have an existing document to reference.
Response Fields
Checking Template Creation Status
After creating a template, you can check its status by polling the Get Template endpoint using the templateId returned from this request.
The template will have different status values:
ONGOING: Template creation is still in progressSUCCESS: Template has been created successfullyFAILED: Template creation failed (check metadata.errorMessage)
Usage Example
Here’s a complete example of creating a template and polling for completion:
async function createTemplate(prompt, displayName, fileUrl) {
// 1. Create template
const createResponse = await fetch(
"https://api.pdfnoodle.com/v1/integration/templates/create",
{
method: "POST",
headers: {
Authorization: "Bearer pdfnoodle_api_123456789",
"Content-Type": "application/json",
},
body: JSON.stringify({
prompt,
displayName,
fileUrl,
}),
}
);
const { templateId, fetchTemplateUrl } = await createResponse.json();
// 2. Poll for completion
let templateReady = false;
while (!templateReady) {
await new Promise((resolve) => setTimeout(resolve, 15000)); // Wait 15 seconds
const statusResponse = await fetch(
`https://api.pdfnoodle.com/v1/integration/templates/${templateId}`,
{
headers: { Authorization: "Bearer pdfnoodle_api_123456789" },
}
);
const data = await statusResponse.json();
if (data.template) {
// Template is complete
templateReady = true;
console.log("Template ready:", data.template);
return data.template;
} else if (data.status === "SUCCESS") {
// Template creation completed
templateReady = true;
console.log("Template created:", data.templateHtml);
return data;
} else if (data.status === "FAILED") {
// Template creation failed
throw new Error(data.metadata.errorMessage);
}
// Otherwise, status is 'ONGOING', continue polling
}
}
// Usage
createTemplate(
"Create an invoice template with company logo, billing address, line items table, and total amount",
"Standard Invoice"
);
import requests
import time
def create_template(prompt, display_name, file_url=None):
# 1. Create template
response = requests.post(
'https://api.pdfnoodle.com/v1/integration/templates/create',
headers={
'Authorization': 'Bearer pdfnoodle_api_123456789',
'Content-Type': 'application/json'
},
json={
'prompt': prompt,
'displayName': display_name,
'fileUrl': file_url
}
)
result = response.json()
template_id = result['templateId']
# 2. Poll for completion
template_ready = False
while not template_ready:
time.sleep(15) # Wait 15 seconds
status_response = requests.get(
f'https://api.pdfnoodle.com/v1/integration/templates/{template_id}',
headers={'Authorization': 'Bearer pdfnoodle_api_123456789'}
)
data = status_response.json()
if 'template' in data:
# Template is complete
template_ready = True
print('Template ready:', data['template'])
return data['template']
elif data.get('status') == 'SUCCESS':
# Template creation completed
template_ready = True
print('Template created:', data['templateHtml'])
return data
elif data.get('status') == 'FAILED':
# Template creation failed
raise Exception(data['metadata']['errorMessage'])
# Otherwise, status is 'ONGOING', continue polling
# Usage
create_template(
'Create an invoice template with company logo, billing address, line items table, and total amount',
'Standard Invoice'
)
If template creation fails, the status will be set to FAILED and error
details will be available in the metadata when fetching the template. You
should handle these errors appropriately in your application.
Error Responses
401 Unauthorized
{
"message": "Unauthorized"
}
500 Internal Server Error
{
"message": "Error message describing what went wrong"
}
