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 a drawing is an unsigned integer in Procore but a UUID in PlanGrid. 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.

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...
}

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'