Skip to main content

Reference ID

When you generate a Link Token to initialize an Agave Link session, you need to pass in a reference_id as a parameter.

Agave API uses the reference_id parameter to determine if the Agave Link is for a new Integration and reference_id is different since each reference_id can only belong to one Integration.

In certain situations, you may want to let your Users link multiple accounts within the same Integration (e.g. a User could belong to multiple companies in a Procore account). For these situations, we recommend that you use different reference_ids for each Link Token request (e.g. user-1234:procore, user-1234:dropbox, etc). Note, you can format the reference identifier however you want since this is an opaque string.

danger

The reference_id cannot be longer than 255 characters.

Note for On-Prem or Hosted Integrations​

If you use an On-Prem (e.g., QuickBooks Desktop) or Hosted (e.g., Vista Hosted or Foundation Hosted) 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.

The full list of Source Systems that require a unique Reference ID is:

  • Cheops (Hosted and On-Prem)
  • Foundation (Hosted and On-Prem)
  • QuickBooks Desktop (On-Prem)
  • Vista (Hosted and On-Prem)
  • Sage 100 Contractor (On-Prem)
  • Sage 300 CRE (On-Prem)

A different Reference ID results in different Agave Ids when using our APIs, even if the underlying object has the same Source Id.