Brand Templates

Create a brand template

Creates a brand template of the account: the look a report is printed with and a client portal view is drawn with -- the fonts, the colours, the margins, the front cover, the table of contents and the header of the portal.

A NEW TEMPLATE IS BORN COMPLETE. Every setting a body does not carry takes the default of the product, and the template is born with the logo of the platform, which is what makes include_logo true mean something on the first call. A body with a name alone therefore writes a template that prints correctly; send only what is meant to differ.

THE BODY IS THE OBJECT /v1/brand-templates/get ANSWERS. The keys that read publishes and a write has no column for -- brand_template_key, is_system, logo and cover_image -- are accepted and ignored with a READ_ONLY_FIELD_IGNORED warning, and a null means "leave it as it is", which on a creation means the default.

THE TWO IMAGES ARE NOT WRITTEN HERE: /v1/brand-templates/set-logo and /v1/brand-templates/set-cover-image each write one file. A creation with cover_style 'image' is refused with details.reason cover_image_required, because a template being created carries no image yet.

Colours are written as #RRGGBB and stored in lower case. cover_tone auto, web_font_family app_default and cover_inverted false are stored as an absent column, which is what the settings window of the application writes for them, and a read publishes the same values back. colors does not change size.

if_version is not accepted, and the call is never confirmed: its inverse is /v1/brand-templates/delete.

Refusals: 400 for the framework and the body (VALIDATION_FAILED, one entry per field), 403 WRITE_ACCESS_DISABLED.

A brand template written through this API is not visible to an application window that is already open: the page has to be reloaded before the same template is edited there.

Every write endpoint reads dry_run and idempotency_key; see the Write guarantees section of the introduction.

post/brand-templates/create

Request

  • Base URL: https://api.reportingninja.com/v1
  • URL: https://api.reportingninja.com/v1/brand-templates/create
  • Auth: HTTP bearer

Request body

namestring nullable required
internal_notesstring nullable

A note for the account's own staff. Left out or null, it is left as it is.

font_familystring nullable

The font of the PDF. Left out or null, it is left as it is.

margin_topinteger nullable

The top margin of the page, in points. Left out or null, it is left as it is.

margin_bottominteger nullable

The bottom margin of the page, in points. Left out or null, it is left as it is.

margin_leftinteger nullable

The left margin of the page, in points. Left out or null, it is left as it is.

margin_rightinteger nullable

The right margin of the page, in points. Left out or null, it is left as it is.

report_title_text_colorstring nullable

The colour of the title of the cover, as #RRGGBB. Left out or null, it is left as it is.

report_title_font_sizeinteger nullable

The size of the title of the cover. Left out or null, it is left as it is.

report_title_font_weight'normal' | 'bold' nullable

The weight of the title of the cover. Left out or null, it is left as it is.

report_subtitle_text_colorstring nullable

The colour of the subtitle of the cover, as #RRGGBB. Left out or null, it is left as it is.

report_subtitle_font_sizeinteger nullable

The size of the subtitle of the cover. Left out or null, it is left as it is.

report_subtitle_font_weight'normal' | 'bold' nullable

The weight of the subtitle of the cover. Left out or null, it is left as it is.

section_name_text_colorstring nullable

The colour of the name of a section, as #RRGGBB. Left out or null, it is left as it is.

section_name_font_sizeinteger nullable

The size of the name of a section. Left out or null, it is left as it is.

section_name_font_weight'normal' | 'bold' nullable

The weight of the name of a section. Left out or null, it is left as it is.

date_range_text_colorstring nullable

The colour of the period line of a section, as #RRGGBB. Left out or null, it is left as it is.

date_range_font_sizeinteger nullable

The size of the period line of a section. Left out or null, it is left as it is.

date_range_font_weight'normal' | 'bold' nullable

The weight of the period line of a section. Left out or null, it is left as it is.

component_name_text_colorstring nullable

The colour of the name of a widget, as #RRGGBB. Left out or null, it is left as it is.

component_name_font_sizeinteger nullable

The size of the name of a widget. Left out or null, it is left as it is.

component_name_font_weight'normal' | 'bold' nullable

The weight of the name of a widget. Left out or null, it is left as it is.

footer_text_colorstring nullable

The colour of the footer, as #RRGGBB. Left out or null, it is left as it is.

footer_font_sizeinteger nullable

The size of the footer. Left out or null, it is left as it is.

footer_font_weight'normal' | 'bold' nullable

The weight of the footer. Left out or null, it is left as it is.

include_logoboolean nullable

Whether the report prints the logo. It cannot be true on a template that carries none, and setting it FALSE REMOVES the file, which is what the settings window of the application does when the checkbox is unticked: nothing keeps a copy, so switching it on again needs a new upload through /v1/brand-templates/set-logo. The answer says so with a LOGO_REMOVED warning. Left out or null, it is left as it is.

include_section_lineboolean nullable

Whether a line is drawn under the name of a section. Left out or null, it is left as it is.

section_line_colorstring nullable

The colour of that line, as #RRGGBB. Left out or null, it is left as it is.

component_name_background_colorstring nullable

The background behind the name of a widget, as #RRGGBB. Left out or null, it is left as it is.

component_content_text_colorstring nullable

The colour of the content of a widget, as #RRGGBB. Left out or null, it is left as it is.

component_content_font_sizeinteger nullable

The size of the content of a widget. Left out or null, it is left as it is.

colorsstring[] nullable

The palette the charts are drawn with, in order, as #RRGGBB. Left out or null, it is left as it is.

footer_contentstring nullable

The text of the footer. Left out or null, it is left as it is.

include_footer_lineboolean nullable

Whether a line is drawn above the footer. Left out or null, it is left as it is.

footer_line_colorstring nullable

The colour of that line, as #RRGGBB. Left out or null, it is left as it is.

primary_colorstring nullable

The main colour of the brand, as #RRGGBB. Left out or null, it is left as it is.

cover_style'gradient' | 'plain' | 'aurora' | 'circles' | 'waves' | 'diagonal' | 'rings' | 'dots' | 'bubbles' | 'contours' | 'blocks' | 'image' nullable

The style the front cover is drawn with. A template that never picked one is read as plain, which is what it is drawn with. Left out or null, it is left as it is.

cover_tone'auto' | 'light' | 'dark' | 'custom' nullable

The tone of the text of the cover. auto takes it from the primary colour and is what a template that never picked one is read as. Left out or null, it is left as it is.

cover_text_colorstring nullable

The colour of the cover text when the tone is custom, as #RRGGBB. Left out or null, it is left as it is.

cover_invertedboolean nullable

Whether the cover is drawn on a coloured surface instead of white paper. Left out or null, it is left as it is.

prepared_bystring nullable

The line naming who prepared the report. Left out or null, it is left as it is.

prepared_forstring nullable

The line naming who it was prepared for. Left out or null, it is left as it is.

toc_style'cards' | 'rule' | 'band' | 'timeline' nullable

The style of the table of contents. A template that never picked one is read as timeline. Left out or null, it is left as it is.

portal_header_style'none' | 'letterhead' | 'card' | 'band' nullable

The header the client portal wears. none draws no header and is what a template that never picked one is read as. Left out or null, it is left as it is.

portal_header_logoboolean nullable

Whether that header carries the logo. Left out or null, it is left as it is.

web_font_familystring nullable

The font of the client portal and of a public link. app_default is the font of the application. Left out or null, it is left as it is.

brand_template_keystring nullable

Ignored on a write: part of what a read publishes and not part of what a write stores. It is accepted so the object /v1/brand-templates/get answers can be sent straight back, and it comes back as a READ_ONLY_FIELD_IGNORED warning.

is_systemboolean nullable

Ignored on a write: part of what a read publishes and not part of what a write stores. It is accepted so the object /v1/brand-templates/get answers can be sent straight back, and it comes back as a READ_ONLY_FIELD_IGNORED warning.

logoobject nullable

Ignored on a write: part of what a read publishes and not part of what a write stores. It is accepted so the object /v1/brand-templates/get answers can be sent straight back, and it comes back as a READ_ONLY_FIELD_IGNORED warning.

cover_imageobject nullable

Ignored on a write: part of what a read publishes and not part of what a write stores. It is accepted so the object /v1/brand-templates/get answers can be sent straight back, and it comes back as a READ_ONLY_FIELD_IGNORED warning.

dry_runboolean

Validate everything and write nothing.

idempotency_keystring

Replays the answer of an identical call for 24 hours.

Response

The call succeeded. This endpoint reports its errors with a real HTTP status, so a 200 always carries status=ok.

status'ok' required

Changes

No recorded changes to this operation across all 1 revision of this API.