Skip to content

Branding Profiles API

Branding profiles control how your invoices look: logo, colors, fonts, and header/footer text applied to the rendered PDFs. Each account can have multiple named profiles, exactly one of which is the default. You can select a specific profile per document. If your account has no profiles yet, listing them seeds a default "Default" profile automatically.

Create Branding Profile

POST /api/v1/branding-profiles

Request:

{
  "name": "Acme Corp",
  "primary_color": "#111827",
  "accent_color": "#06B6D4",
  "font_family": "Inter",
  "header_text": "Acme Corp — Invoices",
  "footer_text": "Generated by InvoicePDFs",
  "hide_invoicepdfs_branding": false,
  "is_default": false
}
Field Required Description
name Yes Display name for the profile
primary_color No Hex color for primary elements. Defaults to #111827
accent_color No Hex accent color. Defaults to #111827
font_family No Font family name used in the PDF
header_text No Text shown in the PDF header
footer_text No Text shown in the PDF footer. Defaults to Generated by InvoicePDFs
hide_invoicepdfs_branding No Hide the "Generated by InvoicePDFs" credit. Paid plans only — see the note below. Defaults to false
is_default No Make this the default profile. Defaults to false

hide_invoicepdfs_branding is a paid-plan feature. Documents rendered on the Free plan always carry a small "Generated by InvoicePDFs" footer credit. Setting your own footer_text does not remove it — your text and the credit are shown together. The field is accepted on every plan and simply has no effect until the plan allows it, so you can set it once and keep sending it across an upgrade.

Response 200 OK:

{
  "data": {
    "id": "brnd_01XYZ",
    "name": "Acme Corp",
    "is_default": false,
    "logo_file_id": null,
    "primary_color": "#111827",
    "accent_color": "#06B6D4",
    "font_family": "Inter",
    "header_text": "Acme Corp — Invoices",
    "footer_text": "Generated by InvoicePDFs",
    "hide_invoicepdfs_branding": false,
    "created_at": "2026-07-20T10:00:00Z",
    "updated_at": "2026-07-20T10:00:00Z"
  }
}

Note

The first profile created for an account is always made the default, regardless of is_default. Setting is_default to true on a later profile moves the default to it.

Try it

List Branding Profiles

GET /api/v1/branding-profiles

Profiles are returned with the default first. If the account has none, a "Default" profile is created and returned.

Response:

{
  "data": [
    {
      "id": "brnd_01XYZ",
      "name": "Default",
      "is_default": true,
      "logo_file_id": null,
      "primary_color": "#111827",
      "accent_color": "#111827",
      "font_family": null,
      "header_text": null,
      "footer_text": "Generated by InvoicePDFs",
      "hide_invoicepdfs_branding": false,
      "created_at": "2026-07-20T10:00:00Z",
      "updated_at": "2026-07-20T10:00:00Z"
    }
  ]
}
Try it

Get Branding Profile

GET /api/v1/branding-profiles/{profile_id}

Fetch a single branding profile by ID, including its colors, fonts, and logo_file_id. Returns 404 not_found if the profile doesn't exist.

Response:

{
  "data": {
    "id": "brnd_01XYZ",
    "name": "Acme Corp",
    "is_default": false,
    "logo_file_id": "fil_01ABC",
    "primary_color": "#111827",
    "accent_color": "#06B6D4",
    "font_family": "Inter",
    "header_text": "Acme Corp — Invoices",
    "footer_text": "Generated by InvoicePDFs",
    "hide_invoicepdfs_branding": false,
    "created_at": "2026-07-20T10:00:00Z",
    "updated_at": "2026-07-20T10:00:00Z"
  }
}
Try it

Update Branding Profile

PATCH /api/v1/branding-profiles/{profile_id}

Only include the fields you want to change:

{
  "accent_color": "#06B6D4",
  "header_text": "Acme Corp — Billing"
}
Field Required Description
name No Display name for the profile
primary_color No Hex color for primary elements
accent_color No Hex accent color
font_family No Font family name used in the PDF
header_text No Text shown in the PDF header
footer_text No Text shown in the PDF footer
hide_invoicepdfs_branding No Hide the "Generated by InvoicePDFs" branding
is_default No Set to true to make this the default profile
Try it

Set Default

POST /api/v1/branding-profiles/{profile_id}/default

Makes this profile the default and clears the default flag on all others. The default profile is applied to documents that don't name a specific profile.

Response — the updated profile, now with is_default: true:

{
  "data": {
    "id": "brnd_01XYZ",
    "name": "Acme Corp",
    "is_default": true,
    "logo_file_id": "fil_01ABC",
    "primary_color": "#111827",
    "accent_color": "#06B6D4",
    "font_family": "Inter",
    "header_text": "Acme Corp — Invoices",
    "footer_text": "Generated by InvoicePDFs",
    "hide_invoicepdfs_branding": false,
    "created_at": "2026-07-20T10:00:00Z",
    "updated_at": "2026-08-06T09:00:00Z"
  }
}
Try it

Delete Branding Profile

DELETE /api/v1/branding-profiles/{profile_id}

If you delete the default profile, the oldest remaining profile is promoted to default.

Response:

{
  "data": {
    "deleted": true
  }
}
Try it 
POST /api/v1/branding-profiles/{profile_id}/logo

Upload a logo image for the profile. The request is multipart/form-data with a single file field. The file must be an image (image/png, image/jpeg, etc.); a non-image file returns 422 Unprocessable Entity with error code unprocessable_entity.

curl -X POST https://invoicepdfs.com/api/v1/branding-profiles/brnd_01XYZ/logo \
  -H "Authorization: Bearer inv_..." \
  -F "file=@logo.png"

The updated branding profile is returned, with logo_file_id set to the newly stored file.

Try it 
DELETE /api/v1/branding-profiles/{profile_id}/logo

Clears the logo (logo_file_id) from the profile.

Response:

{
  "data": {
    "deleted": true
  }
}
Try it