Vizzlo Organizations & Teams

Retrieving organizations

Route

GET /api/v1/orgs/org

Managing organization settings

Route

PATCH /api/v1/orgs/org

This method can be used to update certain organization-specific settings. Currently, the following values can be updated using PATCH calls with query parameters:

Example
curl -u USER:PASSWORD --request PATCH --data default_theme=abc123/orange https://vizzlo.com/api/v1/orgs/abc123

Managing organization user accounts

This section applies to organizations in the Enterprise plan, only!

About managed users

Enterprise organizations allow managing the user accounts for their employees ensuring that all users are administered from a central entity. This includes creating and deleting the accounts which can be done without the need to verify email addresses, etc.

A “managed user“ has the following restrictions compared to an individual user account:

Listing managed users

Route

GET /api/v1/orgs/org/users

Query parameters
Return value

A JSON object with the following fields will be returned:

  1. An object org_subscription that contains basic information about the subscription of the organization:

    • name (string): Name of the subscription.
    • current_member_count (number): Current number of seats taken.
    • max_member_count (number): Maximum number of paid for seats.
    • unlimited (boolean): Specifies if this subscriptions allows for an unlimited number of seats.
    • free (boolean): Specifies if this organization is freely usable without a subscription
    • period_interval (number): Payment period of the subscription.
    • period (string): Payment period unit of the subscription.
    • currency (string): Currency the subscription is paid for.
    • price_per_period (number): Total price of the current subscription per period. Prices are always given in hundredths of the specified currency, ie. $12.50 are specified as 1250 with currency USD.
    • price_per_user_and_period (number): Average price per seats for the user’s payment period.
    • management_url (string): URL where the organization’s management settings interface is available for users.
    • suspended (boolean): Specifies if this subscription is suspended due to a payment issue.

  2. An array users that contains a list of objects, each having the following set of fields:

    • id (string): User ID of the given user.
    • name (string): Full name of the user.
    • email (string): Email address of the user.
    • avatar_url (string): URL which can be used to show a profile picture of the user.
    • role (string): Role of the user within the organization. Can be any of admin, brand_manager, or member.
    • last_seen (string): Timestamp of when the user was last active on Vizzlo as RFC 3339 encoded string.

    If the request yields no results (ie. no user matches the specified filter_role or q), the field users will be ommitted.

Paging headers

If more results for the given query are available, a pair of optional Link headers will be returned (with rel being prev or next) which can be used to page through the result set.

Getting information about a single managed user

Route

GET /api/v1/orgs/org/users/id

Return value

A JSON object representing the user is returned that contains the following fields:

Modifying managed users

Route

PATCH /api/v1/orgs/org/users/id

Request payload

A JSON object containing one or more of the following fields should be sent to this endpoint:

Return value

Upon success, an empty result (HTTP status code 204) is returned.

Deleting managed users

Route

DELETE /api/v1/orgs/org/users/id

Return value

Upon success, an empty result (HTTP status code 204) is returned.

Creating a new managed user

Creating new users in an organization is a two-stage process:

  1. The client sents a plan (“upgrade check”) to create a new managed user account for the organization. The server replies with the necessary details of the operation and—potentially—information about necessary subscription changes.
  2. The client confirms the operation.

In some cases (ie. customers who pay a flat fee regardless of the number of seats), the upgrade check might not be necessary, but will not hurt.

In all other cases, even if the current number of seats being paid for is sufficient, running an upgrade check is mandatory!

Part 1: Checking subscriptions status in preparation of creating a new user

Route

POST /api/v1/orgs/org/users/check

Return value

A JSON object with the following fields will be returned:

If an upgrade of the subscription is necessary, due to the current number of seats in the organization account not being sufficient, the response will contain another field, update_info, that contains the following information:

Part 2: Confirming a potential subscription change to create a new user

Route

POST /api/v1/orgs/org/users

Request payload

A JSON object with the following fields should be sent to this endpoint:

Return value

A JSON object that contains the following fields is returned:

Inviting external users into the organization

If your organization is on an Enterprise plan, the possibility to invite external users might be disabled. In that case, all POST requests of this section will fail with HTTP Status 400.

Listing all open invites for an organization

Any organization member or open invitation will count towards the number of seats the organization is paying for.

Route

GET /api/v1/orgs/org/invites

Return value

Upon success, a JSON object with one field invites (array of objects) is returned. Each object within this array contains these fields:

Inviting external users to an organization

Inviting new members to an organization is a two-stage process:

  1. The client sents a plan (“invite check”) to invite a given list of addresses to the organization. The server replies with the necessary details of the operation and—potentially—information about necessary subscription changes.
  2. The client confirms the operation.

Part 1: Checking subscriptions status in preparation of sending out invitations

Route

POST /api/v1/orgs/org/invites/check

Request payload

A JSON object containing the following fields should be sent to this endpoint:

Return value

A JSON object with the following fields will be returned:

If an upgrade of the subscription is necessary, due to the current number of seats in the organization account not being sufficient for the number of requested invites, the response will contain another field, update_info, that contains the following information:

Part 2: Confirming a subscription change to send out invitations

Route

POST /api/v1/orgs/org/invites

Request payload

A JSON object containing the following fields should be sent to this endpoint:

Return value

Upon success, an empty result is returned.

Deleting an open invite

Route

DELETE /api/v1/orgs/org/invite/id

Re-sending an open invitation

Route

POST /api/v1/orgs/org/invites/id/send

Managing organization members

Listing members of an organization

Route

GET /api/v1/orgs/org/members

Query parameters
Return value

A JSON object with the following fields will be returned:

  1. An object org_subscription that contains basic information about the subscription of the organization:

    • name (string): Name of the subscription.
    • current_member_count (number): Current number of seats taken.
    • max_member_count (number): Maximum number of paid for seats.
    • unlimited (boolean): Specifies if this subscriptions allows for an unlimited number of seats.
    • free (boolean): Specifies if this organization is freely usable without a subscription
    • period_interval (number): Payment period of the subscription.
    • period (string): Payment period unit of the subscription.
    • currency (string): Currency the subscription is paid for.
    • price_per_period (number): Total price of the current subscription per period. Prices are always given in hundredths of the specified currency, ie. $12.50 are specified as 1250 with currency USD.
    • price_per_user_and_period (number): Average price per seats for the user’s payment period.
    • management_url (string): URL where the organization’s management settings interface is available for users.
    • suspended (boolean): Specifies if this subscription is suspended due to a payment issue.

  2. An array members that contains a list of objects, each having the following set of fields:

    • id (string): User ID of the given organization member.
    • name (string): Full name of the user.
    • email (string): Email address of the user.
    • avatar_url (string): URL which can be used to show a profile picture of the user.
    • role (string): Role of the user within the organization. Can be any of admin, brand_manager, or member.
    • last_seen (string): Timestamp of when the user was last active on Vizzlo as RFC 3339 encoded string.
    • managed (boolean): true for managed user accounts, false for individual accounts.

    If the request yields no results (ie. no member matches the specified filter_role or q), the field members will be ommitted.

Paging headers

If more results for the given query are available, the a pair of optional Link headers will be returned (with rel being prev or next) which can be used to page through the result set.

Removing members from an organization

Route

POST /api/v1/orgs/org/members/remove

Query parameters

Managing organization themes

Routes

Managing organization assets

Listing assets

Route

GET /api/v1/orgs/org/assets

Example
curl -u USER:PASSWORD https://vizzlo.com/api/v1/orgs/abc123/assets

Add or updating organization assets

Routes

Deleting assets

DELETE /api/v1/orgs/org/assets/filename

Example
curl -u USER:PASSWORD -X DELETE https://vizzlo.com/api/v1/orgs/abc123/assets/FILENAME

Managing Teams

Listing all teams of an organization

Route

GET /api/v1/orgs/org/teams

Creating a new team

Route

POST /api/v1/orgs/org/teams

Getting information about a specific team

Route

GET /api/v1/orgs/org/team/team

Adding/Removing members of a team

id is the user ID of the member to add to or remove from the team.

Routes

PUT /api/v1/orgs/org/team/team/member/id

DELETE /api/v1/orgs/org/team/team/member/id

Updating information of a specific team

Route

PUT /api/v1/orgs/org/team/team

Deleting a team

Route

DELETE /api/v1/orgs/org/team/team

Verified domains

This section applies to organizations on an Enterprise or Education plan, only. All of these calls require the caller to be an admin of the organization.

Verified domains are the internet domains an organization owns. They are a prerequisite for managing user accounts (managed users must have an email address on a verified domain) and for SAML/SSO just-in-time provisioning.

A domain is verified by publishing a DNS TXT record. Registering a domain returns a record_value that you publish as a TXT record on the domain (the record name is the domain itself). Once published, trigger verification, which performs a live DNS lookup.

Every domain object returned by these endpoints has the following shape:

NameTypeDescription
domainstringThe domain name.
statusstringVerification status: pending, verified, or failed.
record_valuestringThe value to publish as a DNS TXT record, e.g. vizzlo-domain-verification=….
last_checkedstringOptional: Timestamp (RFC 3339) of the last verification attempt.
verified_atstringOptional: Timestamp (RFC 3339) of when the domain was verified.

Listing verified domains

Route

GET /api/v1/orgs/org/domains

Return value

A JSON object with a single field verifications (array of objects), each having the shape described above.

Registering a new domain

Route

POST /api/v1/orgs/org/domains

Request payload
{
  "domain": "example.com"
}

The domain must be a valid domain name and must not be a public/free email provider domain. It also must not already be verified by another organization.

Return value

A single domain object with status set to pending. Publish its record_value as a DNS TXT record on the domain before verifying.

Verifying a domain

Performs a live DNS TXT lookup for the domain and marks it verified if a record matching the domain’s record_value is found, or failed otherwise.

Route

POST /api/v1/orgs/org/domains/domain/verify

Return value

The updated domain object (with status of verified or failed).

Removing a domain

Route

DELETE /api/v1/orgs/org/domains/domain

Return value

No content (HTTP status code 204) upon success.

Organization settings

Beyond the single-value settings that can be changed via PATCH on the organization itself, organizations have a structured settings object that controls policies and layout presets.

Reading the settings is allowed for any member; changing them requires the brand_manager or admin role.

The settings object has the following fields:

NameTypeDescription
layoutsarrayLayout presets (see below).
auto_invite_domain_usersbooleanAutomatically invite users signing up with a verified-domain email address.
auto_update_seat_countbooleanAutomatically grow the subscription’s seat count when needed.
auto_update_seat_count_limitnumberOptional: Upper bound for automatic seat-count growth.
enforce_ssobooleanRequire members to sign in via SSO.
disable_unmanaged_accountsbooleanDisallow individual (unmanaged) accounts for members.
disable_document_storagebooleanDisable cloud document storage for members (offline use only).
disable_public_documentsbooleanForce all documents of the organization to be private.

Each entry in layouts is an object with name (string), width (number, pt), height (number, pt), display_unit (string), and margin (object with top, right, bottom, left in pt).

Reading the settings object

Route

GET /api/v1/orgs/org/settings

Return value

The full settings object as described above.

Replacing the settings object

Replaces the whole settings object with the request payload.

Route

PUT /api/v1/orgs/org/settings

Return value

No content (HTTP status code 204) upon success.

Updating individual settings

Sends a partial settings object; only the keys present are updated.

Route

PATCH /api/v1/orgs/org/settings

Request payload
{
  "enforce_sso": true
}

Unknown keys result in HTTP status code 400.

Return value

No content (HTTP status code 204) upon success.

Appending a layout preset

Appends a single layout preset to the layouts list.

Route

POST /api/v1/orgs/org/settings/layouts

Request payload
{
  "name": "Widescreen",
  "width": 960,
  "height": 540,
  "display_unit": "pt",
  "margin": { "top": 40, "right": 40, "bottom": 40, "left": 40 }
}
Return value

No content (HTTP status code 204) upon success.

Deleting a setting or layout preset

Return value

No content (HTTP status code 204) upon success.

Subscription information

Returns a summary of the organization’s subscription. Requires the admin role.

Route

GET /api/v1/orgs/org/subscription

Return value

A JSON object describing the subscription. It contains the same basic fields as the org_subscription object embedded in the member and managed-user listings (name, current_member_count, max_member_count, unlimited, free, period, period_interval, currency, price_per_period, price_per_user_and_period, management_url, suspended), plus additional fields such as:

If the organization has no billing subscription, an empty result (HTTP status code 204) is returned.

Audit log

Returns the organization’s audit-log events from the last 90 days. Requires the admin role on an Enterprise-plan organization (or operator access).

Route

GET /api/v1/orgs/org/audit-log

Query parameters
Return value

A JSON object with the following fields: