Portal Views

Change a view of the client portal

Changes a view of the client portal. The update is partial -- a field the body does not carry keeps its value -- with one exception worth reading twice: report_keys and user_keys REPLACE the stored lists, they do not add to them, and neither may end up empty. A view whose reports are filtered globally by something other than nothing is refused with 409 NOT_EDITABLE_BY_API: this version could not show that filter in the before and after. The confirmation is CONDITIONAL, and it is the PRESENCE of a field that triggers it: a body carrying report_keys, user_keys or send_notification asks for a confirmation even when the values it sends are the ones already stored, and so does any call that would email somebody. Refusals: the same as the creation, plus NOT_EDITABLE_BY_API. if_version is not accepted.

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

post/portal-views/update

Request

  • Base URL: https://api.reportingninja.com/v1
  • URL: https://api.reportingninja.com/v1/portal-views/update
  • Auth: HTTP bearer

Request body

portal_view_keystring required

The view to change, from /v1/portal-views/list.

namestring

Title of the view, 2 to 150 characters.

internal_notesstring

A note for the account's own staff, at most 250 characters. It is never shown in the portal.

brand_template_keystring nullable

A brand template of the account. Explicit null means the default brand of the account.

send_notificationboolean

Email the users that the view is available. Default false. Asking for it makes the call ask for a confirmation.

allow_to_change_date_rangeboolean

Let the users change the period of what they see. Default true.

date_range_option'all' | 'last_monthly_periods'

Which periods the portal offers.

report_keysstring[]

The reports of the view, in the order the portal menu will show them. Between 1 and 50, no repeats, and none of them a template. On an update the list REPLACES the stored one.

user_keysstring[]

The client users who see it. Between 1 and 25, no repeats, and each one a client user of the account: the owner and the administrators are refused. On an update the list REPLACES the stored one.

dry_runboolean

Validate and answer what WOULD happen, without writing anything. Default false.

idempotency_keystring

Makes a retry safe: the answer of the first call is replayed for 24 hours to any later call with the same key and the same body.

confirmation_tokenstring

The token the previous call answered. Sending the same body with it performs the write.

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.