DOCSEARCHbyAlgolia
Submit Docs

Agave API Documentation

website·Indexed 33 days ago

https://docs.agaveapi.com

A unified API for integrating with various source systems including Procore, QuickBooks Online, Sage 300 CRE, Sage Intacct, Viewpoint Vista, ServiceTitan, and others. The documentation covers Agave Link for authentication and SSO, API reference for pagination, filtering, and webhooks, and specific setup guides for on-prem and cloud-hosted source systems.

Tokens
29.1K
Snippets
68
Records
198
Agent score
62%

What's inside Agave

  1. Overview of Agave API and Core Concepts

    Agave API provides a single, unified REST API to interact with various third-party software systems (Source Systems) used in construction and field services, such as Procore, QuickBooks Online, and ServiceTitan.

    Key terminology for using the platform:

    • Source System: The third-party software being integrated (e.g., Procore).
    • User: The person granting your application permission to access their data in a Source System.
    • Integration: Agave's specific connection to a Source System.
    • Agave Link: A front-end component used to let Users select Source Systems, authenticate, and grant data access.
    • Linked Account: A User's Source System account after successful authentication via Agave Link.
    • Agave File Manager: A front-end component for selecting files and folders from a Linked Account.

  2. Understand and use Agave IDs

    The Agave ID is a persistent UUID generated by the Agave API for every object, regardless of whether the source system has its own identifier. Agave IDs are returned in the id field of response bodies. Developers should use Agave IDs for most API interactions and database storage to avoid writing source-system-specific logic for different identifier formats.
    {
    "id": "15baed1e-7eff-52f4-8fef-3851b4a509d6",
    "source_id": "1120",
    "name": "Job 1120",
    "status": "Completed",
    "description": "Call customer before april."
}

  3. Understand Line Items in Agave

    A Line Item represents an estimated expenditure and must always be associated with a financial object. Supported financial objects include AP Invoices, AR Invoices, AR Payments, Change Events, Change Orders, Estimates, Prime Contracts, Purchase Orders, and Subcontracts. Each Line Item is assigned a unique Agave-generated UUID.

    Distinction between Line Items and Items:

    • An Item is a product or service a company buys, sells, or re-sells.
    • A Line Item is a record of a specific expenditure on a financial document. While a Line Item can reference an Item, it is not required (e.g., AR Payment Line Items reference documents like Invoices rather than Items).

  4. Understand Agave API versioning and backward compatibility

    Agave API introduces new integrations and endpoints without updating the API-Version if the changes are backward-compatible. Backward-compatible changes include:

    • Adding new API endpoints
    • Adding new optional request parameters
    • Adding new properties to existing responses
    • Adding new values to existing ENUM properties
    • Changing the order of properties in responses
    • Changing the length or format of opaque strings (e.g., object IDs, error messages)
    • Adding new error types

    Non-backward-compatible (breaking) changes will trigger the release of a new API version to prevent impacting existing clients.

  5. Authenticate Sage Intacct with Agave

    To complete the connection between Sage Intacct and Agave, provide the following credentials in the Agave Link interface:

    • Company ID: Found under Applications -> Overview -> Company Information.
    • Sender ID: The Web Service Sender ID provided by Sage Intacct.
    • Sender Password: The Web Service Sender Password provided by Sage Intacct.
    • User ID: The Web Service User ID created during the setup process.
    • Password: The password for the Web Service User.

    After submitting these details, select the appropriate Entity and confirm to finish authentication.

  6. Understand Agave API webhook event payload structure

    When Agave API sends a webhook event to your callback URL, it provides a JSON payload containing metadata about the event, the target resource, and the raw source data from the integrated provider (e.g., Autodesk Build, BIM 360). The payload includes top-level identifiers such as id, source_id, project_id, and the event type (e.g., "UPDATE"), along with a source_data object containing the specific event details from the third-party system.
    {
 "id": "61ce34a3-db8f-5a3b-a900-f929ca8f325b",
 "source_id": "17a674cc-5c71-4d0c-8017-7be022ed9f87",
 "callback_url": "https://your-website.com/webhook-callback",
 "event": "UPDATE",
 "project_id": "a573cb23-0ca0-5b1e-95b2-c0a502f948cd",
 "target": "e2061d61-300b-5346-bbf6-91fe649b85c4",
 "type": "file",
 "source_data": {
   "path": "",
   "content_type": "application/json",
   "data": {
     "version": "1.0",
     "resourceUrn": "urn:adsk.wipprod:fs.file:vf.-R7wYazIQXu4Xwd-CcY0tA?version=1",
     "hook": {
       "event": "dm.version.modified",
       "status": "active"
     },
     "payload": {
       "name": "test-file.png",
       "sizeInBytes": 47872,
       "modifiedTime": "2024-01-04T00:27:18+0000"
     }
   }
 }
}

  7. CMiC environment and version support

    Agave supports all CMiC instances regardless of hosting method (on-prem, iPaaS, or cloud hosted) and all environment types (train, test, conv, and prod). All CMiC versions with API access are supported. Note that API access may need to be purchased as a separate package from CMiC.

  8. Understand the /link/account response structure

    The /link/account endpoint returns a JSON object containing the account status, the source system (e.g., Procore), and details about the linked user and company. The linked_user.email field is the primary identifier used for matching or creating accounts in your own database.
    {
  "account_id": "ee9b53e7-f982-4be6-bc12-75f716d3ee94",
  "linked_company": {
    "id": "ee9b53e7-f982-4be6-bc12-75f716d3ee94",
    "source_id": "12345",
    "name": "Agave construction Inc."
  },
  "linked_user": {
    "id": "ee9b53e7-f982-4be6-bc12-75f716d3ee94",
    "source_id": "12345",
    "name": "John Smith",
    "email": "jsmith@example.com"
  },
  "status": "linked",
  "source_system": {
    "slug": "procore",
    "name": "Procore"
  },
  "supports_cross_account_uuid": true
}

  9. Agave API Technical Architecture

    The Agave API is built on REST principles. It uses resource-oriented URLs, accepts and returns JSON-encoded bodies, and utilizes standard HTTP response codes, verbs, and authentication. While SDKs are provided for popular languages, any standard HTTP client can be used to make requests.

  10. Interpret Agave API response headers

    Agave API responses include several custom headers to provide metadata about the request, billing status, and data freshness. Key headers include:

    • Agave-Debug-Id: A unique identifier for the response. Provide this to Agave support for troubleshooting.
    • Agave-Billing-Id: A unique identifier tied to the linked Company used for billing active monthly Linked Accounts.
    • Agave-Billing-Enabled: Indicates if the account is a 'test' or 'production' account for billing purposes.
    • Agave-Data-Retrieved-At: The ISO-8601 timestamp indicating when the data was retrieved from the Source System.
    • Agave-Warnings: Contains non-critical processing issues (e.g., automatic Content-Type changes) to assist in debugging.

  11. Configure Windows Date Time Format for Sage 300 CRE and Agave API

    To ensure the Agave API functions correctly with Sage 300 CRE, the Windows system of the user installing the Agave connector must be configured to use the US date format.

    Follow these steps:

    1. Right-click the time on the Windows taskbar and select "Adjust date and time settings."
    2. Set the Country/Region to United States.
    3. Set the Current format to English (United States).
    4. In the "Change date formats" section, ensure the Short Date and Long Date formats are correctly configured.
    5. Restart the Windows machine.
    6. Open Sage 300 CRE and verify that dates appear in the yyyy-mm-dd format.
    7. Install the Agave Connector on this specific Windows user account.

  12. Install the Agave Link initialization script

    To use Agave Link, include the initialization script on every page of your site. The script must be loaded directly from the Agave CDN and cannot be bundled or hosted locally.
    <script src="https://cdn.agaveapi.com/init.js"></script>