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:

JSON

{
    "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
        }
	]
}

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
400	Bad Request	Check that you are sending a standard “Host” header in your request
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.

Connection Disconnect

To forcibly disconnect a previously connected application send a POST request (using basic auth) to https://admin.myintranetapps.com/app/api.php with with an "Account-Key" header set to "XXXX" (where XXXX is your account key) that contains a JSON body that looks like:

JSON

{
  "action": "connection_disconnect",
  "account_key": "5a70d8fcd44aa9.76285892",
  "integration": "chargebee",
  "environment": "production",
  "purge_data": true
}

The property called "account_key" must be set to the account key of the account to update. The integration property must also be set to a valid integration key. Environment should be set to either “production” or “sandbox”.

If the optional “purge_data” property is set to true, then a background job will be started that deletes all previously stored data related to this integration. You can setup a "Data Purge Complete" webhook to know when this background job is completed.

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

JSON

{
  "status_code":200,
  "message":"Connection successfully disconnected",
  "account_key": "5a70d8fcd44aa9.76285892",
  "integration": "chargebee",
  "environment": "production",
  "purge_job_id": 22
}

Note that the response will only contain a “purge_job_id” if “purge_data” was set to true in the request.

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
400	Bad Request	Check that you are sending a standard “Host” header in your request
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.disconnect"	Please check your API Key contains required scope.
400	No account_key is set for update
400	No integration specified
400	environment param must be set for connection_disconnect action OR environment param must be one of: production, sandbox	You must specify the environment of the connection you are requesting to disconnect
409	Connection not updated	There was no connection in this environment to disconnect

Health in Admin Portal

Connection health is also visible within your administration portal, a listing of all customer connections will be displayed along with current connection health information including when the connection was created and when it last synchronized data.