Skip to main content

Identifiers

Agave API generates and uses persistent UUIDs in all request parameters and response bodies. This UUID is known as the Agave ID.

The Agave ID removes the need to write Source System-specific logic to handle different identifier formats. For example, the unique identifier of an AP Invoice is an unsigned integer in Procore but either a combination of month + transaction number (for Posted AP Invoices) or a combination of month + batch number + batch sequence (for Pending AP Invoices) in Vista. If you integrate with Agave API, you will get an Agave ID for both Source Systems.

Some Source Systems may not even have an identifier for an object. In these cases, Agave will still generate a persistent UUID for these objects for you.

info

We recommend you store both Agave IDs and Source IDs. Both are usable with Agave unified endpoints, but only Source IDs can used for passthrough requests.

caution

Agave IDs are unique within the context of their parent objects. See here for more info.

Note for On-Prem / Hosted Integrations​

If you use a hosted or on-prem integration, then the Reference ID uniquely identifies your user. If you want to re-authenticate the same user, you must pass the same Reference ID as before. A different Reference ID results in a different Agave Id.

The following Source Systems follow this behavior:

Agave Id​

The Agave Id is always returned as the id field of the object.

{
    "id": "15baed1e-7eff-52f4-8fef-3851b4a509d6",
    "source_id": "1120",
    "name": "Job 1120",
    "status": "Completed",
    "description": "Call customer before arrival.",
    // more properties...
}

Uniqueness​

Agave UUIDs are unique within the context of their parent objects. This means that, for example, the Cost Codes in two different Projects can have the same UUID, or that the Line Items in two different AP Invoices can have the same UUID.

We recommend that you store the Agave ID of your object and its parent(s) database as a unique composite key.

For example, if you store AP Invoice Line Items in a database, you should use the pair of <project_uuid, ap_invoice_uuid, line_item_uuid> as the unique key for the table. Note that you will need to pass all of these 3 identifiers to the Agave API when making a request, so the columns should already exist in your table:

curl /ap-invoices/{ap_invoice_uuid}/line-items/{line_item_uuid} \
     --header 'API-Version: 2021-11-21' \
     --header 'Client-Id: CLIENT_ID' \
     --header 'Client-Secret: CLIENT_SECRET' \
     --header 'Account-Token: ACCOUNT_TOKEN' \
     --header 'Project-Id: {project_id}'

Source Id​

In addition to the Agave ID, Agave API also returns the object ID from the the Source System as source_id.

For example, from the GET /projects/{id} endpoint:

{
    "id": "15baed1e-7eff-52f4-8fef-3851b4a509d6",
    "source_id": "123",
    "name": "Project 123",
    "description": "Project 123 is the most fun project",
    // more properties...
}

Using Identifiers

Generally speaking, you should always interact with Agave-provided UUIDs, both when storing them on your database and when interacting with Agave APIs. For example, to retrieve a project through the GET /projects/{id} endpoint, use the Agave ID for this Project:

curl https://api.agaveapi.com/projects/15baed1e-7eff-52f4-8fef-3851b4a509d6 \
     --header 'API-Version: 2021-11-21' \
     --header 'Client-Id: CLIENT_ID' \
     --header 'Client-Secret: CLIENT_SECRET' \
     --header 'Account-Token: ACCOUNT_TOKEN'

The only exception is when you make a passthrough request and don't have an Agave-provided UUID. In these situations, the source ID can be passed with source_id: as prefix. The source_id:{source_id} convention can be used anywhere an ordinary UUID is used: in a query parameter, request header, or request body.

This is identical to the example above, using an Agave-provided UUID to get the project:

curl https://api.agaveapi.com/projects/source_id:123 \
     --header 'API-Version: 2021-11-21' \
     --header 'Client-Id: CLIENT_ID' \
     --header 'Client-Secret: CLIENT_SECRET' \
     --header 'Account-Token: ACCOUNT_TOKEN'

Line Items​

Line items are referenced via their parent.

For example: GET /ap-invoices/{ap_invoice_id}/line-items/{id}

This means that Line Item UUIDs are only unique within the context of their parent.

For example:

  • AP Invoice Line Item A can have UUID: 3d0ef836-073f-5741-bdf3-a589f21cc58d and parent AP Invoice UUID 65726c4f-5f59-523f-a3c2-419d103ff09f
  • AP Invoice Line Item B can also have UUID: 3d0ef836-073f-5741-bdf3-a589f21cc58d and parent AP Invoice UUID 46951c9b-d6e9-5817-93f1-611c794779c8

Since these UUIDs are not globally unique, if you store Line Item UUIDs in a database please ensure the unique key for the table is the pair of {parentID, lineItemID}