Overview

A Correlation ID is an optional, user created string value you can set at the Credential or File level to help reconcile with your internal systems. They do not have to be unique.

When submitting a Credential or File, you can specify a correlationId as an optional parameter. This field is intended to group together related data or to tag data at point of entry to the system with identifying information. By searching on correlationId or correlationIds, you can retrieve related entities quickly.

A correlationId can be specified in the following ways:

• A request parameter when creating or updating Credentials
• A query parameter when adding Files
• A query parameter when submitting Credentials through Connect

Credentials and Files are the only entities that "own" and can set a correlationId as they are the source of data that creates the other entities: Accounts, Meters, and Statements.

Accounts, Meters, and Statements have a list of correlationIds which is populated automatically from the inherited Credentials and Files.

When a Credential's correlationId is updated, the update will cascade down to the associated Accounts, Meters, and Statements, updating their list of correlationIds. The new value will be added and the old value will be removed if the Account, Meter, or Statement is not associated with another Credential or File with that correlationId.

Examples

Statement Submitted via Files Module & Credential Upload Correlation ID Behavior

If a Statement statementId==stm_111 for accountId==act_222 is submitted via the Files module (fileId==000) and the correlationId field is set to "aaa", then correlationIds value for the Account, the Meters on the Statement submitted, and the Statement itself would be ["aaa"].

If you then submit the Credentials for accountId==act_222 where credentialId==crd_333with the Credential correlationId set to "zzz", then the field correlationIds for statementId==stm_111 and accountId==act_222 would be ["aaa", "zzz"].

Only the Statement, statementId==stm_111, submitted via the Files module would have aaa as part of its correlationIds array. Any additional Statements for accountId==act_222 created by credentialId==crd_333 would have a correlationIds value of ["zzz"] (assuming they were not also submitted as Files).

Only the Meters extracted from statementId==stm_111 would have the aaa as part of its correlationIds array. Any additional Meters for accountId==act_222 extracted from other Statements would have a correlationIds value of ["zzz"] (assuming they were not also submitted on Statements in the Files module).

Credential Correlation ID Change

Assuming there are no Files for Statements under given Credential 444

Before

After

Important Notes

📘

A single Account, Meter, or Statement can be associated with multiple Credentials and/or multiple Files

There are legitimate cases where different Credentials can have access to the same utility Account and Statements. In such scenarios, the Accounts, Meters, and Statements will be tagged with each Credentials' correlationIds.

It is also possible for two Files to generate the same Accounts, Meters, and Statement. Plug deduplicates Files based on the content, so if the content of two files differs but the extracted Statement data is the same, both Files will associate with the same Statement entity. This can happen if the File includes a timestamp for when it was generated or downloaded, for example.

Similarly, it is possible for a Statement and its Accounts and Meters to be associated with a Credential and a File if the bill is uploaded as a File in addition to being available via the Credential. The entities will be tagged with the correlationId from both the File and the Credential in this case.

For these reasons, Accounts, Meters, and Statements have correlationIds as a list that can hold multiple values.

🚧

The correlationIds list on Accounts, Meters, and Statements may not be populated if your data is older than May 23rd, 2024

If you need this data to be populated, you can update the correlationId on the Credentials to cascade the update to the existing Account, Meters, and Statements. The update will cause each entity to recalculate its correlationIds list, so if one belongs to multiple Credentials, only one Credential will need to be updated for the list to be populated correctly. If the Account, Meter, or Statement is from File upload only, the File must be deleted and resubmitted with a correlationId since it is not possible to update a File's correlationId currently.