Introduction OEM API

This page contains the documentation for the Veeting Rooms OEM API version 1. It provides ways to integrate Veeting Rooms into an existing billing system. The APIs is only available to White Label customers.

All data that is sent to the Veeting Rooms server has to be packaged in a standardized JSON data request body described below. Similarly, all response object from the server come in an equally standardized JSON data response body.

Every application that consumes these API's has to first obtain an API key from Veeting Rooms. Such an API key must not be used for multiple applications, every application should use its own API key.

Standard data bodies

Request parameter definitions

Every API that sends data to the service must wrap the data in the following data structure:

Field name Data type Description
apiKey String The unique API key of this application, mandatory
localeCode String Local code, optional, default is “en” for English
data Object A JSON object containing data parameters for the specific request

Example:

{
	"apiKey": "YOUR UNIQUE API KEY",
    "localeCode": "de",
	"data": {
	}
}


Response parameter definitions

Every API request is answered by a generic response object. The response object contains three fields: a response code, a response message and data field containing JSON encoded, API specific data.

Field name Data type Description
responseCode String A response code indicating a success or error, see table below for details
responseMessage String A localized response message that can be displayed to the user in case of an error. Mandatory if responseCode < 0. The message can be expected in the language passed in as localecode in the request, or if not available, in English (“en”)
data Object A JSON object containing response data or error objects in case of responseCode < 0

Response code Description
-99 Unknown error
-10 Account already exists
-4 Data not valid
-3 Not allowed
-2 Session key not valid
-1 API key not valid
0 Success

Example:

{
	"responseCode" : 0,
	"responseMessage": "Success",
	"data": {
	}
}

Default configuration

Configure these fields in order to run the examples below.

Create Account

Description

This API allows the billing system to create an account with Veeting Rooms.


End-point definition

URL https://www.veeting.com/oem-api/v1/create-account
HTTP Method POST
Requires session key? No

Request parameter definitions

Field name Data type Mandatory? Description
id String Yes The unique OEM account ID. This OEM account ID usually corresponds with an ID in the OEMs own database.
accountType String Yes One of "trial", "meetingOrganizer", "payAsYouGo", etc. "trial" will result in a 14 days account
validForNumberOfMonth Integer No The number of month the subscription is valid, for "meetingOrganizer" account type, otherwise ignored. Default is 0
validUntil Integer No Instead of to the "validForNumberOfMonth" parameter one can send a Unix timestamp UTC in milliseconds to define the validity period. If both parameters are provided the "validUntil" parameter will be ignored. Only valid for "meetingOrganizer" account type.
numberOfMeetingOrganizers Integer No The number of meetings organizers the account is payed for. Mandatory for "meetingOrganizer" account type, otherwise ignored. Default is 1.
numberOfMeetings Integer No The number of meetings the account holder has purchased. Mandatory for "payAsYouGo" account type, otherwise ignored. Default is 0.
oemUserId String No A unique OEM user ID. This OEM user ID usually corresponds with an ID in the OEMs own database.
firstName String Yes The first name of the account owner / user of the account. More users can be added later.
lastName String Yes The last name of the account owner / user of the account. More users can be added later.
email String Yes The email address of the account owner / user of the account. This will be the user's id in the system. More users can be added later.
sendPassword Boolean No Indicates if the system should send a welcome email with the password or not. Default is true. To be used together with the Authenticate User API
comment String No A free text field
branding Branding Object No A branding object (see below) to style the meeting room of this account

Request parameter definitions

Field name Data type Mandatory? Description
enabled Boolean No Indicates if branding is enabled or not
logoUrl String No A URL pointing to an image file. Must be hosted on HTTPS
cssUrl String No A URL pointing to a CSS file. Must be hosted on HTTPS
primaryColor String No A color as HEX, RGB or RGBA CSS string
secondaryColor String No A color as HEX, RGB or RGBA CSS string

Response parameter definitions

The system does not send extra data with the response.


Example

Code:

Results:

Update Account

Description

This API the billing system to update an account.

End-point definition

URL https://www.veeting.com/oem-api/v1/update-account
HTTP Method POST
Requires session key? No

Branding object definition

Field name Data type Mandatory? Description
id String Yes The OEM account ID
accountId String No Alternatively, if no OEM account ID is present, one can use Veeting's internal account ID
accountType String No One of "trial", "meetingOrganizer", "payAsYouGo", etc. "trial" will result in a 14 days account
numberOfMonthToAdd Integer No The number of payed month to add, for "meetingOrganizer" account types, otherwise ignored. Default is 0
validUntil Integer No Instead of to the "numberOfMonthToAdd" parameter one can send a Unix timestamp UTC in milliseconds to define the validity period. If both parameters are provided the "validUntil" parameter will be ignored. Only valid for "meetingOrganizer" account type.
numberOfMeetingOrganizersToAdd Integer No The number of meetings organizers to add to an account. Mandatory for "meetingOrganizer" account type, otherwise ignored. Values < 0 will reduce the number of meeting organizers.
numberOfMeetingsToAdd Integer No The number of meetings that should be added to the account account, for "payAsYouGo" account type, otherwise ignored. Negative numbers will remove meetings. The total number of meetings will always be >= 0
comment String No A free text field
branding Branding Object No A branding object (see above) to style the meeting room of this account

Response parameter definitions

The system does not send extra data with the response.


Example

Code:

Results:

Get Account

Description

This API retrieves account information. The account can be found by either the unique Account id or the email address of a member of this account.

End-point definition

URL https://www.veeting.com/oem-api/v1/get-account
HTTP Method POST
Requires session key? No


Request parameter definitions

Field name Data type Mandatory? Description
id String No The OEM account ID
accountId String No Alternatively, if no OEM account ID is present, one can use Veeting's internal account ID
userId String No As the third option, it is also possible to search for an account by the admin's email address

Response parameter definitions

Field name Data type Description
accountId String The internal account ID from Veeting
oemAccountId String The OEM account ID
validUntil Integer Expiry date of the account, as a Unix timestamp UTC in milliseconds.
name String The account name
company String The company name
telephoneNumber String The telephone number
address String The address
country String The country
numberOfMeetings Integer The number of meetings available for this account
numberOfMeetingOrganizers Integer The number of meeting organizers that this account can define
type String The account type
comment String The free text field

Example

Code:

Results:

Delete Account

Description

This API deletes an account with Veeting Rooms. It will also delete all associated data such as meetings, documents, users, etc.

End-point definition

URL https://www.veeting.com/oem-api/v1/delete-account
HTTP Method POST
Requires session key? No


Request parameter definitions

Field name Data type Mandatory? Description
id String Yes The OEM account ID
accountId String No Alternatively, if no OEM account ID is present, one can use Veeting's internal account ID

Response parameter definitions

The system does not send extra data with the response.


Example

Code:

Results:

Create User

Description

This API creates a user with Veeting Rooms. Only one user per email address is allowed, the email address will be the user id.

End-point definition

URL https://www.veeting.com/oem-api/v1/create-user
HTTP Method POST
Requires session key? No

Request parameter definitions

Field name Data type Mandatory? Description
accountId String Yes The unique account ID with which this user is associated with
firstName String Yes The users first name
lastName String No The users last name
email String Yes A valid email address. One email address can only be associated with one user account.
oemUserId String No A unique OEM user ID. This OEM user ID usually corresponds with an ID in the OEMs own database.
sendPassword Boolean No Indicates if the system should send a welcome email with the password or not. Default is true. To be used together with the Authenticate User API

Response parameter definitions

The system does not send extra data with the response.


Example

Code:

Results:

Update User

Description

This API updates user information with Veeting Rooms. Only one user per email address is allowed, the email address is the user id.

End-point definition

URL https://www.veeting.com/oem-api/v1/update-user
HTTP Method POST
Requires session key? No

Request parameter definitions

Field name Data type Mandatory? Description
userId String Yes The current email address of the user
oemUserId String No A unique OEM user ID as an alternative for the userId. This OEM user ID usually corresponds with an ID in the OEMs own database.
firstName String No The users first name
lastName String No The users last name
email String No A valid email address. One email address can only be associated with one user account.

Response parameter definitions

The system does not send extra data with the response.


Example

Code:

Results:

Delete User

Description

This API deletes a user with Veeting Rooms. It will also delete all associated data such as meetings, documents, etc.

End-point definition

URL https://www.veeting.com/oem-api/v1/delete-user
HTTP Method POST
Requires session key? No

Request parameter definitions

Field name Data type Mandatory? Description
userId String No The current email address of the user
oemUserId String No A unique OEM user ID. This OEM user ID usually corresponds with an ID in the OEMs own database.

Response parameter definitions

The system does not send extra data with the response.


Example

Code:

Results:

Get User

Description

This API retrieves user information. The user can be found by the email address.

End-point definition

URL https://www.veeting.com/oem-api/v1/get-user
HTTP Method POST
Requires session key? No


Request parameter definitions

Field name Data type Mandatory? Description
userId String Yes An email address of a user

Response parameter definitions

Field name Data type Description
firstName String The first name
lastName String The last name
email String The email address
preferredLanguage String The preferred language of the user
timezone String The timezone of the user.

Example

Code:

Results:

Schedule meeting

Description

This API allows to schedule a Veeting on behalf of a user.

End-point definition

URL https://www.veeting.com/oem-api/v1/schedule-meeting
HTTP Method POST
Requires session key? Yes

Request parameter definitions

Field name Data type Mandatory? Description
userId String Yes The email address of the user for whom you schedule the meeting. The user needs to have an account with this email address.
topic String Yes Meeting topic
agenda String No Meeting agenda
startTimestamp Integer Yes Unix time stamp, Milliseconds since 1.1.1970 UTC
duration Integer Yes Meeting duration in minutes, minimum 15, maximum 7200.
participants Array of strings No List of email addresses, comma separated. Requires session key, maximum number of email addresses is 10
meetingType String Yes "video" or "audio"
meetingStyle String Yes "standard", "offTheRecord", "boardroom" or "classroom"
meetingPassword String No An optional password for the meeting.
sendMeetingInvitation Boolean No Set to True if the system should send out meeting invitations to the participants. Default is False
permission String No Permission ID to define the permissions for this meeting.
omitMeetingHooks Boolean No Omit the meeting hooks when running this API call. Default is "false"

Response parameter definitions

Field name Data type Description
Meeting object Object See definition of meeting object in “List meetings”.

Example

Code:

Results:

Update meeting

Description

This API allows to update a Veeting on behalf of a user. The admin token of the meeting is required.

End-point definition

URL https://www.veeting.com/oem-api/v1/update-meeting
HTTP Method POST
Requires session key? Yes

Request parameter definitions

Field name Data type Mandatory? Description
userId String Yes The email address of the user for whom you schedule the meeting. The user needs to have an account with this email address.
adminToken String Yes Meeting topic
topic String Yes Meeting topic
agenda String No Meeting agenda
startTimestamp Integer Yes Unix time stamp, Milliseconds since 1.1.1970 UTC
duration Integer Yes Meeting duration in minutes, minimum 15, maximum 7200.
participants Array of strings No List of email addresses, comma separated. Requires session key, maximum number of email addresses is 10
meetingType String Yes “video” or “audio”
meetingStyle String Yes "standard", "offTheRecord", "boardroom" or "classroom"
meetingPassword String No An optional password for the meeting.
sendMeetingInvitation Boolean No Set to True if the system should send out meeting invitations to the participants. Default is False
omitMeetingHooks Boolean No Omit the meeting hooks when running this API call. Default is "false"

Response parameter definitions

Field name Data type Description
Meeting object Object See definition of meeting object in “List meetings”.

Example

Code:

Results:

Delete meeting on behalf of a user.

Description

This API allows to delete a Veeting. The admin token of the meeting is required.

End-point definition

URL https://www.veeting.com/oem-api/v1/delete-meeting
HTTP Method POST
Requires session key? Yes

Request parameter definitions

Field name Data type Mandatory? Description
userId String Yes The email address of the user for whom you schedule the meeting. The user needs to have an account with this email address.
adminToken String Yes Meeting topic
omitMeetingHooks Boolean No Omit the meeting hooks when running this API call. Default is "false"

Response parameter definitions

Field name Data type Description
success Boolean "True" if meeting was deleted, otherwise "false".

Example

Code:

Results:

List meetings of a user

Description

This API allows anyone with a valid session key to retrieve the upcoming and ongoing meetings associated with the appropriate account.

End-point definition

URL https://www.veeting.com/oem-api/v1/list-meetings
HTTP Method POST
Requires session key? YES

Request parameter definitions

Field name Data type Mandatory? Description
userId String Yes The email address of the user for whom you schedule the meeting. The user needs to have an account with this email address.

Response parameter definitions

Field name Data type Description
Meetings List A list of meeting objects. See table below for the definition of the meeting object.

Meeting data structure definition

Field name Data type Description
meetingId String Unique meeting id
adminToken String Unique admin token, currently useless for API users
topic String Meeting topic
agenda String Meeting agenda
startTimestamp Integer Milliseconds since 1.1.1970, UTC
duration Integer Meeting duration in minutes
participants Array of strings List of email addresses, comma separated.
meetingType String “video” or “audio”
meetingStyle String e.g. “standard”, “offTheRecord”, “boardRoom”, etc
meetingOrganizer String Full name of meeting Organizer, only filled in if the meeting was created by a logged in user, i.e. a valid security token
hasStarted Boolean Indicates if the meeting has started already
isOpen Boolean Indicates if the meeting room for this meeting is available. The meeting room opens 15 minutes before the meeting starts.
isClosed Boolean Indicates if the meeting is closed already
maxStorageReached Boolean Currently useless for API users
permission String The meeting permission id. See Permission APIs for details.

Example

Code:

Results:

Authenticate User

Description

This API has to be implemented on servers of the API user. It will be used by Veeting Rooms to authenticate a user on each login attempt. The Veeting Rooms service will first check its internal database if such a user exists and if found, will call this API to verify the credentials provided by the user.

The API call will be made from the Veeting Rooms server.

End-point definition

URL To be defined by the API user
HTTP Method POST
Requires session key? No

Request parameter definitions

Field name Data type Mandatory? Description
apiKey String Yes An API Key provided by the OEM partner. Default is "MY-API-KEY".
localeCode String Yes The two letter locale code. Can be used to internationalize response messages. Default is "en".
email String Yes The email address of the user
password String Yes The password of the user

Response parameter definitions

The system does not send extra data with the response. If the login was not successful the Veeting Rooms UI will show the message returned in the “responseMessage” field of the standard response body defined above.


Example

curl -X POST --data '{"apiKey": "MY-API-KEY", "localeCode": "en", "data": { "email" : "me@example.com", "password": "secret"}}' --header "Content-Type: application/json" https://www.example.com/authenticate-user

API Key Request

Get in touch if you are interested in optaining an API key from us. At the moment we are focusing on implementation partners with existing, high value products and services.

API Documentation