Passthrough Requests

Using Agave API's authenticated passthrough request, you can make requests directly to the Source Systems. Passthrough requests allow you to a Source System's endpoints before Agave API supports them in a unified way.

We support passthrough requests in three ways:

JSON request, suitable for most requests where the Source System has native JSON API endpoints
Multipart request, when you need to upload files
Other request type, where the Source System does not offer native JSON API endpoints

1. JSON Requests

API Endpoint

https://api.agaveapi.com/passthrough

For full specification, see Passthrough (JSON).

Request Header

As with other API requests, you need to include an API-Version, Client-Id, Client-Secret, and Account-Token. To learn more, see Headers.

Request Body

The request body should be in JSON format with the following parameters:

Key	Type	Description	Example	Required
method	String	The method for the request to the source system.	`"GET"`	Required
path	String	The path for the request to the source system.	`"/rest/v1.0/projects"`	Required
data	JSON	The data for the request body or query parameters.	`{ "company_id": 31936 }`	Optional

Example Requests

Get Projects in Procore

curl --request POST https://api.agaveapi.com/passthrough \
     --header 'API-Version: 2021-11-21' \
     --header 'Client-Id: your_client_id' \
     --header 'Client-Secret: your_client_secret' \
     --header 'Account-Token: procore_account_token' \
     --header 'Content-Type: application/json' \
     --data-raw '{
            "method": "GET",
            "path": "/rest/v1.0/projects",
            "data": { "company_id": 31936 }
        }'

Get Documents Updated Since June 2022 in Aconex

curl --request POST https://api.agaveapi.com/passthrough \
     --header 'API-Version: 2021-11-21' \
     --header 'Client-Id: your_client_id' \
     --header 'Client-Secret: your_client_secret' \
     --header 'Account-Token: aconex_account_token' \
     --header 'Content-Type: application/json' \
     --data-raw '{
            "method": "GET",
            "path": "/api/projects/1207970160/register/integrity",
            "data": {
                "everythingsince" : "2022-06-01T02:00:00.000Z"
            }
        }'

Post an Item in Quickbooks Online

curl --request POST https://api.agaveapi.com/passthrough \
     --header 'API-Version: 2021-11-21' \
     --header 'Client-Id: your_client_id' \
     --header 'Client-Secret: your_client_secret' \
     --header 'Account-Token: quickbooks_online_account_token' \
     --header 'Content-Type: application/json' \
     --data-raw '{
            "method": "POST",
            "path": "/v3/company/4620816365204621010/item?minorversion=4",
            "data": {
                "Name": "New Concrete",
                "Type": "Service",
                "PurchaseCost": 1,
                "IncomeAccountRef": {
                    "value": "48",
                    "name": "Fountains and Garden Lighting"
                }
            }
        }'

Step-by-step Guide

Before starting, you need to reference the API docs for the endpoint you want to use in the Source System.

Example API docs:

Step 1: Identify Method

Identify the method of the request you are trying to make.

Common values:

Method	Description
DELETE	Deletes the specified resource.
GET	Requests a representation of the specified resource. Should only retrieve data.
PATCH	Applies partial modifications to a resource.
POST	Submits an entity to the specified resource.
PUT	Replaces all current representations of the target resource with the request payload.

Step 2: Identify Host URL

Find the host URL for the request. You can typically find this in the overview section of API docs.

Examples:

Aconex: https://{{domain}}.aconex.com
Procore: https://api.procore.com
QuickBooks Online: https://quickbooks.api.intuit.com

Step 3: Identify Full URL

Identify the full path of the request you are trying to make.

Examples:

Aconex get users: https://{{domain}}.aconex.com/api/user
Procore get projects: https://api.procore.com/rest/v1.0/projects
Quickbooks Online post a new item: https://quickbooks.api.intuit.com/v3/company/4620816365204621010/item?minorversion=4

Step 4: Add Path

Truncate the host URL (step 2) from the full URL (step 3). That is the path of the request.

Examples:

Aconex get users: /api/user
Procore get projects: /rest/v1.0/projects
Quickbooks Online post a new item: /v3/company/4620816365204621010/item?minorversion=4

Step 5: Add Data Object

Prepare a JSON object to pass in query parameters or a request body.

Examples:

Aconex get users: no data object needed
Procore get projects for a specific company: { "company_id": 31936 }
Quickbooks Online post a new item:

{
    "Name": "New Concrete",
    "Type": "Service",
    "PurchaseCost": 1,
    "IncomeAccountRef": {
        "value": "48",
        "name": "Fountains and Garden Lighting"
    }
}

Step 6: Get Account Token

To make a request on behalf of a Source System, you will need an Account Token.

Step 7: Make Request

With the method, path, and data parameters filled out, you can make a passthrough request to Agave API:

curl --request POST https://api.agaveapi.com/passthrough \
     --header 'API-Version: 2021-11-21' \
     --header 'Client-Id: your_client_id' \
     --header 'Client-Secret: your_client_secret' \
     --header 'Account-Token: account_token_from_step_6' \
     --header 'Content-Type: application/json' \
     --data-raw '{
            "method": "method_from_step1",
            "path": "path_from_step4",
            "data": { ... }
        }'

2. Multipart Requests

The main reason you would use a multipart passthrough request is so you can upload files in the request body.

API Endpoint

https://api.agaveapi.com/passthrough-multipart

For full specification, see Passthrough (Multipart).

Request Header

In addition to API-Version, Client-Id, Client-Secret, and Account-Token, the common Headers you always include, you also need to pass in the path and method of your request.

Header	Description	Example	Required
Passthrough-Method	The method for the request to the source system.	`"POST"`	Required
Passthrough-Path	The path for the request to the source system with query parameters	`"rest/v1.0/images?project_id=66738"`	Required

Request Body

The content type of the request body should be in multipart/form-data. Then, you can follow the documentation on the API you are trying to hit.

Example Requests

Upload a New Image to Procore

curl --request POST 'https://api.agaveapi.com/passthrough-multipart' \
     --header 'Api-Version: 2021-11-21' \
     --header 'Client-Id: your_client_id' \
     --header 'Client-Secret: your_client_secret' \
     --header 'Account-Token: procore_account_token' \
     --header 'Passthrough-Path: rest/v1.0/images?project_id=66738' \
     --header 'Passthrough-Method: POST' \
     --form 'image[data]=@"/path/test.png"'

Upload a New Schedule to Procore

curl --request POST 'https://api.agaveapi.com/passthrough-multipart' \
     --header 'Api-Version: 2021-11-21' \
     --header 'Client-Id: your_client_id' \
     --header 'Client-Secret: your_client_secret' \
     --header 'Account-Token: procore_account_token' \
     --header 'Passthrough-Path: rest/v1.0/schedule_integration?project_id=66736' \
     --header 'Passthrough-Method: PUT' \
     --form 'schedule_integration[file]=@"/path/test.mpp"'

Step-by-step Guide

Before starting, you need to reference the API docs for the endpoint you want to use in the Source System.

Example API docs:

Procore

Step 1: Identify Method

Identify the method of the request you are trying to make.

Common values for multipart request:

Method	Description
PATCH	Applies partial modifications to a resource.
POST	Submits an entity to the specified resource.
PUT	Replaces all current representations of the target resource with the request payload.

Step 2: Identify Host URL

Find the host URL for the request. You can typically find this in the overview section of API docs.

Examples:

Procore: https://api.procore.com

Step 3: Identify Full URL

Identify the full path of the request you are trying to make, along with the query parameters it requires.

Examples:

Procore upload schedule: https://api.procore.com/rest/v1.0/schedule_integration?project_id=123

Step 4: Add Path

Truncate the host URL (step 2) from the full URL (step 3). That is the path of the request.

Examples:

Procore upload schedule: /rest/v1.0/schedule_integration?project_id=123

Step 5: Construct Multipart Request Body

Locate the file you want to upload and construct the request body

Examples:

Procore upload schedule:

'schedule_integration[file]=@"/path/test.mpp"'

Step 6: Get Account Token

To make a request on behalf of a Source System, you will need an Account Token.

Step 7: Make Request

With the method, path, and data parameters filled out, you can make a multipart passthrough request to Agave API:

curl --request POST 'https://api.agaveapi.com/passthrough-multipart' \
     --header 'API-Version: 2021-11-21' \
     --header 'Client-Id: your_client_id' \
     --header 'Client-Secret: your_client_secret' \
     --header 'Passthrough-Method: method_from_step1' \
     --header 'Passthrough-Path: path_from_step4' \
     --header 'Account-Token: account_token_from_step_6' \
     --form 'form_data_from_step5'

3. Other Request Types

The following explains how to structure passthrough requests to a Source System that does not offer native JSON API endpoints (e.g. QuickBooks Desktop, Viewpoint Vista). Note, the response body for these requests will always be in JSON.

API Endpoint

https://api.agaveapi.com/passthrough

For full specification, see Passthrough (JSON).

Request Header

As with other API requests, you need to include an API-Version, Client-Id, Client-Secret, and Account-Token. To learn more, see Headers.

Request Body

Unlike JSON and multi-part passhthrough requests, the request body will depend on the Source System.

QuickBooks Desktop

Since QuickBooks Desktop does not have native JSON APIs, you will need to use its native XML operations to make requests.

info

Check out QuickBooks Desktop's API Reference to see a list of XML operations that are supported. These operations can be fine in the XMLOps tab for each data object. If you are unable to find the endpoint you need, please contact us at support@agaveapi.com and we should be able to assist.

For example, the below request retrieves a list of Classes in a customer's QuickBooks Desktop account using the Class Query XML Operation:

curl --request POST https://api.agaveapi.com/passthrough \
     --header 'API-Version: 2021-11-21' \
     --header 'Client-Id: your_client_id' \
     --header 'Client-Secret: your_client_secret' \
     --header 'Account-Token: quickbooks_desktop_account_token' \
     --header 'Content-Type: text/xml' \
     --data-raw '
            <?xml version="1.0" encoding="utf-8"?>
            <?qbxml version="16.0"?>
            <QBXML>
                <QBXMLMsgsRq onError="stopOnError">
                    <ClassQueryRq>            
                    </ClassQueryRq>
                </QBXMLMsgsRq>
            </QBXML>
        '

As with all Agave API passthrough requests, the response will be in JSON:

{
    "body": [
        {
            "ListID": "12345-123456789",
            "TimeCreated": "2022-01-01T00:00:00-00:00",
            "TimeModified": "2022-01-01T00:00:00-00:00",
            "EditSequence": "12345678",
            "Name": "Revenue - Job Related",
            "FullName": "Revenue - Job Related",
            "IsActive": "true",
            "Sublevel": "0"
        }
}

Sage Intacct

Since Sage Intacct does not have native JSON APIs, you will need to use its native XML request format.

info

Check out Sage Intacct's API Reference to see a list of XML requests that are supported. If you are unable to find the endpoint you need, please contact us at support@agaveapi.com and we should be able to assist.

For example, the below request retrieves a list of Project Statuses in a customer's Sage Intacct account using the Project Status XML Request:

curl --request POST https://api.agaveapi.com/passthrough \
     --header 'API-Version: 2021-11-21' \
     --header 'Client-Id: your_client_id' \
     --header 'Client-Secret: your_client_secret' \
     --header 'Account-Token: quickbooks_desktop_account_token' \
     --header 'Content-Type: application/json' \
     --data-raw '
        <readByQuery>
            <object>PROJECTSTATUS</object>
            <fields>*</fields>
            <query></query>
            <pagesize>100</pagesize>
        </readByQuery>
        '

As with all Agave API passthrough requests, the response will be in JSON:

{
    "body": {
        "@attributes": {
            "listtype": "projectstatus",
            "count": "1",
            "totalcount": "1",
            "numremaining": "0",
            "resultId": ""
        },
        "projectstatus": [
            {
                "NAME": "Unstarted",
                "DESCRIPTION": "Unstarted",
                "PREVENTTIMESHEET": "false",
                "PREVENTEXPENSE": "false",
                "PREVENTAPPO": "false",
                "PREVENTGENINVOICE": "false",
                "STATUS": "active",
                "RECORDNO": "1",
                "WHENCREATED": "01/01/2022 00:00:00",
                "WHENMODIFIED": "01/01/2022 00:00:00",
                "CREATEDBY": "1",
                "MODIFIEDBY": "1",
                "MEGAENTITYKEY": "1",
                "MEGAENTITYID": "GC",
                "MEGAENTITYNAME": "AnyContractors Inc."
            }
        ]
    }
}

Viewpoint Vista

Since Viewpoint Vista does not have native APIs and is backed by a SQL databases, you will need to use a different request syntax to return results from a Source System's underlying SQL table for a data object.

info

Agave API only supports read operations for passthrough requests for Viewpoint Vista. If you are interested in Agave API supporting write passthrough requests, please contact us at support@agaveapi.com.

The request body should be in JSON format with the following parameters:

Key	Type	Description	Example	Required
table	String	This is the underlying backing table name in the Source System.	`"HQCO"`	Yes
operation	String	This is the operation to perform on the table. It can be one of "COUNT", "SCHEMA", or "SELECT".	`"SELECT"`	Yes
filters	Array of Objects	These are filters that can be applied to return a subset of results from the table.	`[{"field": "Category","operator": "=","value": "1"}]`	No
limit	Integer	This is the number of results to return in the request.	`10`	No
offset	Integer	This is the the position of the results returned in the request.	`0`	No
order_by	Array of Objects	This is one or more column to order the results returned in the request.	`"[{"field": "HQCO", "dir": "ASC"}]`	No
columns	Array	This is an array you can pass to specify which columns to return in the request.	`["HQCO", "NAME]`	No

Get Results for a Table

Using the SELECT operation in a passthrough request to Viewpoint Vista returns a list of results for a specific object:

curl --request POST https://api.agaveapi.com/passthrough \
     --header 'API-Version: 2021-11-21' \
     --header 'Client-Id: your_client_id' \
     --header 'Client-Secret: your_client_secret' \
     --header 'Account-Token: viewpoint_vista_account_token' \
     --header 'Content-Type: application/json' \
     --data-raw '{
            "table": "HQCO",
            "operation": "SELECT",
            "limit": 1,
            "offset": 0,
            "order_by": "HQCo",
            "columns": [
                        "HQCo", 
                        "Name", 
                        "Address"
                    ]
        }'

The response generated is one result with the values for each column specified in the columns array:

{
    "body": [
        {
            "HQCo": "1",
            "Name": "AnyContractors Inc",
            "Address": "123 Main Street"
        }
    ],
    "content_type": "application/json",
    "headers": [],
    "status": 200
}

info

To see a list of tables available in a Viewpoint Vista instance, input vDDFH as the value for table in a request with SELECT as the operation.

Get Schema for a Table

Using the SCHEMA operation in a passthrough request to Viewpoint Vista returns the table schema for a specific object (in the below example, an end-user's Viewpoint Vista Company).

curl --request POST https://api.agaveapi.com/passthrough \
     --header 'API-Version: 2021-11-21' \
     --header 'Client-Id: your_client_id' \
     --header 'Client-Secret: your_client_secret' \
     --header 'Account-Token: viewpoint_vista_account_token' \
     --header 'Content-Type: application/json' \
     --data-raw '{
            "table": "HQCO",
            "operation": "SCHEMA"
        }'

The response generated is the schema for each column in the table, returned in a JSON format:

{
    "body": [
        {
            "default_constraints_name": null,
            "column_name": "HQCo",
            "data_type": "string",
            "is_identity": "0",
            "data_length": "1",
            "numeric_precision": "3",
            "numeric_scale": "0",
            "is_nullable": "NO",
            "column_default": null,
            "foreign_key": "HQCo"
        },
    ...

Get Totals for a Table

Using the COUNT operation in a passthrough request to Viewpoint Vista returns the total number of rows in the table.

For example, here is a request returning the total number of Companies in an end-user's Viewpoint Vista instance:

curl --request POST https://api.agaveapi.com/passthrough \
     --header 'API-Version: 2021-11-21' \
     --header 'Client-Id: your_client_id' \
     --header 'Client-Secret: your_client_secret' \
     --header 'Account-Token: viewpoint_vista_account_token' \
     --header 'Content-Type: application/json' \
     --data-raw '{
            "table": "HQCO",
            "operation": "COUNT"
        }'

The response generated is the count of rows:

{
    "body": {
        "count": 5
    },
    "content_type": "application/json",
    "headers": [],
    "status": 200
}

Passthrough Requests

1. JSON Requests​

API Endpoint​

Request Header​

Request Body​

Example Requests​

Step-by-step Guide​

Step 1: Identify Method​

Step 2: Identify Host URL​

Step 3: Identify Full URL​

Step 4: Add Path​

Step 5: Add Data Object​

Step 6: Get Account Token​

Step 7: Make Request​

2. Multipart Requests​

API Endpoint​

Request Header​

Request Body​

Example Requests​

Step-by-step Guide​

Step 1: Identify Method​

Step 2: Identify Host URL​

Step 3: Identify Full URL​

Step 4: Add Path​

Step 5: Construct Multipart Request Body​

Step 6: Get Account Token​

Step 7: Make Request​

3. Other Request Types​

API Endpoint​

Request Header​

Request Body​

QuickBooks Desktop​

Sage Intacct​

Viewpoint Vista​

Get Results for a Table​

Get Schema for a Table​

Get Totals for a Table​

1. JSON Requests

API Endpoint

Request Header

Request Body

Example Requests

Step-by-step Guide

Step 1: Identify Method

Step 2: Identify Host URL

Step 3: Identify Full URL

Step 4: Add Path

Step 5: Add Data Object

Step 6: Get Account Token

Step 7: Make Request

2. Multipart Requests

API Endpoint

Request Header

Request Body

Example Requests

Step-by-step Guide

Step 1: Identify Method

Step 2: Identify Host URL

Step 3: Identify Full URL

Step 4: Add Path

Step 5: Construct Multipart Request Body

Step 6: Get Account Token

Step 7: Make Request

3. Other Request Types

API Endpoint

Request Header

Request Body

QuickBooks Desktop

Sage Intacct

Viewpoint Vista

Get Results for a Table

Get Schema for a Table

Get Totals for a Table