The Administration API is used to provision and manage accounts that will store your customers data as well as manage app connection information. Each account is isolated from one another unless access is granted via sharing settings or setting the datashare flag when creating the account.

A Postman collection is available to use this API at the bottom of this page

This API is NOT used to access the chart of accounts of a company or any company data like a balance sheet. It is only used to manage accounts to store your customers data. See API for accessing your customers data.


Accounts

Creating Accounts

You can create a new account via a POST request (using basic auth) to https://admin.myintranetapps.com/app/api.php with an "Account-Key" header set to "XXXX"  (where XXXX is your account key) that contains a JSON body that looks like:

{
  "name": "new client name",
  "package_id": "9",
  "active": "1",
  "email_admin": "newaccountadmin@email.com",
  "password": "newadminpassword",
  "subdomain": "example",
  "type": "standard",
  "domain": "www.redirect.com",
  "datashare": "1"
}
JSON

Parameter

Definition

name
required

The human readable name of the company you are adding an account for, typically the legal name. This is displayed to the user.

package_id
optional

Specifies an identifier for a collection of account settings called a `package`. If no package_id is set, your default package will be used.

active
required

A flag that indicates you want this account to be active on creation. Either 0 or 1.

email_admin
required

Address that indicates the email we should use for communication to the manager of the account, reasons for sending an email might include sending system service/maintenance notices or requests to re-authorize an integration if access has been revoked for some reason.

password
required

Used to allow the default "admin" account to login with the given password, leave this blank to disable admin login.

subdomain
required

Required as each new account is accessible under its own subdomain of myintranetapps.com, the text you specify here will be used to create a domain like "my-company.myintranetapps.com".

Must be 50 characters or less and use alphanumeric characters and dashes only.

If the subdomain is already in use by another account, the request will fail with a 409 response:

{
    "status_code": 409,
    "message": "Subdomain already in use"
}
CODE

In this case, the request should be retried with a new subdomain.

type
required

Indicates the account type which is either "reseller" or "standard", for your purposes you should leave this as “standard”.

domain
optional

An optional field used when you want to add a custom (DNS CNAME) domain name to the system instead of using the myintranetapps.com domain, you shouldn't need this field and can leave blank.

If you have not previously setup a DNS CNAME entry for your custom domain do not provide a value in this field or the account creation will not succeed.

datashare
optional

Indicates that you want the account setup with permissions already active to allow full sharing with the master account.

If you want the account to share data with you, be sure to set it to "1"for your use case.

The response you get back will be in JSON and look like:

{
  "status_code":200,
  "message":"Account successfully created",
  "account_key":"<<<UNIQUE_KEY>>>",
  "subdomain":"example",
  "account_domain":"example.myintranetapps.com",
  "name":"new client name",
  "admin_email":"newaccountadmin@email.com"
}
JSON

You should save the unique key for future reference in your system, you will use this unique account key whenever you need to interact with this account in the future

If something goes wrong while processing your POST request ("status_code" value will differ from 200), the "message" property will contain an error description.

Error responses

HTTP response status

Error message

Description

401

Missing username/API Key from Basic Auth header

401

Missing 'Account-Key' request header

403

Invalid or expired API Key

If API Key used

403

Invalid API Key

If API Key used

401

Missing password from Basic Auth header

If username/password used

403

Invalid username/account key

If username/password used

403

Invalid password

If username/password used

403

Operation is not permitted - missing scope: "admin.account.create"

Please check your API Key contains required scope.

403

Parent account key must be used when making a 'create account' request. Child account key given. Please check that correct key is used in Account-Key header

400

Missing or empty required fields: {fields list}

Missing one or more required fields: 'type', 'name', 'active', 'subdomain', 'email_admin', 'password'

403

Invalid subdomain, must be 50 characters or less and use alphanumeric characters and dashes only

409

Subdomain already in use

409

Custom domain already in use

409

Invalid package_id

409

Invalid environment

409

Account creation failure - accounts

This is internal error during account creation.

409

Account creation failure - users

This is internal error during user creation

409

Account creation failure - default package

This is internal error during package creation

Listing Accounts

You can list all accounts previously created via a POST request (using basic auth) to https://admin.myintranetapps.com/app/api.php with an "Account-Key" header set to "XXXX"  (where XXXX is your account key) that contains a JSON body that looks like:

{
  "action": "list_accounts"
}
JSON

The response you get back will be in JSON and look like:

{
  "status_code":200,
  "message": "Accounts list successfully generated",
  "accounts":[
    {
      "name": "General Company Ltd",
      "key": "5a70d8fcd44aa9.76285892",
      "subdomain": "generalco",
      "domain":  "",
      "package_id":  "93",
      "email_admin": "cfo@example.com"
    }
  ]
}
JSON

If something goes wrong while processing your POST request ("status_code" value will differ from 200), the "message" property will contain an error description.

Error responses

HTTP response status

Error message

Description

401

Missing username/API Key from Basic Auth header

401

Missing 'Account-Key' request header

403

Invalid or expired API Key

If API Key used

403

Invalid API Key

If API Key used

401

Missing password from Basic Auth header

If username/password used

403

Invalid username/account key

If username/password used

403

Invalid password

If username/password used

403

Operation is not permitted - missing scope: "admin.account.list"

Please check your API Key contains required scope.

409

Account list failure

This is internal error when tried to get list of account

Updating Accounts

You can update an account previously created via a POST request (using basic auth) to https://admin.myintranetapps.com/app/api.php with an "Account-Key" header set to "XXXX"  (where XXXX is your account key) that contains a JSON body that looks like:

{
  "action": "update_account",
  "account_key": "5a70d8fcd44aa9.76285892",
  "package_id": "9",
  "active": "1",
  "email_admin": "newaccountadmin@email.com"
}
JSON

Property called "account_key" must be set to the value of the account key of the account to update. Following properties of the JSON posted are optional: "package_id", "active", "email_admin", but there must be at least one property set to perform an update.

The response you get back will be in JSON and look like:

{
  "status_code":200,
  "message":"Account successfully updated",
  "account_key": "5a70d8fcd44aa9.76285892"
}
JSON

If something goes wrong while processing your POST request ("status_code" value will differ from 200), the "message" property will contain an error description.

Error responses

HTTP response status

Error message

Description

401

Missing username/API Key from Basic Auth header

401

Missing 'Account-Key' request header

403

Invalid or expired API Key

If API Key used

403

Invalid API Key

If API Key used

401

Missing password from Basic Auth header

If username/password used

403

Invalid username/account key

If username/password used

403

Invalid password

If username/password used

403

Operation is not permitted - missing scope: "admin.account.update"

Please check your API Key contains required scope.

400

No account_key is set for update

400

No fields to update. Allowed fields: package_id, active, email_admin

409

Account did not updated

This is internal error when during update account


Connections

Connection Health

To get a list of all app connections and their current status create a GET request (using basic auth) to https://admin.myintranetapps.com/app/api.php?action=connection_health with an "Account-Key" header set to "XXXX"  (where XXXX is your account key).

The response you get back will be in JSON and look like:

{
    "status_code": 200,
    "message": "Connection health generated",
    "count": 2,
	"connections": [
		{
			"integration": "quickbooks",
			"property": "Sandbox Company_US_1",
			"expires": "2021-11-05 19:02:23",
			"created": "2019-06-26 22:39:47",
			"status": "INACTIVE",
			"environment": "sandbox",
			"last_sync": "2021-10-12 16:20:38",
			"last_sync_error": null,
			"last_sync_error_count": null,
			"last_sync_error_message": null,
			"active": false,
			"name": "Dev Startup",
			"account_key": "5aa2e93c0ea374.82746293",
			"in_error_state": false
		},
		{
            "integration": "quickbooks",
            "property": "Boss Widgets Inc",
            "expires": "2021-11-05 19:02:23",
            "created": "2021-11-05 18:02:23",
            "status": "ACTIVE",
            "environment": "production",
            "last_sync": "2022-05-02 04:05:59",
            "last_sync_error": "2022-01-20 04:05:50",
            "last_sync_error_count": "0",
            "last_sync_error_message": "warning: failed to make request to quickbooks, code:200",
            "active": true,
            "name": "testborrower",
            "account_key": "6170841d16cc84.92698341",
            "in_error_state": false
        }
	]
}
JSON

The response contains the following fields:

Field

Definition

integration

The unique identifying key for a particular app

property

Some apps manage access to multiple properties/accounts via a given set of credentials. For many apps this field will be blank but for those that support accessing different properties the name of the property will be the value of this field.

expires

The date and time the current access token expires. Access tokens are refreshed automatically

created

The date and time this app connection was created in UTC

status

The current status of the app connection. One of:
ACTIVE - fully connected
PENDING - some apps can be pending if the connection process is started but not completed
INACTIVE - app was once connected and is now disconnected
UNKNOWN - status is unknown due to some error

environment

The app connection environment, typically this is either “production” or “sandbox” depending on the account settings

last_sync

The date and time of the last full synchronization for this app in UTC

last_sync_error

The date and time of the last full synchronization that resulted in an error in UTC

last_sync_error_count

The number of sequential errors that have occurred when performing full synchronization, this counter resets to 0 when a successful synchronization occurs. Automatic synchronization will pause when 10 attempts at synchronization fail.

last_sync_error_message

The technical error message indicating the reason for an error

active

Whether or not this app connection is an active connection (true) or has been disconnected (false).

Deprecated - use ‘status' instead

name

The name of the account associated with the connection

account_key

The account key associated with the connection

in_error_state

Whether or not the connection is currently considered in error, 0 or 1

integration_platform

The platform an app is categorized into (accounting, commerce, banking, billing)

If something goes wrong while processing your GET request ("status_code" value will differ from 200), the "message" property will contain an error description.

Error responses

HTTP response status

Error message

Description

401

Missing username/API Key from Basic Auth header

401

Missing 'Account-Key' request header

403

Invalid or expired API Key

If API Key used

403

Invalid API Key

If API Key used

401

Missing password from Basic Auth header

If username/password used

403

Invalid username/account key

If username/password used

403

Invalid password

If username/password used

403

Operation is not permitted - missing scope: "admin.connection.health"

Please check your API Key contains required scope.

400

Invalid status {status} received in 'statuses' param. Valid values are INACTIVE,ACTIVE,PENDING

405

HTTP request method not allowed

Action (parameter “action”, for example “connection_health”) is not supported

Fetching connection information for a specific account

Adding an additional GET parameter named account_key will limit the result set to only contain connections for the given account, e.g. https://admin.myintranetapps.com/app/api.php?action=connection_health&account_key=5aa2e93c0ea374.82746293

Filtering connections based on status

Adding an additional GET parameter named statuses will filter the result set based on status. The statuses parameter should be a comma-separated list of statuses you want to include in the response. For example, https://admin.myintranetapps.com/app/api.php?action=connection_health&statuses=ACTIVE would only return ACTIVE connections in the response.
https://admin.myintranetapps.com/app/api.php?action=connection_health&statuses=PENDING,INACTIVE would only return PENDING and INACTIVE connections in the response.
Valid values that can be included in the comma-separated list are ACTIVE, PENDING, or INACTIVE.

Filtering connections based on platforms

Adding an additional GET parameter named platforms will filter the result set based on the platform the connections are categorized to. The platforms parameter should be a comma-separated list of platforms you want to include in the response. For example, https://admin.myintranetapps.com/app/api.php?action=connection_health&platforms=accounting would only return connections from the accounting platform in the response.
https://admin.myintranetapps.com/app/api.php?action=connection_health&platforms=accounting,commerce would only return connections from the accounting and commerce platforms in the response.
Valid values that can be included in the comma-separated list are accounting, commerce, billing and banking.

Embedding

Embed Token

In order to use the Link Page Element widget you will need an embed token.

You can create a new embed token via a GET request (using basic auth or API key) to https://admin.myintranetapps.com/app/api.php?action=embed_token with an "Account-Key" header set to "XXXX"  (where XXXX is your account key)

There are three ways to use Embed Tokens:

  1. To access your own account. In this case, do not use the account_key or observe_account params.

  2. To access a customer account. In this case, account_key should be the account key of the customer account you are trying to access. Do not use the observe_account param.

  3. To access your own account and view a customer’s pages. In this case, account_key should be the account key of the customer whose pages you are trying to view. observe_account should be set to 1.

The Account-Key header is different from the account_key query parameter, the former is used to authenticate to the API, the latter is used to specify which account you need a token for

Parameter

Definition

action
required

Should be set to “embed_token”

account_key
optional

If observe_account is not set, this is the key of the account you wish to access.

If observe_account is set to 1, this is the key of the account whose pages you wish to view (while accessing your own account).

observe_account
optional

If set to 1, you will access your own account with the ability to view another account’s pages.

The response you get back will be in JSON and look like:

{
	"status_code": 200,
	"message": "Embed token generated",
	"token": "et-629cb2c4-a972-47b5-8ed0-f4977a8a8010",
	"expires": "2022-09-08T23:48:59+00:00",
	"params": {
		"account_key": "5f66c0b15206d1.36412804",
		"observe_account": true,
		"redirect_url": false,
		"account_domain": "bank.myintranet.app"
	}
}
JSON

You will need to pass the token and account_domain properties as parameters when instantiating the Link Page Element widget

If something goes wrong while processing your GET request ("status_code" value will differ from 200), the "message" property will contain an error description.


Postman Collection

Administration.postman_collection.json

Collection environment variables:

Variable

Value

Description

admin_subdomain

admin

Unless you have a custom domain this should be set to admin

baseurl

myintranetapps.com

myintranetapps.ca

Either myintranetapps.com or myintranetapps.ca unless you are using a custom domain

account_key

<YOUR ACCOUNT KEY>

The unique alphanumeric key assigned to your account. This will be sent in the header of each API request. e.g. 5a50d8fed44aa9.76285894

username

<YOUR USER NAME>

A user from your account that is part of the admins group

password

<YOUR PASSWORD>

The password of your user