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:

  • default_theme: Specifies the default theme to use when a user that is members of this organization creates a new document. This setting shall be provided as string that identifies the theme—potentially including the organization’s id.
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:

  • Managed users cannot create Vizzlo Professional subscriptions
  • Managed users cannot be a member of multiple organizations
  • Managed users need to have an email address that belongs to a verified domain name of the organization
  • Managed users cannot change their email address using the self-service functionality
  • Managed users cannot delete their account using the self-service functionality

Listing managed users

Route

GET /api/v1/orgs/org/users

Query parameters
  • q (string): Optional: Only return members whose email address or name matches the given string.
  • filter_role (string): Optional: Only return users that match the given role in the organization. Needs to be any of admin, brand_manager, or member.
  • offset (number): Optional: Offset of the first search result matching the query to return. (Default: 0)
  • limit (number): Optional: Maximum number of search results to return. This value cannot exceed 100. (Default: 100)
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:

  • 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.

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:

  • email (string): New email address of the given user. The email address MUST be part of the verified domains of the organization for this request to succeed.
  • name (string): New name of the given user.
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:

  • update_needed (boolean): Is a subscription update necessary for this operation? See update_info below for more details about the necessary update.
  • unlimited (boolean): The organization account is unlimited in the number of seats which can be used.
  • new_member_count (number): Number of new members that would be created when confirming this operation.
  • max_member_count (number): Current maximum number of seats this organization is configured for.
  • subscription_revision (number): Numerical revision of the current set of members the organization has. This is to ensure that any confirmed subscription change transaction is really an atomic operation. To confirm this operation, you need to send this exact revision for the confirmation API call.

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:

  • additional_seats (number): Number of additional seats which would be added to the account.
  • total_seats (number): Total number of seats the subscription being used after the update.
  • max_member_count (number): Maximum number of seats which can be used after the update.
  • update_cost (number): Cost of the planned subscription update. This is the amount of the pro-rated invoice which will be generated.
  • currency (string): Currency, the subscription update will be charged in.
  • subscription_cost (number): New total subscription cost.
  • billing_cycle_every (number): Interval of billing cycle which is used for the subscription.
  • billing_cycle_unit (string): Unit of billing cycle which is used for the subscription.
  • next_billing_at (string): Next time the subscription will be fully billed.
  • subscription_status (string): Status the subscription will be in after the update.

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:

  • email (string): Email address of the given user. The email address MUST be part of the verified domains of the organization for this request to succeed.
  • name (string): Name of the given user.
  • role (string): Optional: Role of the user within the organization. Can be any of admin, brand_manager, or member (default).
  • teams (array of strings): Optional: List of team IDs to add this new user to right away.
  • subscription_revision (number): Numerical revision which was returned to you as part of the request in part 1.
Return value

A JSON object that contains the following fields is returned:

  • user_id (string): User ID of the newly created user account.
  • initial_password (string): The initial password of the newly created user account.

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:

  • id (string): Identifier for this invitation.
  • email (string): Email address of the person invited.
  • invited_at (string): Timestamp (ISO 8601 encoded) of when the person was invited.
  • sent_at (string): Timestamp (ISO 8601 encoded) of when the invitation was last (re-)sent.
  • inviter_username (string): User ID of the person who triggered this invitation.
  • inviter_name (string): Full name of the person who triggered this invitation.
  • inviter_avatar_url (string): URL of the avatar image of the person who triggered this invitation.

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:

  • emails (array of strings): List of the email addresses that you want to invite as members of the organization.
Return value

A JSON object with the following fields will be returned:

  • update_needed (boolean): Is a subscription update necessary for this operation? See update_info below for more details about the necessary update.
  • unlimited (boolean): The organization account is unlimited in the number of seats which can be used.
  • new_member_count (number): Number of new members that will be invited when confirming this operation.
  • max_member_count (number): Current maximum number of seats this organization is configured for.
  • addresses_to_really_add (array of strings): List of email addresses which will be added if confirming the operation. Already existing members or invites will be filtered from this list.
  • subscription_revision (number): Numerical revision of the current set of members the organization has. This is to ensure that any confirmed subscription change transaction is really an atomic operation. To confirm this operation, you need to send this exact revision for the confirmation API call.

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:

  • additional_seats (number): Number of additional seats which would be added to the account.
  • total_seats (number): Total number of seats the subscription being used after the update.
  • max_member_count (number): Maximum number of seats which can be used after the update.
  • update_cost (number): Cost of the planned subscription update. This is the amount of the pro-rated invoice which will be generated.
  • currency (string): Currency, the subscription update will be charged in.
  • subscription_cost (number): New total subscription cost.
  • billing_cycle_every (number): Interval of billing cycle which is used for the subscription.
  • billing_cycle_unit (string): Unit of billing cycle which is used for the subscription.
  • next_billing_at (string): Next time the subscription will be fully billed.
  • subscription_status (string): Status the subscription will be in after the update.

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:

  • emails (array of strings): List of the email addresses that you want to invite as members of the organization.
  • subscription_revision (number): Numerical revision which was returned to you as part of the request in part 1.
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
  • filter_role (string): Optional: Only return members that match the given role. Needs to be any of admin, brand_manager, or member.
  • q (string): Optional: Only return members whose email address or name matches the given string.
  • limit (number): Optional: Maximum number of search results to return. This value cannot exceed 100. (Default: 100)
  • offset (number): Optional: Offset of the first search result matching the query to return. (Default: 0)
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
  • id (string): User ID of the member to remove from the organization.

Managing organization themes

Routes
  • GET /api/v1/orgs/org/themes
  • GET /api/v1/orgs/org/themes/theme
  • PUT /api/v1/orgs/org/themes/theme
  • DELETE /api/v1/orgs/org/themes/theme

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
  • PUT /api/v1/orgs/org/assets/filename
  • POST /api/v1/orgs/org/assets

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

Routes

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

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

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