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.

You read the current values from the personalization block of GET /v1/account, and you change them with a single partial update on PATCH /v1/account/personalization. Both endpoints work the same in test mode (fact_test_ keys) and live (fact_live_ keys).

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.

Reading the current personalization

The personalization block is part of the Account resource:

curl -s https://api.factuarea.com/v1/account \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  | 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/account/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 — the same shape as GET /v1/account, including the refreshed personalization block. Requires the account:write scope.

curl -s -X PATCH https://api.factuarea.com/v1/account/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/account/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/account/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/account/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/account/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/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