API Reference

Authentication

Log in

POST /api/login/DoLogin

Authenticate a user and receive a session token. On success the token is in LoginSession.SessionToken and ErrorCode is 0; LoginUser carries the signed-in user's identity, admin flags, and group memberships. On bad credentials the call returns ErrorCode 101 with "Login Failed - Username or Password is invalid." and a null session.

Common use: Start here. Run this once, copy the returned token into the Session token field at the top of the page, and every other sample is ready to send. bolForceLogin is legacy — always send true.

Body parameters

UserIdstring	Required	The user's login name.
UserPasswordstring	Required	The user's PIN / password.
isGuestboolean	Required	Set true only for a guest login; otherwise false.
bolForceLoginboolean	Required	Legacy flag — always send true.

Edit any value, then Send Invalid JSON

Response

Example response

{
  "ErrorCode": 0,
  "ErrorMessage": "",
  "LoginSession": {
    "SessionToken": "AZQZDNKTMYOWZ[ZRJTFCGW[FF",
    "SessionFlag": 0,
    "isGuestSession": false,
    "SessionExpir": "2026-06-24T20:26:01.119+00:00"
  },
  "LoginUser": {
    "ID": "1",
    "LoginName": "admin",
    "FirstName": "Yurbi",
    "LastName": "Admin",
    "isAdmin": true,
    "isSuperAdmin": true
  }
}

Authentication

Check session

POST /api/Session/CheckSession

Confirm a session token is still valid. Use this before a long-running job, or to decide whether you need to log in again.

Common use: Cheap to call. A common pattern: check the session, and if it's expired, silently re-run Log in before continuing.

Requires a session token in the request body.

Body parameters

sessionTokenstring

Required

The session token to validate.

Edit any value, then Send Invalid JSON

Response

Example response

{
  "IsValid": true,
  "ErrorCode": 0,
  "ErrorMessage": null
}

Authentication

Refresh session

POST /api/Session/RefreshSession

Extend a session token's lifetime without a full re-login. Resets the expiration window so an active integration (like an embedded dashboard) keeps working.

Common use: Power a keep-alive: before the token's SessionExpir passes, call this to extend it — the pattern the embedding flow uses to keep an iframe signed in.

Requires a session token in the request body.

Body parameters

sessionTokenstring

Required

The session token to extend.

Edit any value, then Send Invalid JSON

Response

Example response

{
  "ErrorCode": 0,
  "ErrorMessage": ""
}

Authentication

Reset session passport

POST /api/Session/ResetPassport

Force the session's passport (its cached permissions) to rebuild. This is not a routine call — it can log the affected user out. Reach for it when you've made a security or role change and need it to take effect immediately, rather than waiting for the user's next login. Returns { ErrorCode, ErrorMessage }; set withReturn false for just the status.

Common use: After changing a user's group membership or role mid-session, reset their passport so the new permissions apply right away.

Requires a session token in the request body.

Body parameters

sessionTokenstring	Required	The session token whose passport should be rebuilt.
withReturnboolean	Optional	Return the full passport (true) or just status (false). Usually false.

Edit any value, then Send Invalid JSON

Response

Example response

{
  "ErrorCode": 0,
  "ErrorMessage": ""
}

Authentication

Log out

POST /api/login/DoLogout

End a session and release its token. Good hygiene for short-lived sessions created by automation.

Common use: Call this when a script finishes so you don't leave sessions open on the server.

Requires a session token in the request body.

Body parameters

sessionTokenstring

Required

The session token to end.

Edit any value, then Send Invalid JSON

Response

Example response

{
  "ErrorCode": 0,
  "ErrorMessage": null
}

Users

New user template

POST /api/Contact/NewContact

Return a blank user object pre-filled with sensible defaults. The recommended starting point for creating a user — fetch this template, fill in the fields, then post it to SaveContact.

Common use: Avoid guessing the user shape: get the template here, set LoginName / names / Pin, and send it straight to Create or update a user.

Requires a session token in the request body.

Body parameters

sessionTokenstring

Required

A valid admin session token.

Edit any value, then Send Invalid JSON

Response

Example response

{
  "ErrorCode": 0,
  "ID": null,
  "LoginName": "",
  "FirstName": "",
  "LastName": "",
  "AuthType": "PIN",
  "twofa": "none",
  "SecurityGroups": []
}

Users

Create or update a user

POST /api/Contact/SaveContact

Create a new user, or update an existing one. Send the user inside a user object with ID: null to create, or an existing ID to update. Requires an admin session token.

Common use: Recommended flow: call NewContact first to get a template, fill it in, then post it here. Leave SecurityGroups empty and manage membership with the Group endpoints (AddUser / RemoveUser). After creating the user, you can seed their Favorites with FavDash / ContactFavLibraryReportItem so they see content on first login.

Requires a session token in the request body.

Body parameters

sessionTokenstring	Required	A valid admin session token.
user.FirstNamestring	Required	First name.
user.LastNamestring	Required	Last name.
user.LoginNamestring	Required	The user's login name.
user.Pinstring	Required	The user's password.
user.AuthTypestring	Required	"PIN" unless using Windows AD authentication.
user.timezoneinteger	Required	Numeric timezone offset, e.g. -5.
user.timezonenamestring	Required	Timezone name, e.g. "Eastern Standard Time".
user.twofastring	Required	"none" unless configuring 2FA.
user.SecurityGroupsarray	Required	Leave empty []; manage membership via the Group endpoints.
withpinboolean	Required	Send true when the password is supplied in user.Pin.

Edit any value, then Send Invalid JSON

Response

Example response

{
  "ErrorCode": 0,
  "ErrorMessage": "",
  "ID": "639046099446490166",
  "LoginName": "jsmith405",
  "FirstName": "Jane",
  "LastName": "Smith",
  "isAdmin": false
}

Users

Update my profile

POST /api/Contact/SaveMYContact

Self-service profile update: the signed-in user edits their own first name, last name, email, and description. Unlike SaveContact (an admin editing anyone), this acts on the caller's own record. Read-modify-write — start from the current user object, change the fields, and post the whole thing back. Returns the saved user with ErrorCode 0.

Common use: Power a 'My Profile' screen in an embedded app so users can maintain their own name and email without admin involvement.

Requires a session token in the request body.

Body parameters

sessionTokenstring	Required	The signed-in user's session token.
userobject	Required	The user's own record with updated fields.
withpinboolean	Optional	Whether the payload includes a PIN/password change. Usually false.

Edit any value, then Send Invalid JSON

Response

Example response

{
  "ErrorCode": 0,
  "ErrorMessage": "",
  "ID": "1001",
  "FirstName": "Jordan",
  "LastName": "Lee",
  "EmailAddress": "jordan@acme.com"
}

Users

List users

POST /api/Contact/GetContactList

Return every user on the instance with profile fields, role flags (isAdmin, isSuperAdmin, isAgent, …), and their SecurityGroups. Find a user's ID here before updating them with SaveContact or adding them to a group.

Common use: Look up an existing user by login name, or confirm whether a user already exists before creating one.

Requires a session token in the request body.

Body parameters

sessionTokenstring

Required

A valid admin session token.

Edit any value, then Send Invalid JSON

Response

Example response

[
  {
    "ID": "1",
    "LoginName": "admin",
    "FirstName": "Yurbi",
    "LastName": "Admin",
    "EmailAddress": "admin@acme.com",
    "AuthType": "PIN",
    "isAdmin": true,
    "isSuperAdmin": true,
    "SecurityGroups": [
      {
        "GroupId": "1",
        "GroupName": "Administrators"
      }
    ]
  }
]

Groups & Roles

List groups

POST /api/Group/GetAllSecurityGroups

Return every security group, each with its GroupId, name, description, role assignments, and Membership (the users in it). Use the GroupId when adding or removing users, or when assigning a group to an AppShield policy.

Common use: Find a group's ID before calling AddUser / RemoveUser, or confirm a group exists before creating one.

Requires a session token in the request body.

Body parameters

sessionTokenstring

Required

A valid admin session token.

Edit any value, then Send Invalid JSON

Response

Example response

[
  {
    "GroupId": "1",
    "GroupName": "Administrators",
    "GroupDescription": "Yurbi Admins",
    "GroupStatus": 0,
    "GroupRoles": [],
    "Membership": [
      {
        "ID": "638764569153988232",
        "LoginName": "pabbly",
        "isAdmin": false
      }
    ]
  }
]

Groups & Roles

New group template

POST /api/Group/NewSecurityGroup

Return a blank security-group object with defaults. The recommended starting point for creating a group — fetch this, set the name, then post it to SaveSecurityGroup.

Common use: Get the correct group shape instead of guessing it, then fill in GroupName and save.

Requires a session token in the request body.

Body parameters

sessionTokenstring

Required

A valid admin session token.

Edit any value, then Send Invalid JSON

Response

Example response

{
  "GroupId": null,
  "GroupName": "",
  "GroupDescription": "",
  "GroupStatus": 0,
  "AllUsers": [],
  "AllRoles": []
}

Groups & Roles

Create or update a group

POST /api/Group/SaveSecurityGroup

Create a security group, or update an existing one. Send GroupId: null to create. For a new group, leave AllUsers and AllRoles empty and add members with AddUser. Updating an existing group this way is not recommended — use AddUser / RemoveUser for membership.

Common use: Create a tenant's group once, then manage who's in it (and their role) through the AddUser / RemoveUser endpoints.

Requires a session token in the request body.

Body parameters

sessionTokenstring	Required	A valid admin session token.
group.GroupNamestring	Required	Name of the security group.
group.GroupDescriptionstring	Required	Group description.
group.GroupStatusinteger	Required	Legacy field — set to 0.
group.AllUsersarray	Required	Leave [] for a new group; populate via AddUser.
group.AllRolesarray	Required	Leave [] for a new group; populate via AddUser.

Edit any value, then Send Invalid JSON

Response

Example response

{
  "ErrorCode": 0,
  "ErrorMessage": "",
  "GroupId": "16",
  "GroupName": "Acme — Customer A"
}

Groups & Roles

Add user to group

POST /api/Group/AddUser

Add a user to a security group with a specific role. Roles: 1 Admin (full access), 2 View (read-only), 3 Modify (edit), 4 Delete, 5 Builder (consumes a Builder license); 0 is None. Returns a plain-text result; errors include "GroupId/ContactId/RoleId is required.", "Invalid session.", and "Permission Denied."

Common use: The recommended way to grant access: pick the group, the user (ContactId from List users), and the role to assign.

Requires a session token in the request body.

Body parameters

sessionTokenstring	Required	A valid admin session token.
GroupIdstring	Required	The group's ID.
ContactIdstring	Required	The user's ID (from List users).
RoleIdstring	Required	Role to assign: "1" Admin, "2" View, "3" Modify, "4" Delete, "5" Builder.

Edit any value, then Send Invalid JSON

Response

Example response

"User Added Successfully."

Groups & Roles

Remove user from group

POST /api/Group/RemoveUser

Remove a user from a security group. Returns a plain-text result — "User Removed Successfully." on success; errors include "GroupId/ContactId is required.", "Invalid session.", and "Permission Denied."

Common use: Revoke a user's access to a group's resources without deleting the user.

Requires a session token in the request body.

Body parameters

sessionTokenstring	Required	A valid admin session token.
GroupIdstring	Required	The group's ID.
ContactIdstring	Required	The user's ID.

Edit any value, then Send Invalid JSON

Response

Example response

"User Removed Successfully."

Groups & Roles

List roles

POST /api/Contact/GetRolesList

Return the available roles and their IDs. A role controls what a user can do with a group's resources: 0 None, 1 Admin, 2 View, 3 Modify, 4 Delete, 5 Builder (consumes a Builder license).

Common use: Reference the role IDs you pass as RoleId when adding a user to a group with AddUser.

Requires a session token in the request body.

Body parameters

sessionTokenstring

Required

A valid admin session token.

Edit any value, then Send Invalid JSON

Response

Example response

[
  {
    "RoleId": "0",
    "RoleName": "None",
    "RoleDescription": "No access to resources within this group"
  },
  {
    "RoleId": "1",
    "RoleName": "Admin",
    "RoleDescription": "Full access to resources assigned to this group"
  },
  {
    "RoleId": "2",
    "RoleName": "View",
    "RoleDescription": "Read-only access to resources within this group"
  },
  {
    "RoleId": "5",
    "RoleName": "Builder",
    "RoleDescription": "Consumes a Builder license type"
  }
]

AppShield

New policy template

POST /api/AppShield/NewPolicy

Return a blank AppShield policy object with defaults. This does not create anything — it gives you the structure to fill in and post to SaveAppShieldPolicy.

Common use: The recommended starting point for creating a policy: get the template, set a name, attach groups/users, then save.

Requires a session token in the request body.

Body parameters

sessionTokenstring

Required

A valid admin session token.

Edit any value, then Send Invalid JSON

Response

Example response

{
  "id": null,
  "Name": "New AppShield Policy",
  "Description": "AppShield Policy Created 2016-06-06T21:17:40-04:00",
  "Constraints": [],
  "Groups": null,
  "Users": null,
  "isActive": false,
  "ErrorCode": 0,
  "ErrorMessage": null
}

AppShield

Create or update a policy

POST /api/AppShield/SaveAppShieldPolicy

Create a new AppShield policy or update an existing one. Send the policy object (from NewPolicy) with id: null to create, or an existing id to update. With isDeepSave: true, the groups and users arrays are applied to the policy in the same call. Returns the saved policy with ErrorCode / ErrorMessage populated.

Common use: Provision a full data-security policy in one call — create it and attach its groups and users together. For quick single-group changes on an existing policy, AddGroup / RemoveGrp are lighter.

Requires a session token in the request body.

Body parameters

sessionTokenstring	Required	A valid admin session token.
policyobject	Required	The policy object (from NewPolicy). id: null creates; existing id updates.
isDeepSaveboolean	Required	When true, also apply the groups and users arrays to the policy.
groupsarray	Optional	List of group IDs to assign to the policy (with isDeepSave).
usersarray	Optional	List of user IDs to assign to the policy (with isDeepSave).

Edit any value, then Send Invalid JSON

Response

Example response

{
  "id": "636129983109455587",
  "Name": "New AppShield Policy",
  "ErrorCode": "0",
  "ErrorMessage": "",
  "isActive": false,
  "Groups": [
    {
      "GroupId": "16"
    },
    {
      "GroupId": "11"
    }
  ],
  "Users": [
    {
      "ID": "635055077867776462"
    },
    {
      "ID": "635176414815914719"
    }
  ]
}

AppShield

Add group to policy

POST /api/AppShield/AddGroup

Attach a security group to an AppShield data-security policy. Requires a valid admin session; the policy and group must already exist. Returns plain text: Success, or Group is already a member if it was already attached. Errors: "Group not found.", "Policy not found.", "Invalid Session.", "GroupId is required.", "policyid is required.", "Permission Denied."

Common use: Wire a tenant's group into the policy that scopes their data — the integration step that makes AppShield enforce isolation for that group.

Requires a session token in the request body.

Body parameters

sessionTokenstring	Required	A valid admin session token.
policyidstring	Required	ID of the AppShield policy. Must exist.
groupidstring	Required	ID of the security group to add. Must exist.

Edit any value, then Send Invalid JSON

Response

Example response

"Success"

AppShield

Remove group from policy

POST /api/AppShield/RemoveGrp

Detach a security group from an AppShield data-security policy. Requires a valid admin session; the policy and group must exist. Returns plain text: Success, or No Changes if the group was not attached to the policy. Errors: "Group not found.", "Policy not found.", "Invalid Session.", "GroupId is required.", "policyid is required.", "Permission Denied."

Common use: Stop a policy from applying to a group — e.g. when offboarding a tenant or restructuring access.

Requires a session token in the request body.

Body parameters

sessionTokenstring	Required	A valid admin session token.
policyidstring	Required	ID of the AppShield policy. Must exist.
groupidstring	Required	ID of the security group to remove. Must exist.

Edit any value, then Send Invalid JSON

Response

Example response

"Success"

Apps & Servers

List apps

POST /api/App/GetApplicationList

Return every application (app) defined on the instance, with its ID and name. Use the IDs when granting a user access in SaveContact.

Common use: Fetch this first when creating users, so you can grant access to the right apps by ID instead of guessing.

Requires a session token in the request body.

Body parameters

sessionTokenstring

Required

A valid session token.

Edit any value, then Send Invalid JSON

Response

Example response

[
  {
    "ID": "52",
    "Name": "Yurbi v10"
  },
  {
    "ID": "61",
    "Name": "Sales Reporting"
  }
]

Apps & Servers

List registered servers

POST /api/RegServers/GetAdminRegisteredServers

Return the registered server (data source) records an admin can manage — including database host, name, and the linked report module. This is the record you edit, then save back with SaveRegSrv.

Common use: Always read-modify-write: fetch the record here, change only the fields you need, then post the whole object to Update an app.

Requires a session token in the request body.

Body parameters

sessionTokenstring

Required

A valid admin session token.

Edit any value, then Send Invalid JSON

Response

Example response

[
  {
    "ID": "1",
    "DatabaseServer": "db.internal",
    "AppName": "Audit App",
    "ReportModule": {
      "ID": "52",
      "Name": "Yurbi v10"
    }
  }
]

Apps & Servers

Create an AnyDB module

POST /api/RegServers/InsertAnyDbModule

Create an AnyDB application module — the container a data source attaches to. Anything a partner registers is an AnyDB module. This is step one of provisioning a data source: create the module here (it returns an ID and a ModuleType like anydb1004), then register the database server against it with SaveRegSrv.

Common use: Spin up a new app/data-source slot for a tenant. Pair with SaveRegSrv to attach their database connection.

Requires a session token in the request body.

Body parameters

sessionTokenstring	Required	A valid admin session token.
appnamestring	Required	Display name for the new module.
descriptionstring	Required	Description of the module.

Edit any value, then Send Invalid JSON

Response

Example response

{
  "ErrorCode": 0,
  "ErrorMessage": null,
  "ID": "1004",
  "Name": "Acme Sales DB",
  "RPT": "Yurbi.RptModules.AnyDB",
  "ModuleType": "anydb1004",
  "ClassPath": "AnyDB",
  "ProductCode": "ANYDB",
  "isAnyDbApp": true
}

Apps & Servers

Register a data source

POST /api/RegServers/SaveRegSrv

Register (or update) the database server behind an AnyDB module — the connection Yurbi reports against. This is the second step of data-source provisioning: after InsertAnyDbModule creates the module, assemble a regserver (connection details + the module as ReportModule) and save it here. Send bsaveasanydb false for the standard path. Get a blank template from NewRegServer, and validate first with TestConnection. Returns the full saved server with a new ID and ErrorCode 0 (the password is blanked out on return).

Common use: Onboard a tenant's database: create the module, test the connection, then register it here so their reports and dashboards have data. Driver/platform casing matters — "POSTGRESQL"/"postgresql", "MSSQL"/"mssql".

Requires a session token in the request body.

Body parameters

sessionTokenstring	Required	A valid admin session token.
regserverobject	Required	The full server definition: ReportModule (from InsertAnyDbModule), DisplayName, DatabaseDriver, DatabasePlatform, DatabaseServer, DatabaseLogin, DatabasePassword, DatabaseName, DatabaseOwner, ConnectionTimeout, CommandTimeout, TimeZone, DaylightSavings.
bsaveasanydbboolean	Optional	Save as an AnyDB registration. Send false for the standard path (the module is already AnyDB).

Edit any value, then Send Invalid JSON

Response

Example response

{
  "ErrorCode": 0,
  "ErrorMessage": "",
  "ID": "178226433293",
  "ReportModule": {
    "ID": "1005",
    "ModuleType": "anydb1005",
    "isAnyDbApp": true
  },
  "ModuleType": "anydb1005",
  "DisplayName": "Acme Sales DB",
  "DatabaseServer": "db.acme.com",
  "DatabaseLogin": "reporting",
  "DatabasePassword": "",
  "DatabaseDriver": "POSTGRESQL",
  "DatabasePlatform": "postgresql"
}

Apps & Servers

Test a connection

POST /api/RegServers/TestConnection

Validate a database connection before saving it. Send the assembled regserver object; returns the plain string "Passed" on success, or "Test Failed - …" with the reason. The driver/platform values must match Yurbi's expected casing (e.g. DatabaseDriver "POSTGRESQL", DatabasePlatform "postgresql"; "MSSQL"/"mssql" for SQL Server).

Common use: Call this before SaveRegSrv so you only persist a connection that actually works — surface the failure message to the user if it doesn't.

Requires a session token in the request body.

Body parameters

sessionTokenstring	Required	A valid admin session token.
regserverobject	Required	The server definition to test (same shape SaveRegSrv expects).

Edit any value, then Send Invalid JSON

Response

Example response

"Passed"

Library

List items in a folder

POST /api/library/GetListByFolderID

Return every library item (report or dashboard) inside a folder that the user can view. Each item has its id, name, type, and the user's permission flags — same item shape as SearchReports. Empty if nothing matches.

Common use: Browse a folder (use GetAllLibraryTree to find folder IDs) to get a report or dashboard id — the value you run or embed. itemtype: 0 Dashboard, 1 grid, 2 chart, 3 KPI text, 4 KPI gauge, 6 pie, 7 combo.

Requires a session token in the request body.

Body parameters

sessionTokenstring	Required	A valid session token.
LibraryIDstring	Required	The folder ID to list items from (from GetAllLibraryTree).

Edit any value, then Send Invalid JSON

Response

Example response

[
  {
    "id": 1738259678,
    "ReportName": "# of Tickets by Channel",
    "AppDisplayName": "Service Desk Tickets",
    "folderid": 2,
    "itemtype": 2,
    "isEmbedable": true,
    "isUserView": true,
    "error_code": 0,
    "error_message": null
  }
]

Library

Get library tree

POST /api/library/GetAllLibraryTree

Return the full folder tree of the library as nested nodes. Each node has an id, text (folder name), a children array, and the current user's permission flags. libtype marks the branch: 1 Public Library, 2 My Library, 0 Favorites (included when includefav is true).

Common use: Render a folder picker, or walk the whole structure. Pair it with GetListByFolderID to list the reports and dashboards inside a chosen folder.

Requires a session token in the request body.

Body parameters

sessionTokenstring	Required	A valid session token.
includefavboolean	Required	Include the user's Favorites branch (libtype 0).

Edit any value, then Send Invalid JSON

Response

Example response

[
  {
    "rootnode": {
      "id": 0,
      "text": "Public Library",
      "libtype": 1,
      "isUserAdmin": true,
      "children": [
        {
          "id": 2,
          "text": "Service Desk Reports",
          "level": "0",
          "libtype": 1,
          "children": [
            {
              "id": 3,
              "text": "Target Reports",
              "level": "2:3",
              "libtype": 1,
              "children": []
            }
          ]
        }
      ]
    }
  }
]

Library

Search reports & dashboards

POST /api/library/SearchReports

Return every library item (report or dashboard) whose name matches a search string and that the user can view. Each item includes its id, name, type, folder, permission flags, and itemtype. Empty if nothing matches.

Common use: Find an item by name across the whole library to get its id — the value you run with GetReportMetadataById or embed. itemtype: 0 Dashboard, 1 grid, 2 chart, 3 KPI text, 4 KPI gauge, 6 pie, 7 combo.

Requires a session token in the request body.

Body parameters

sessionTokenstring	Required	A valid session token.
searchstringstring	Required	Text to match against item names.

Edit any value, then Send Invalid JSON

Response

Example response

[
  {
    "id": 1738259678,
    "ReportName": "# of Tickets by Channel",
    "ReportType": "Service Data",
    "AppDisplayName": "Service Desk Tickets",
    "Application": "Service Desk Tickets",
    "folderid": 2,
    "itemtype": 2,
    "isUserView": true,
    "isUserModify": true,
    "isEmbedable": true,
    "isPublicView": false,
    "isFav": false,
    "error_code": 0,
    "error_message": null
  }
]

Library

Search dashboards

POST /api/Dashboard/SearchDashboardList

Return a lightweight list of dashboards whose name matches a search string and that the user can view — id, name, description, favorite and personal flags. Empty if nothing matches.

Common use: Quickly resolve a dashboard id by name — the value you pass as i= in an embed.html?t=d URL.

Requires a session token in the request body.

Body parameters

sessionTokenstring	Required	A valid session token.
searchstring	Required	Text to match against dashboard names.

Edit any value, then Send Invalid JSON

Response

Example response

[
  {
    "id": 4,
    "name": "Service Desk Status",
    "descr": "Service Desk Status",
    "weight": 0,
    "isFav": 0,
    "isPersonal": 0
  },
  {
    "id": 18,
    "name": "Sales Overview",
    "descr": "Sales",
    "weight": 2,
    "isFav": 1,
    "isPersonal": 1
  }
]

Library

Favorite a dashboard

POST /api/library/ContactFavLibraryDashboardItem

Add a dashboard to a user's Favorites. As an admin, pass the target user's ID as cnt_id to set it on their behalf; omit cnt_id to apply to your own session. Note the dashboard calls use dsh_id / cnt_id (the report favorites calls use ReportId / ContactId).

Common use: Provisioning win: after creating a user, favorite the dashboards you want them to have. A favorited dashboard loads automatically when they log in, and any others appear in the dashboard selector on the dashboard page — so they see content immediately, with no setup on their part.

Requires a session token in the request body.

Body parameters

sessionTokenstring	Required	A valid session token (admin, if setting it for another user).
dsh_idstring	Required	The dashboard's ID (from SearchDashboardList).
cnt_idstring	Optional	The target user's ID. Omit to favorite for your own session.

Edit any value, then Send Invalid JSON

Response

Example response

Library

Unfavorite a dashboard

POST /api/library/ContactUnFavLibraryDashboardItem

Remove a dashboard from a user's Favorites. Pass cnt_id (admin) to act on another user, or omit it to act on your own session. Uses dsh_id / cnt_id.

Common use: The reverse of favoriting — use it to retire a dashboard from a user's set. Common pattern: when you publish a replacement dashboard, walk your users, unfavorite the old one and favorite the new so everyone moves over without lifting a finger. Note there isn't currently an admin call to read another user's favorites, so apply the swap across your full user list rather than checking each user individually first.

Requires a session token in the request body.

Body parameters

sessionTokenstring	Required	A valid session token (admin, if acting for another user).
dsh_idstring	Required	The dashboard's ID.
cnt_idstring	Optional	The target user's ID. Omit to act on your own session.

Edit any value, then Send Invalid JSON

Response

Example response

Library

Favorite a report

POST /api/library/ContactFavLibraryReportItem

Add a report to a user's Favorites. As an admin you can favorite on another user's behalf by passing their ContactId; omit it and it applies to your own session.

Common use: Seed a newly provisioned user's Favorites. When they open the Library and view their Favorites, the reports are already there — no action needed on their part.

Requires a session token in the request body.

Body parameters

sessionTokenstring	Required	A valid session token (admin, if setting it for another user).
ReportIdstring	Required	The report's ID (from the Library calls).
ContactIdstring	Optional	The target user's ID. Omit to favorite for your own session.

Edit any value, then Send Invalid JSON

Response

Example response

Library

Unfavorite a report

POST /api/library/ContactUnFavLibraryReportItem

Remove a report from a user's Favorites. Pass a ContactId (admin) to act on another user, or omit it to act on your own session.

Common use: The reverse of favoriting a report. Use it in the same swap pattern as dashboards — retire an old report from users' Favorites when you roll out a replacement.

Requires a session token in the request body.

Body parameters

sessionTokenstring	Required	A valid session token (admin, if acting for another user).
ReportIdstring	Required	The report's ID.
ContactIdstring	Optional	The target user's ID. Omit to act on your own session.

Edit any value, then Send Invalid JSON

Response

Example response

Reports

Get report metadata

POST /api/Report/GetReportMetadataById

Load a report's full definition (the Reportobj) by ID. The response is a large object whose main content is under Report — fields, chart formatting, sort order — alongside a Prompts array. This is step one of running a report: get the metadata, optionally set prompt values, then call GetReportData. Pass the whole object through unchanged.

Common use: First call when displaying a report programmatically. If the report has prompts, its Prompts array feeds GetFieldValues and ReplacePromptCollection.

Requires a session token in the request body.

Body parameters

sessionTokenstring	Required	A valid session token.
ReportIDstring	Required	The ID of the report to load (from the Library calls).
isTargetboolean	Optional	Whether this is a drill-down target report. Defaults to false.
PreviousMetadataobject	Optional	Prior metadata for chained calls; null on first load.
Criteriaobject	Optional	Pre-applied criteria; null on first load.

Edit any value, then Send Invalid JSON

Response

Example response

{
  "Report": {
    "ReportID": "1738259678",
    "Reportname": "# of Tickets by Channel",
    "ModuleName": "Service Desk Tickets",
    "ErrorCode": 0,
    "ErrorMessage": "",
    "FieldList": [
      {
        "fieldindex": 1,
        "ReportFieldName": "Customer",
        "Fieldtype": "cha",
        "Criteria": []
      },
      {
        "fieldindex": 2,
        "ReportFieldName": "Ticket ID",
        "Fieldtype": "num",
        "Formula": "COUNT(?)",
        "Criteria": []
      }
    ]
  },
  "Prompts": []
}

Reports

Get prompt values

POST /api/Report/GetFieldValues

For a prompted report, return the list of selectable values for one prompt as { key, val } pairs. Pass the report metadata (Reportobj from GetReportMetadataById) and the prompt you're populating (one element of Reportobj.Prompts with PromptField.Criteria[0].bgetvalues set to true). A single result whose key is "1001" means the value list is too large — treat the prompt as free text/search.

Common use: Build a dropdown for a prompt in your own embed UI before running the report. key is what you show; val is what you submit.

Requires a session token in the request body.

Body parameters

sessionTokenstring	Required	A valid session token.
Reportobjobject	Required	The report metadata object (from GetReportMetadataById).
Promptobject	Required	The prompt to fetch values for (one of Reportobj.Prompts).

Edit any value, then Send Invalid JSON

Response

Example response

[
  {
    "key": "Email",
    "val": "Email"
  },
  {
    "key": "Phone Call",
    "val": "Phone Call"
  },
  {
    "key": "Social Media",
    "val": "Social Media"
  }
]

Reports

Set a report prompt

POST /api/Report/ReplacePrompt

Apply a prompt value to a report and get back an updated Reportobj with the criteria injected in the format the engine expects. Call once per prompt before GetReportData.

Common use: When a report has prompts (e.g. a date range or region), set each value here — pass the whole report object plus the prompt you're filling — then run the report.

Requires a session token in the request body.

Body parameters

sessionTokenstring	Required	A valid session token.
Reportobjobject	Required	The report metadata object (from GetReportMetadataById).
Promptobject	Required	The prompt to set, typically one element of Reportobj.Prompts with its value filled in.

Edit any value, then Send Invalid JSON

Response

Example response

{
  "Report": {
    "ReportID": "1738259678",
    "ErrorCode": 0,
    "ErrorMessage": ""
  },
  "Prompts": [
    {
      "Name": "Region",
      "Value": "West"
    }
  ]
}

Reports

Set prompts (batch)

POST /api/Report/ReplacePromptCollection

Apply several prompt values at once and get back an updated Reportobj ready to run. This is the batch version of ReplacePrompt — the embed flow uses it when a set of prompt values is supplied up front. Each element of Prompts is a prompt with its value (and optional isSkipped) set.

Common use: Set all of a report's prompts in one call, then run it with GetReportData — fewer round-trips than replacing prompts individually.

Requires a session token in the request body.

Body parameters

sessionTokenstring	Required	A valid session token.
Reportobjobject	Required	The report metadata object (from GetReportMetadataById).
Promptsarray	Required	The full Prompts array with values/isSkipped applied.

Edit any value, then Send Invalid JSON

Response

Example response

{
  "Report": {
    "ReportID": "1738259678",
    "ErrorCode": 0,
    "ErrorMessage": ""
  },
  "Prompts": []
}

Reports

Run a report

POST /api/Report/GetReportData

Execute a report and return its data. Pass the Reportobj from GetReportMetadataById (after applying any prompts). The rows are in Data (one object per row, keyed by field), with Columns describing each column. String cells may contain drill-down markup; ContainsDrilldown flags that. The full metadata is echoed back under ReportMetadata.

Common use: The final step of the report workflow: metadata → set prompts → run. Use Data + Columns to render a table or chart in your own UI.

Requires a session token in the request body.

Body parameters

sessionTokenstring	Required	A valid session token.
Reportobjobject	Required	The prepared report metadata object.
IsDrillDownboolean	Optional	Whether this is a drill-down run. Defaults to false.
DrillDownCriteriaobject	Optional	Criteria for a drill-down; null otherwise.
TargetReportobjobject	Optional	Target report for a drill-down; null otherwise.

Edit any value, then Send Invalid JSON

Response

Example response

{
  "ErrorCode": 0,
  "ErrorMessage": "",
  "HasError": false,
  "ReportID": "1738259678",
  "Columns": [
    {
      "headerText": "# of Tickets",
      "key": "Ticket_ID",
      "dataType": "number",
      "yurbitype": "num"
    },
    {
      "headerText": "Channel",
      "key": "Channel",
      "dataType": "string",
      "yurbitype": "ddn"
    }
  ],
  "Data": [
    {
      "Ticket_ID": 1704,
      "Channel": "Social Media"
    },
    {
      "Ticket_ID": 905,
      "Channel": "WebForm"
    }
  ],
  "ContainsDrilldown": true,
  "IsFromCache": false
}

Email (SMTP)

Get SMTP settings

POST /api/SMTP/GetSMTP

Return the instance's outbound email (SMTP) configuration — host, port, from address, security, and credentials (the password is returned blank). SMTPRequiredSecurity and SMTPEnableSSL are the strings "True" / "False". This is the record you edit and post back with SaveSMTP, and it carries the SMTPId needed by DeleteSMTP.

Common use: Read-modify-write: fetch the current settings, change what you need, save them back.

Requires a session token in the request body.

Body parameters

sessionTokenstring

Required

A valid admin session token.

Edit any value, then Send Invalid JSON

Response

Example response

{
  "ErrorCode": 0,
  "ErrorMessage": null,
  "SMTPId": "178114386851",
  "SMTPHost": "smtp.acme.com",
  "SMTPPort": "587",
  "SMTPFromAddress": "notifications@acme.com",
  "SMTPRequiredSecurity": "True",
  "SMTPUserName": "notifications@acme.com",
  "SMTPPassword": "",
  "SMTPEnableSSL": "True"
}

Email (SMTP)

Save SMTP settings

POST /api/SMTP/SaveSMTP

Save the outbound email (SMTP) configuration. Send the full smtp object — fetch the current one with GetSMTP first, change what you need, and post it back. Send SMTPRequiredSecurity and SMTPEnableSSL as the strings "True" / "False".

Common use: Point the instance at a new mail relay: pull the settings, update host/port/credentials, save. Scheduled reports and alerts use this server.

Requires a session token in the request body.

Body parameters

sessionTokenstring	Required	A valid admin session token.
smtpobject	Required	The SMTP settings: SMTPHost, SMTPPort, SMTPFromAddress, SMTPRequiredSecurity, SMTPUserName, SMTPPassword, SMTPEnableSSL.

Edit any value, then Send Invalid JSON

Response

Example response

{
  "ErrorCode": 0,
  "ErrorMessage": null,
  "SMTPId": "178114386851"
}

Email (SMTP)

Delete SMTP settings

POST /api/SMTP/DeleteSMTP

Remove the configured SMTP settings. Pass the smtp object returned by GetSMTP (it carries the SMTPId that identifies the record to delete).

Common use: Clear email config before reconfiguring from scratch. Call GetSMTP first — if there's no SMTPId, nothing is configured and there's nothing to delete.

Requires a session token in the request body.

Body parameters

sessionTokenstring	Required	A valid admin session token.
smtpobject	Required	The SMTP record to delete, including its SMTPId (from GetSMTP).

Edit any value, then Send Invalid JSON

Response

Example response

{
  "ErrorCode": 0,
  "ErrorMessage": null
}

Instance Settings

Get instance settings

POST /api/AppSettings/GetAppSettings

Return the instance-wide settings object — session timeout, the query row cap (MaxRecords), SSO flags, tenant mode, scheduler mode, and more. Note many boolean settings come back as the strings "True" / "False", while numeric settings (e.g. MaxRecords, SESSION_TIMEOUT) are integers. This is the record you edit and post back with SaveAppSettings.

Common use: Always read-modify-write: SaveAppSettings replaces the whole record, so fetch it here first and change only the fields you need.

Requires a session token in the request body.

Body parameters

sessionTokenstring

Required

A valid admin session token.

Edit any value, then Send Invalid JSON

Response

Example response

{
  "SESSION_TIMEOUT": 1200,
  "PROMPT_VALUES_LIMIT": 10000,
  "MaxRecords": 100000,
  "SchedulerMode": 1,
  "SSOEnabled": "True",
  "SSOHeader": "ssoTest",
  "TENANT_MODE_ENABLED": "True",
  "Productname": "Yurbi"
}

Instance Settings

Save instance settings

POST /api/AppSettings/SaveAppSettings

Save the instance-wide settings. The API replaces the full record, so fetch it with GetAppSettings first, change the fields you need, and post the complete object back inside appsettings. Keep the original types — numeric fields as numbers, the "True"/"False" string flags as strings.

Common use: Raise the global row cap or session timeout: pull settings, change MaxRecords / SESSION_TIMEOUT, save.

Requires a session token in the request body.

Body parameters

sessionTokenstring	Required	A valid admin session token.
appsettingsobject	Required	The full settings object to save (from GetAppSettings, modified).

Edit any value, then Send Invalid JSON

Response

Example response

{
  "ErrorCode": 0,
  "ErrorMessage": ""
}

Instance Settings

Get audit types

POST /api/Audit/GetAuditTypes

Return the list of audit event types and their retention. Each entry has an ID, a numeric type, a symbol (the event name, e.g. "Login Success"), recorded, and retention (days). This is the same array you edit and post back to SaveAuditTypes.

Common use: Fetch the current audit types before changing retention, so you save back the complete, modified list.

Requires a session token in the request body.

Body parameters

sessionTokenstring

Required

A valid admin session token.

Edit any value, then Send Invalid JSON

Response

Example response

[
  {
    "ID": 1,
    "type": 0,
    "symbol": "Login Success",
    "recorded": -1,
    "retention": 30,
    "options": ""
  },
  {
    "ID": 2,
    "type": 1,
    "symbol": "Login Failure",
    "recorded": -1,
    "retention": 120,
    "options": ""
  }
]

Instance Settings

Save audit types

POST /api/Audit/SaveAuditTypes

Save audit event types and their retention. Send the full list in AuditTypeList — fetch it with GetAuditTypes first, adjust retention (days) on the entries you want, and post the complete array back.

Common use: Apply a retention policy: pull the list, set retention per type, save the whole list back.

Requires a session token in the request body.

Body parameters

sessionTokenstring	Required	A valid admin session token.
AuditTypeListarray	Required	The full list of audit type objects (from GetAuditTypes), modified.

Edit any value, then Send Invalid JSON

Response

Example response

{
  "ErrorCode": 0,
  "ErrorMessage": ""
}

Licensing

Refresh licenses

POST /api/LicenseManager/RefreshInstalledLicenses

Tell the instance to re-read its installed licenses. Run this after a license change so the server picks up new entitlements without a restart.

Common use: Part of an automated deploy: after applying a new license, call this so seat counts and feature flags take effect immediately.

Requires a session token in the request body.

Body parameters

sessionTokenstring

Required

A valid admin session token.

Edit any value, then Send Invalid JSON

Response

Example response

{
  "Refreshed": true,
  "ErrorCode": 0,
  "ErrorMessage": null
}

Licensing

Get installation ID

POST /api/LicenseManager/GetInstallationID

Return this instance's unique installation ID. This identifier ties the running instance to its license.

Common use: A safe, read-only health check that an instance is up and authenticating — and the value you reference when working with licensing.

Requires a session token in the request body.

Body parameters

sessionTokenstring

Required

A valid admin session token.

Edit any value, then Send Invalid JSON

Response

Example response

{
  "InstallationID": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "ErrorCode": 0,
  "ErrorMessage": null
}