Account personalization

Personalization controls how your invoices look and read: the language the generated PDF is rendered in, the PDF template that frames it, and the accent color that brands it. All three live on the authenticated company and apply to every document the API renders for you.

Personalization belongs to the company, so both operations hang off the company axis: you change the three settings with a single partial update on PATCH /v1/companies/{company}/personalization, which answers with the updated Account resource and its refreshed personalization block, and you discover the catalog your plan allows with GET /v1/companies/{company}/personalization/templates. Both work the same in test mode (fact_test_ keys) and live (fact_live_ keys).

{company} is the id (UUID v7) of the tax ID you operate on, and in the curl examples it is $COMPANY_ID. Reach a tax ID explains how to resolve it.

The three settings

Invoice-emission language

language is the locale the generated PDF is rendered in. Set it to en and the invoice headings, labels and dates of every PDF you generate switch to English; ca renders them in Catalan; es (the default) in Spanish. It does not change the message text of API errors — those stay Spanish, as documented in the error model.

PDF template

pdf_template is a slug of the closed PdfTemplate catalog. The five system templates are classic, modern (the default), minimal, corporative and premium. Which ones your account may select depends on your plan — discover the allowed set with the templates endpoint rather than hardcoding it.

Accent color

accent_color is the #RRGGBB hex color used to brand the PDF (headers, totals, accents). Send null to clear it and fall back to the template default.

Personalization and the template library

These three settings are the account-wide level of the PDF look. For anything finer — several designs, a brand with its own logo, a template per document type, per series or per contact — use the PDF template library. The two work together:

• Last level. When a document has no manual selection and no series, contact or company default template that is available, it is rendered from these settings (pdf_template, accent_color, the logo and the company data), exactly as before. Setting a company default in the library takes precedence over them. The full order is in which template a document uses.
• One-time import. When revisioned output is initialized for your company, the settings it has today (template, customization, logo, brand image and commercial contact data) are copied into one imported template and one imported brand, named in your emission language. They are an ordinary starting point in the library. From then on the two sides do not sync while the company has not moved to the library: a later PATCH of pdf_template does not edit those revisions, and editing them does not change these settings. Once the company works with the library, that PATCH applies the design and the color to its main template (a new revision) and the read returns that template's values; without a main template it answers 409 pdf_main_template_required.
• Already issued documents. A document keeps the PDF it was captured with. Changing any of these settings only affects documents you create or revise afterwards.
• Same plan rules. pdf_capabilities keeps describing what your plan allows, and the five slugs of pdf_template are the same presets (base_preset) that library templates start from. The read-only render_activation of GET /v1/companies/{company}/pdf-templates/defaults tells whether the library is effectively active for the company.

language and accent_color keep their meaning: language is the emission language of the account, while a library template also carries its own titles and labels in es, en and ca.

Reading the current personalization

The personalization block travels in the Account resource that the update returns — v1 publishes no read-only endpoint for it, so read it back from the response of the PATCH you just made, or from the one you make with an empty body to change nothing:

curl -s -X PATCH https://api.factuarea.com/v1/companies/$COMPANY_ID/personalization \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' \
  | jq '.data.personalization'

{
  "language": "es",
  "pdf_template": "modern",
  "accent_color": "#1a73e8",
  "pdf_capabilities": {
    "can_upload_logo": true,
    "can_customize": true,
    "can_upload_brand_image": true,
    "requires_attribution": false,
    "available_templates": ["classic", "modern", "minimal", "corporative", "premium"],
    "upgrade_plan": null
  }
}

language and pdf_template are always present. accent_color is null when no color is configured.

pdf_capabilities is read-only and describes what the account's plan allows in the rendered documents. Read it to enable or disable branding controls before calling PATCH:

Updating personalization

PATCH /v1/companies/{company}/personalization is a partial update: only the fields you send are applied, and any field you omit keeps its current value. The response is the updated Account resource, including the refreshed personalization block. Requires the account:write scope.

curl -s -X PATCH https://api.factuarea.com/v1/companies/$COMPANY_ID/personalization \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "en", "pdf_template": "premium", "accent_color": "#0F766E" }' \
  | jq '.data.personalization'

Change a single setting by sending only that field:

curl -s -X PATCH https://api.factuarea.com/v1/companies/$COMPANY_ID/personalization \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "ca" }'

Clear the accent color by sending null:

curl -s -X PATCH https://api.factuarea.com/v1/companies/$COMPANY_ID/personalization \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "accent_color": null }'

Validation errors

Each setting is validated against its closed catalog. A value outside the catalog returns 422 with the allowed_values for the offending field — language and pdf_template against their enum, accent_color against the #RRGGBB pattern:

{
  "error": {
    "type": "validation_error",
    "code": "validation_failed",
    "message": "El idioma indicado no es válido.",
    "param": "language",
    "allowed_values": ["es", "en", "ca"]
  }
}

An accent_color or a template outside available_templates on an account without the PDF editor returns 403 with code: feature_not_available_in_plan and applies no field. pdf_capabilities.upgrade_plan names the plan that unlocks it.

Discovering available templates

GET /v1/companies/{company}/personalization/templates lists the PDF templates available for your account's plan (plan-aware) plus the accepted format for accent_color . Use it to populate a picker instead of hardcoding the catalog. Requires the account:read scope.

curl -s https://api.factuarea.com/v1/companies/$COMPANY_ID/personalization/templates \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  | jq '.data'

{
  "object": "personalization_templates",
  "templates": [
    { "slug": "classic", "label": "Clásica", "available": true },
    { "slug": "modern", "label": "Moderna", "available": true },
    { "slug": "minimal", "label": "Minimalista", "available": true },
    { "slug": "corporative", "label": "Corporativa", "available": false },
    { "slug": "premium", "label": "Premium", "available": false }
  ],
  "accent_color": {
    "format": "#RRGGBB",
    "example": "#1a73e8"
  },
  "pdf_capabilities": {
    "can_upload_logo": true,
    "can_customize": false,
    "can_upload_brand_image": true,
    "requires_attribution": true,
    "available_templates": ["classic", "modern", "minimal"],
    "upgrade_plan": "empresario"
  }
}

pdf_capabilities repeats the block of GET /v1/accounts/{account}, so a picker can be built from this single call. The available flag reflects your current plan: a false slug exists in the catalog but cannot be set until you upgrade. Offer only the available templates, and read accent_color.format to validate the color client-side before the PATCH.

Scopes