Branding & Preferences (3 Operations)

Templates & Preferences API

Standardize candidate presentation across your recruiting agency or enterprise HR team. Query custom branded Word (.docx) templates, set personal or company-wide default formatting preferences, and manage organizational template lifecycles.

The 4-tier template resolution hierarchy

When generating a document via POST /resumes/:id/export or creating a 30-day preview with POST /resumes/:id/preview, your integration does not need to pass an explicit template_id every time. The export engine evaluates a deterministic 4-tier fallback hierarchy:

1Explicit Export Override

If template_id is sent directly in the JSON export request body, the engine renders that exact template immediately.

2Resume Ingest Binding

If omitted during export, the engine looks for any default template_id supplied when the file was originally ingested at POST /resumes.

3Recruiter Default Preference

If the resume has no bound template, the engine looks up the personal default configured by the specific recruiter who uploaded or owns the candidate record.

4Organization Global Fallback

If no recruiter preference exists, the company-wide default is used. If no organization default is set, the API returns 400 TEMPLATE_REQUIRED.

Template scoping & safe removal semantics

Public vs. Custom Templates: System templates provided by CVFormatter have public: true and are accessible across all workspaces. Custom templates uploaded by agency administrators are strictly isolated to your organization (public: false).

Non-Destructive Deletion: Calling DELETE /templates/:templateId does not destroy underlying assets or corrupt historical candidate profiles. Instead, it soft-hides the template within your tenant and automatically unbinds it if it was designated as the active organization fallback.

GET

/templates?limit=20

templates:readHTTP 200

List organization & public templates

Returns all branded templates available to your organization, including global system templates and private custom agency designs. Paginated via opaque cursors (next_cursor=null indicates the last page).

Parameters

Field	Type & Description	Required
limit	numberNumber of template records per page (range 1–100, default 20).	No
cursor	stringPagination cursor from next_cursor in the previous response.	No

curl --fail-with-body -X GET "$CVF_BASE_URL/templates?limit=20" \
  -H "Authorization: Bearer $CVF_API_KEY"

Return Result:

{
  "data": [
    {
      "id": "tmpl_modern_blue_01",
      "name": "Executive Blue Header",
      "public": false,
      "updated_at": "2026-10-10T04:00:00.000Z"
    },
    {
      "id": "tmpl_system_minimal",
      "name": "System Minimalist",
      "public": true,
      "updated_at": "2026-08-15T00:00:00.000Z"
    }
  ],
  "next_cursor": null
}

PUT

/template-preferences

resumes:writeHTTP 200

Configure default template preferences

Sets default styling preferences at either the recruiter level or company-wide organization level. When using an Organization Key, you can configure the tenant fallback or set preferences on behalf of specific recruiters by passing recruiter_id.

Note: Setting an organization-wide default does not overwrite existing personal recruiter preferences or templates explicitly specified during file upload.

Parameters

Field	Type & Description	Required
template_id	stringUnique ID of an available template to designate as the default.	Yes
scope	"recruiter" \| "organization"Preference tier. Set to "organization" for company-wide fallback, or "recruiter" for personal default.	No
recruiter_id	stringTarget recruiter ID (required when updating a recruiter's default preference using an Organization Key).	No

Request Body (JSON)

{
  "template_id": "tmpl_modern_blue_01",
  "scope": "organization"
}

curl --fail-with-body -X PUT "$CVF_BASE_URL/template-preferences" \
  -H "Authorization: Bearer $CVF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template_id":"tmpl_modern_blue_01","scope":"organization"}'

Return Result:

{
  "scope": "organization",
  "organization_id": "ORG_9182AB3",
  "recruiter_id": null,
  "template_id": "tmpl_modern_blue_01",
  "request_id": "req_pref_88301a"
}

DELETE

/templates/:templateId

resumes:write • owner recruiter or org keyHTTP 200

Remove an organization template

Soft-hides a custom template within your organization and clears it from default preference slots. Historical resume exports that used this template continue to render normally without corruption.

Note: Requires an Organization Key or the personal key of the recruiter who originally created the template. Repeating deletion on an already-removed template is safely idempotent.

curl --fail-with-body -X DELETE "$CVF_BASE_URL/templates/tmpl_modern_blue_01" \
  -H "Authorization: Bearer $CVF_API_KEY"

Return Result:

{
  "id": "tmpl_modern_blue_01",
  "removed": true,
  "organization_id": "ORG_9182AB3",
  "request_id": "req_del_10284f"
}