Skip to content

Organizations API

Organizations

An organization represents any organization account on giosg system. An organization consists of a number of users with their own user accounts. A user always belongs to exactly one organization.

Please note that despite its name a "organization" in this context means any organization or group. It can even consists of only one user.

An organization object contains the following attributes. Note that the contact information is public.

Attribute Type Editable Description
id UUID read-only Unique identifier for this organization
name string required The name of the organization. Maximum length is 64.
email string optional Contact email address, or null. Maximum length is 64.
phone string optional Contact phone number, or null. Maximum length is 16.
street string optional Contact street address, or null. Maximum length is 128.
postal_code string optional Contact address postal code, or null. Maximum length is 8.
city string optional Contact address city, or null. Maximum length is 32.
country string optional Country as a two-letter, lowercase ISO 3166-1 code, or null. Maximum length is 2.
business_id string optional Business ID of the organization, if any, or null. Maximum length is 256.
script_tag string read-only The script tag for the organization.
is_online boolean read-only Whether the organization is currently online, i.e. at least one user from the organization is online. See users for more information.
is_present boolean read-only Whether the organization is currently present, i.e. at least one user from the organization is present. See users for more information.
max_rules_count integer / null read-only Number of rules the organization can create. NOTE: Will be moved to somewhere else in the near future!
created_at datetime read-only When this organization account was created.
updated_at datetime read-only When organization details were changed last time.

Retrieve organization details

Get a single organization object by its ID.

GET https://service.giosg.com/api/v5/orgs/<organization_id>

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization

Update organization details

You may update some of the attributes of an organization, if you have permissions to do so.

PUT https://service.giosg.com/api/v5/orgs/<organization_id>

PATCH https://service.giosg.com/api/v5/orgs/<organization_id>

When using PUT you need to provide an object as a request payload that contains all the required attributes of the organization. When using PATCH, you may omit those attributes that you do not want to change.

This endpoint returns:

  • 200 if the request was successful
  • 400 if required attributes are missing from the request
  • 400 if the request payload is in wrong format
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have settings permission

Organization overviews

Usually you may want to know some aggregated numbers of a organization. A organization overview describes the current status of the organization.

An organization overview has the following attributes:

Attribute Type Description
present_visitor_count integer The total number of unique visitors currently present.
pending_chat_count integer The total number of pending chats.

Retrieve an overview of an organization

You can get the overview of your organization:

GET /api/v5/orgs/<organization_id>/overview

The overview attributes have the following meanings:

  • present_visitor_count describes the number of visitors present across all your organization rooms.
  • pending_chat_count describes the number of pending chats across all your organization rooms.

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have settings permission

Organization's Features

Features are different kind of services (e.g. rooms, rules) which giosg provides. A feature object contains following attributes:

Attribute Type Editable Description
id string read-only Unique identifier for this feature. In this case the name is the unique identifier.

List current features of organization

You may want to list all features which are currently enabled for a organization. Expired / disabled features cannot be listed.

GET https://service.giosg.com/api/v5/orgs/<organization_id>/features

Parameter Type Default Description
ordering ordering id Ordering of results with option id (with or without -)

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization

Organization Settings

Every organization has its settings. These settings contain organization specific definitions how the system should work for them. Organization can have only one settings for them.

Attribute Type Editable Description
id UUID read-only Unique identifier for this organization settings.
organization_id UUID read-only ID of the organization.
organization object read-only The organization object.
ui_version string read-only Giosg UI version code.
default_ui_language string required Default UI language in console.
timezone string required Organization time zone. See Time zones API for supported values.
is_private_chat_history_enabled boolean required Whether only users with reports permission may see the organization's chat history or everyone
is_strict_password_policy_enabled boolean required Whether strict password policy is enabled or not.
is_automatic_chat_links_enabled boolean required Whether links in chat dialogs are clickable or not.
is_variable_signing_required boolean required Do visitor variables have to be signed with key.
is_login_credentials_preservation_enabled boolean required Are user login credentials saved, i.e. users do not have to login for every session.
login_credentials_preservation_duration integer required For how long login credentials are saved. This value is in seconds.
password_expiration_days integer / null optional Password expiration interval in days. Must be at least 1 day. If null, passwords will not expire.
custom_cdn_url string / null read-only Organizations own CDN. If null static files will be loaded through Giosg CDN.
created_at datetime read-only When organization settings were created.
updated_at datetime read-only When organization settings were changed last time.

Retrieve organization settings

Get organization's settings by:

GET https://service.giosg.com/api/v5/orgs/<organization_id>/settings

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization

Update organization settings

You may update some of the attributes of organization settings, if you have permissions to do so.

PUT https://service.giosg.com/api/v5/orgs/<organization_id>/settings

PATCH https://service.giosg.com/api/v5/orgs/<organization_id>/settings

When using PUT you need to provide an object as a request payload that contains all the required attributes of the organization settings. When using PATCH, you may omit those attributes that you do not want to change.

This endpoint returns:

  • 200 if the request was successful
  • 400 if required attributes are missing from the request
  • 400 if the request payload is in wrong format
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have settings permission

Organization's Customership

Information about your organization's customership. The customership object contains information about usage limits of certain features and status of your current subscription (trial account or not).

Attribute Type Editable Description
organization_id UUID read-only ID of the organization.
organization object read-only The organization object.
is_trial boolean read-only Whether organization has a trial subscription or not.
max_users_count integer / null read-only How many users organization can have once.
max_online_users_count integer / null read-only How many users can organization have chatting once.
max_rules_count integer / null read-only How many created rules organization can have once.
max_scheduled_email_reports_count integer / null read-only How many scheduled reports organization can have once.
updated_at datetime read-only When organization's customership was updated last time.

Retrieve details of organization's customership

Get details of organization's customership:

GET https://service.giosg.com/api/v5/orgs/<organization_id>/customership

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 404 if organization does not have created subscription.