# Certificate Holdings

Retrieve the list of all monthly certificates held by the API user (hourly certificates are not included). This will return certificates belonging to the API user that are in active and retired states.

Endpoint: GET /api/ledger/holding
Version: 1.0.0
Security: JWT

## Query parameters:

  - `accountIds` (array)
    Account ids: if specified, limits results to the items related to the accounts whose ids match the provided set; otherwise, all results related to any authorized account will be returned

  - `vintageStart` (string)
    Vintage start (inclusive)

  - `vintageEnd` (string)
    Vintage end (exclusive)

  - `subaccountTypeCode` (string)
    Subaccount type code. If not specified, holdings will be returned regardless of status.

  - `$filter` (string)
    OData-like filter expression

  - `$orderby` (string)
    Comma-separated list of columns for sorting

  - `$skip` (integer)
    Number of records to skip

  - `$top` (integer)
    Maximum number of records to return

  - `$apply` (string)
    OData-like apply expression with groupby and aggregate only

## Response 200 fields (application/json):

  - `@count` (integer)

  - `value` (array, required)

  - `value.accountId` (string, required)
    The account identifier
    Example: "55"

  - `value.notificationName` (string, required)
    The name of the beneficial owner of a retirement
    Example: "John Doe"

  - `value.notificationEmail` (string, required)
    The email address of the beneficial owner of a retirement
    Example: "jdoe@acmecorp.com"

  - `value.certificateSerialNumberRange` (string, required)
    The certificate serial number range
    Example: "NAR-REC-1234-CA-06-2024-555555-1 to 66"

  - `value.certificateStatus` (string)
    The certificate status - Active, Pending, Retired
    Example: "RETIRED"

  - `value.countryIso2Code` (string, required)
    The country to which resource belongs as an ISO-2 code
    Example: "US"

  - `value.fuelTypeCode` (string, required)
    The fuel type code: see documentation for possible values
    Example: "H2O"

  - `value.fuelTypeDescription` (string, required)
    The fuel type description
    Example: "Hydroelectric Water"

  - `value.quantity` (number, required)
    The holding quantity
    Example: 66

  - `value.resourceName` (string, required)
    The resource name
    Example: "Acme Hydro"

  - `value.resourceProgramAssignedIdentifier` (string, required)
    The resource identifier
    Example: "GEN1234"

  - `value.retirementDate` (string)
    The date the holding was retired
    Example: "2024-10-06T22:38:15.08Z"

  - `value.retirementDetails` (string)
    Additional retirement details
    Example: "Retired of behalf of John Doe"

  - `value.retirementReasonCode` (string)
    The retirement reason code: see documentation for possible values
    Example: "22"

  - `value.retirementReasonDescription` (string)
    The retirement reason description
    Example: "REC-Only Product"

  - `value.retirementComplianceState` (string)
    The State chosen for the retirement. (ISO 3166-2 code)
    Example: "CA"

  - `value.retirementYear` (integer)
    The retirement year
    Example: 2024

  - `value.retirementTypeCode` (string)
    The retirement type code: see documentation for possible values
    Example: "GRN"

  - `value.retirementTypeDescription` (string)
    The retirement type description: see documentation for possible values
    Example: "Green-e Energy Voluntary Market"

  - `value.subaccountType` (string)
    The subaccount type code: see documentation for possible values
    Example: "RET"

  - `value.subaccountId` (string)
    The subaccount identifier
    Example: "321"

  - `value.subaccountName` (string)
    The subaccount name
    Example: "Green-e Retirements 2024"

  - `value.vintageMonth` (string, required)
    The vintage month (rendered as an ISO-8601 date)
    Example: "06/2024"

  - `value.eligibilities` (string)
    a comma-delimited list of eligibility codes: see documentation for possible values
    Example: "CRS Listed"

  - `totalCount` (integer)

  - `countExceeded` (boolean, required)

## Response 400 fields (application/json):

  - `submissionId` (string)
    Submission identifier for issue investigation

  - `errors` (array)
    List of errors

  - `errors.parameter` (string)
    The parameter in error, if applicable

  - `errors.correlationId` (string)
    The correlation identifier from the input

  - `errors.path` (string)
    The path to the field specifically in error, if applicable

  - `errors.field` (string)

  - `errors.code` (string)
    The field in error, if applicable

  - `errors.message` (string, required)
    The error code

## Response 401 fields (application/json):

  - `submissionId` (string)
    Submission identifier for issue investigation

  - `errors` (array)
    List of errors

  - `errors.parameter` (string)
    The parameter in error, if applicable

  - `errors.correlationId` (string)
    The correlation identifier from the input

  - `errors.path` (string)
    The path to the field specifically in error, if applicable

  - `errors.field` (string)

  - `errors.code` (string)
    The field in error, if applicable

  - `errors.message` (string, required)
    The error code

## Response 403 fields (application/json):

  - `submissionId` (string)
    Submission identifier for issue investigation

  - `errors` (array)
    List of errors

  - `errors.parameter` (string)
    The parameter in error, if applicable

  - `errors.correlationId` (string)
    The correlation identifier from the input

  - `errors.path` (string)
    The path to the field specifically in error, if applicable

  - `errors.field` (string)

  - `errors.code` (string)
    The field in error, if applicable

  - `errors.message` (string, required)
    The error code

## Response 429 fields (application/json):

  - `submissionId` (string)
    Submission identifier for issue investigation

  - `errors` (array)
    List of errors

  - `errors.parameter` (string)
    The parameter in error, if applicable

  - `errors.correlationId` (string)
    The correlation identifier from the input

  - `errors.path` (string)
    The path to the field specifically in error, if applicable

  - `errors.field` (string)

  - `errors.code` (string)
    The field in error, if applicable

  - `errors.message` (string, required)
    The error code

## Response 500 fields (application/json):

  - `submissionId` (string)
    Submission identifier for issue investigation

  - `errors` (array)
    List of errors

  - `errors.parameter` (string)
    The parameter in error, if applicable

  - `errors.correlationId` (string)
    The correlation identifier from the input

  - `errors.path` (string)
    The path to the field specifically in error, if applicable

  - `errors.field` (string)

  - `errors.code` (string)
    The field in error, if applicable

  - `errors.message` (string, required)
    The error code