Skip to main content

Pass-through Requests

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

We support pass-through requests in two ways:

  1. JSON request, suitable for most requests
  2. Multipart request, when you need to upload files

1. JSON Request

API Endpoint

https://api.agaveapi.com/passthrough

For full specification, see Pass-through (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:

KeyTypeDescriptionExampleRequired
methodStringThe method for the request to the source system."GET"Required
pathStringThe path for the request to the source system."/rest/v1.0/projects"Required
dataJSONThe 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:

  1. Aconex
  2. Procore
  3. Quickbooks Online

Step 1: Identify Method

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

Common values:

MethodDescription
DELETEDeletes the specified resource.
GETRequests a representation of the specified resource. Should only retrieve data.
PATCHApplies partial modifications to a resource.
POSTSubmits an entity to the specified resource.
PUTReplaces 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:

  1. Aconex: https://{{domain}}.aconex.com
  2. Procore: https://api.procore.com
  3. 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:

  1. Aconex get users: https://{{domain}}.aconex.com/api/user
  2. Procore get projects: https://api.procore.com/rest/v1.0/projects
  3. 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:

  1. Aconex get users: /api/user
  2. Procore get projects: /rest/v1.0/projects
  3. 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:

  1. Aconex get users: no data object needed
  2. Procore get projects for a specific company: { "company_id": 31936 }
  3. 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 pass-through 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 Request

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

API Endpoint

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

For full specification, see Pass-through (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.

HeaderDescriptionExampleRequired
Passthrough-MethodThe method for the request to the source system."POST"Required
Passthrough-PathThe 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:

  1. Procore

Step 1: Identify Method

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

Common values for multipart request:

MethodDescription
PATCHApplies partial modifications to a resource.
POSTSubmits an entity to the specified resource.
PUTReplaces 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:

  1. 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:

  1. 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:

  1. 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:

  1. 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 pass-through 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'