API Reference

The Formatix API lets you format CVs and generate professional documents programmatically. Integrate with Zapier, Salesforce, HubSpot, and thousands of other platforms — or build your own custom workflows.

Base URL https://app.formatix.ai/api/v1

Authentication

All API requests require a Bearer token in the Authorization header. Generate API keys from the Integrations page.

Keys are prefixed with fxi_ and shown only once at creation. Store them securely — you cannot retrieve the full key again.

Header

Authorization: Bearer fxi_your_api_key_here

Keep your keys secret. Do not expose them in client-side code, public repositories, or browser requests. Use server-side calls only.

Error Handling

The API returns standard HTTP status codes. Errors include a JSON body with error (machine-readable code) and message (human-readable).

Error Response

{
  "success": false,
  "error": "insufficient_credits",
  "message": "Not enough credits. Need 3, have 1.",
  "required": 3,
  "available": 1
}

Status	Error Code	Description
400	missing_field	A required field is missing from the request
400	invalid_field	A field has an invalid value
401	authentication_required	Missing or malformed Authorization header
401	invalid_key	API key is invalid, revoked, or expired
402	insufficient_credits	Not enough credits for the requested operation
403	access_denied	You don't have access to the requested template
404	not_found / invalid_template	Resource or template not found
500	processing_failed	Internal processing error

Credits & Limits

Every formatting operation costs 1 credit per file. Multi-file requests deduct one credit per file uploaded (max 20 files per request for BIOS templates, 10 for Custom templates).

Check your balance with the Credits endpoint before submitting jobs. The API returns 402 when credits are insufficient.

Format CV

POST /api/v1/format-cv/

Upload one or more CV files and format them using a specified template. The request is processed asynchronously — poll the returned record_id for status.

Request Body (multipart/form-data)

Parameter	Type	Description
template_id required	integer	ID of the template to use. Get available IDs from List Templates.
template_type required	string	`"cvtobios"` for BIOS templates or `"custom"` for Custom templates.
file required	file(s)	One or more CV files (PDF, DOCX, DOC, RTF, TXT). Send as `file` or `files`. Max 20 files for BIOS, 10 for Custom.
output_format optional	string	`"docx"` (default), `"pptx"`, or `"xlsx"`. PowerPoint and Excel are only available for BIOS templates that have those formats configured.

Example Request

curl -X POST https://app.formatix.ai/api/v1/format-cv/ \
  -H "Authorization: Bearer fxi_your_api_key" \
  -F "template_id=42" \
  -F "template_type=cvtobios" \
  -F "output_format=docx" \
  -F "file=@/path/to/resume.pdf"

import requests

url = "https://app.formatix.ai/api/v1/format-cv/"
headers = {"Authorization": "Bearer fxi_your_api_key"}

with open("resume.pdf", "rb") as f:
    response = requests.post(url, headers=headers, files={
        "file": ("resume.pdf", f, "application/pdf"),
    }, data={
        "template_id": 42,
        "template_type": "cvtobios",
        "output_format": "docx",
    })

print(response.json())
# {"success": true, "record_id": 1234, "status": "processing", ...}

const form = new FormData();
form.append("template_id", "42");
form.append("template_type", "cvtobios");
form.append("output_format", "docx");
form.append("file", fileInput.files[0]);

const res = await fetch("https://app.formatix.ai/api/v1/format-cv/", {
  method: "POST",
  headers: { "Authorization": "Bearer fxi_your_api_key" },
  body: form,
});

const data = await res.json();
console.log(data);
// {success: true, record_id: 1234, status: "processing", ...}

Response

200 OK

JSON

{
  "success": true,
  "record_id": 1234,
  "status": "processing",
  "template_type": "cvtobios",
  "output_format": "docx",
  "message": "1 CV(s) queued for formatting. Poll /api/v1/format-cv/1234/"
}

For multi-file Custom template requests, the response also includes record_ids — an array of all record IDs in the batch.

Format Status

GET /api/v1/format-cv/{record_id}/

Poll the status of a formatting job. When the status changes to "Formatted", the response includes a download_url.

Path Parameters

Parameter	Type	Description
record_id required	integer	The `record_id` returned from the Format CV request.

Example Request

cURL

curl https://app.formatix.ai/api/v1/format-cv/1234/ \
  -H "Authorization: Bearer fxi_your_api_key"

Response (Processing)

200 OK

JSON

{
  "success": true,
  "record_id": 1234,
  "status": "Processing"
}

Response (Complete)

200 OK

JSON

{
  "success": true,
  "record_id": 1234,
  "status": "Formatted",
  "download_url": "https://docs.google.com/document/d/abc123/export?format=docx"
}

Polling strategy: We recommend polling every 5–10 seconds. Most documents complete within 30–90 seconds depending on length and complexity.

Download URL Formats

Output	URL Pattern
docx	`https://docs.google.com/document/d/{id}/export?format=docx`
pptx	`https://docs.google.com/presentation/d/{id}/export/pptx`
xlsx	`https://docs.google.com/spreadsheets/d/{id}/export?format=xlsx`

List Templates

GET /api/v1/templates/

Returns all templates assigned to the API key owner. Use the returned id and type when calling Format CV.

Example Request

cURL

curl https://app.formatix.ai/api/v1/templates/ \
  -H "Authorization: Bearer fxi_your_api_key"

Response

200 OK

JSON

{
  "templates": [
    {
      "id": 42,
      "name": "Executive Profile",
      "type": "cvtobios",
      "category": "executive",
      "formats": ["docx", "pptx"]
    },
    {
      "id": 15,
      "name": "Standard CV",
      "type": "custom",
      "category": "custom",
      "formats": ["docx"]
    }
  ]
}

Response Fields

Field	Type	Description
id	integer	Template ID — pass as `template_id` to Format CV.
name	string	Human-readable template name.
type	string	`"cvtobios"` or `"custom"` — pass as `template_type`.
category	string	Template category (e.g. `"executive"`, `"custom"`).
formats	string[]	Available output formats: `"docx"`, `"pptx"`, `"xlsx"`.

Check Credits

GET /api/v1/credits/

Returns the current credit balance, plan name, daily cap, and remaining generations for today.

Example Request

cURL

curl https://app.formatix.ai/api/v1/credits/ \
  -H "Authorization: Bearer fxi_your_api_key"

Response

200 OK

JSON

{
  "credits": 47,
  "plan": "Plus",
  "daily_generation_cap": 100,
  "generations_remaining_today": 88
}

Response Fields

Field	Type	Description
credits	integer	Total credits available in your account.
plan	string	Current subscription plan name.
daily_generation_cap	integer	Maximum generations allowed per day.
generations_remaining_today	integer	Remaining generations for today before hitting the daily cap.

Create API Key

POST /api/v1/keys/

Create a new API key. Requires session authentication (logged-in user). The full key is returned only once in the response.

Request Body (JSON)

Parameter	Type	Description
name optional	string	A label for the key (e.g. "Zapier", "Internal Script"). Defaults to "My API Key".

Response

201 Created

JSON

{
  "id": 7,
  "name": "Zapier",
  "key": "fxi_a1b2c3d4e5f6g7h8i9j0...",
  "created_at": "2026-03-10T14:30:00Z"
}

Save this key immediately. The full key value is returned only once and cannot be retrieved later. If you lose it, revoke it and create a new one.

List API Keys

GET /api/v1/keys/

List all API keys for the authenticated user. Returns key metadata only (prefix, not the full key). Requires session authentication.

Response

200 OK

JSON

{
  "keys": [
    {
      "id": 7,
      "name": "Zapier",
      "key_prefix": "fxi_a1b2....",
      "created_at": "2026-03-10T14:30:00Z",
      "last_used_at": "2026-03-10T16:45:00Z",
      "is_active": true
    }
  ]
}

Revoke API Key

DELETE /api/v1/keys/{key_id}/

Revoke an API key. The key is soft-deleted and any integrations using it will immediately stop working. Requires session authentication.

Path Parameters

Parameter	Type	Description
key_id required	integer	ID of the key to revoke.

Response

200 OK

JSON

{
  "success": true,
  "message": "API key revoked."
}