Portal Views

Create a view of the client portal

Creates a view of the client portal: which reports which client users see, in which order, with which brand and with which choice of periods. Both lists are required and neither may be empty. With send_notification the users are emailed, and that email is sent INSIDE the transaction that writes the view: a send that fails takes the write with it and answers 502 NOTIFICATION_FAILED, so nothing is left half done. The confirmation is CONDITIONAL: it is asked for only when the call would actually email somebody. Refusals: 400 VALIDATION_FAILED, UNKNOWN_PARAM, MISSING_REQUIRED_FIELD or INVALID_VALUE (a template among the reports, a staff user among the users, a repeat in either list), 403 WRITE_ACCESS_DISABLED, 404 NOT_FOUND for a report, a user or a brand template, 409 PORTAL_NOT_CONFIGURED when the portal has no subdomain or no email template plus the confirmation and idempotency conflicts, 429 EMAIL_QUOTA_REACHED, 502 NOTIFICATION_FAILED. 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/create

Request

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

Request body

namestring required

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[] required

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[] required

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.