Correlation IDs
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"]
.
ID | Correlation ID | Correlation IDs |
---|---|---|
fileId==fil_000 | "aaa" | N/A |
statementId==stm_111 | N/A | ["aaa"] |
accountId==act_222 | N/A | ["aaa"] |
If you then submit the Credentials for accountId==act_222
where credentialId==crd_333
with the Credential correlationId
set to "zzz"
, then the field correlationIds
for statementId==stm_111
and accountId==act_222
would be ["aaa", "zzz"]
.
ID | Correlation ID | Correlation IDs |
---|---|---|
fileId==fil_000 | "aaa" | N/A |
statementId==stm_111 | N/A | ["aaa", "zzz"] |
accountId==act_222 | N/A | ["aaa", "zzz"] |
credentialId==crd_333 | "zzz" | N/A |
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
ID | Correlation ID | Correlation IDs |
---|---|---|
credentialId==crd_444 | "bbb" | N/A |
statementId==stm_555 | N/A | ["bbb"] |
accountId==act_777 | N/A | ["bbb"] |
meterId==mtr_888 | N/A | ["bbb"] |
After
ID | Correlation ID | Correlation IDs |
---|---|---|
credentialId==crd_444 | "ccc" | N/A |
statementId==stm_555 | N/A | ["ccc"] |
accountId==act_777 | N/A | ["ccc"] |
meterId==mtr_888 | N/A | ["ccc"] |
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' correlationId
s.
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.
Updated 3 months ago