GET /api/v1/orgs/
org
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.curl -u USER:PASSWORD --request PATCH --data default_theme=abc123/orange https://vizzlo.com/api/v1/orgs/abc123
This section applies to organizations in the Enterprise plan, only!
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:
GET /api/v1/orgs/
org
/users
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
)A JSON object with the following fields will be returned:
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 subscriptionperiod_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.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.
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.
GET /api/v1/orgs/
org
/users/id
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.PATCH /api/v1/orgs/
org
/users/id
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.Upon success, an empty result (HTTP status code 204) is returned.
DELETE /api/v1/orgs/
org
/users/id
Upon success, an empty result (HTTP status code 204) is returned.
Creating new users in an organization is a two-stage process:
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!
POST /api/v1/orgs/
org
/users/check
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.POST /api/v1/orgs/
org
/users
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.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.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.
Any organization member or open invitation will count towards the number of seats the organization is paying for.
GET /api/v1/orgs/
org
/invites
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 new members to an organization is a two-stage process:
POST /api/v1/orgs/
org
/invites/check
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.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.POST /api/v1/orgs/
org
/invites
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.Upon success, an empty result is returned.
DELETE /api/v1/orgs/
org
/invite/id
POST /api/v1/orgs/
org
/invites/id
/send
GET /api/v1/orgs/
org
/members
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
)A JSON object with the following fields will be returned:
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 subscriptionperiod_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.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.
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.
POST /api/v1/orgs/
org
/members/remove
id
(string): User ID of the member to remove from the organization.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
GET /api/v1/orgs/
org
/assets
curl -u USER:PASSWORD https://vizzlo.com/api/v1/orgs/abc123/assets
PUT /api/v1/orgs/
org
/assets/filename
POST /api/v1/orgs/
org
/assets
DELETE /api/v1/orgs/
org
/assets/filename
curl -u USER:PASSWORD -X DELETE https://vizzlo.com/api/v1/orgs/abc123/assets/FILENAME
GET /api/v1/orgs/
org
/teams
POST /api/v1/orgs/
org
/teams
GET /api/v1/orgs/
org
/team/team
PUT /api/v1/orgs/
org
/team/team
/member/username
DELETE /api/v1/orgs/
org
/team/team
/member/username
PUT /api/v1/orgs/
org
/team/team
DELETE /api/v1/orgs/
org
/team/team