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 4 ways:
- JSON Request, for most requests where the Source System has native JSON API endpoints,
- File Download Request, for downloading files,
- Multipart Upload Request, for uploading files, and
- Other Request Types, for Source Systems that do not offer native JSON API endpoints.
1. JSON Requests
API Endpoint
https://api.agaveapi.com/passthrough
For the 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": {companyId}
}
}'
Get Classes 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": "GET",
"path": "/v3/company/{companyId}/query?",
"data": {
"query": "select * from Class"
}
}'
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/{projectId}/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.