Skip to content
NAR Registry
/
OpenAPI Specs
/
/
Certificate Holdings

NAR Registry Client API (1.0.0)

This API is used for retrieving and transacting NAR Monthly vintage certificates. APIs require an OAuth Authentication token. To create API credentials, see Creating an API Login.

Download OpenAPI description
nar.client.v1.openapi.json
nar.client.v1.openapi.yaml
Overview
E-mail
nar@apx.com
Languages
Servers
Generated server url
https://narenewables2.apx.com/ClientAPI/

account

Account Information

Operations

ledger

Ledger Operations

Operations

Inter-Account Transfers

Request

Initiate certificate transfers to other registry account holders. Transfers must then be confirmed by the counterparty.

Security
JWT
Query
onBehalfOfAccountIdstring

Account id for which the request is being made: defaults to the primary account id of the requester unless specified

Bodyapplication/jsonrequired
requestsArray of objects(InteraccountTransferRequest)

List of requests

curl -i -X POST \
  'https://narenewables2.apx.com/ClientAPI/api/ledger/transfer?onBehalfOfAccountId=string' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "requests": [
      {
        "correlationId": "1",
        "certificateSerialNumberRange": "NAR-REC-1234-CA-06-2024-555555-1 to 66",
        "quantity": 55,
        "transfereeId": "77"
      }
    ]
  }'

Responses

OK

Bodyapplication/json
submissionIdstringrequired

Submission identifier for issue investigation

Example: "1"
responsesArray of objects(InteraccountTransferResponse)

List of responses

Response
application/json
{
  "submissionId": "1",
  "responses": [
    { … }
  ]
}

Pending Transfer Actions

Request

Perform actions on pending transfers of monthly certificates between accounts (either incoming or outgoing). Note that actions for incoming and outgoing transfers can be included in the same submission.

Security
JWT
Query
onBehalfOfAccountIdstring

Account id for which the request is being made: defaults to the primary account id of the requester unless specified

Bodyapplication/jsonrequired
requestsArray of objects(PendingTransferActionRequest)

List of requests

curl -i -X POST \
  'https://narenewables2.apx.com/ClientAPI/api/ledger/transfer/pending/action?onBehalfOfAccountId=string' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "requests": [
      {
        "correlationId": "1",
        "transferId": "5678",
        "action": "CONFIRM",
        "subaccountId": "77"
      }
    ]
  }'

Responses

OK

Bodyapplication/json
submissionIdstringrequired

Submission identifier for issue investigation

Example: "1"
responsesArray of objects(PendingTransferActionResponse)

List of responses

Response
application/json
{
  "submissionId": "1",
  "responses": [
    { … }
  ]
}

SubAccount Transfers

Request

Initiate transfers of monthly certificates to other sub-accounts within an account.

Security
JWT
Query
onBehalfOfAccountIdstring

Account id for which the request is being made: defaults to the primary account id of the requester unless specified

Bodyapplication/jsonrequired
requestsArray of objects(SubaccountTransferRequest)

List of requests

curl -i -X POST \
  'https://narenewables2.apx.com/ClientAPI/api/ledger/subaccountTransfer?onBehalfOfAccountId=string' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "requests": [
      {
        "correlationId": "1",
        "certificateSerialNumberRange": "NAR-REC-1234-CA-06-2024-555555-1 to 66",
        "quantity": "55",
        "subaccountId": "77"
      }
    ]
  }'

Responses

OK

Bodyapplication/json
submissionIdstringrequired

Submission identifier for issue investigation

Example: "1"
responsesArray of objects(SubaccountTransferResponse)

List of responses

Response
application/json
{
  "submissionId": "1",
  "responses": [
    { … }
  ]
}

Retirements

Request

Initiate retirements of monthly certificates within an account.

Security
JWT
Query
onBehalfOfAccountIdstring

Account id for which the request is being made: defaults to the primary account id of the requester unless specified

Bodyapplication/jsonrequired
requestsArray of objects(RetireRequest)

List of requests

curl -i -X POST \
  'https://narenewables2.apx.com/ClientAPI/api/ledger/retire?onBehalfOfAccountId=string' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "requests": [
      {
        "correlationId": "1",
        "certificateSerialNumberRange": "NAR-REC-1234-CA-06-2024-555555-1 to 66",
        "quantity": "55",
        "subaccountId": "77",
        "isPublic": true,
        "retirementTypeCode": "GRN",
        "retirementReasonCode": "22",
        "countrySubdivisionCode": "CA",
        "retirementYear": 2024,
        "notificationName": "John Doe",
        "notificationEmail": "jdoe@acmecorp.com",
        "additionalDetails": "Voluntary Retirement for Acme Corp.",
        "retirementCertificateType": "SINGLE"
      }
    ]
  }'

Responses

OK

Bodyapplication/json
submissionIdstringrequired

Submission identifier for issue investigation

Example: "1"
responsesArray of objects(RetireResponse)

List of responses

Response
application/json
{
  "submissionId": "1",
  "responses": [
    { … }
  ]
}

Certificate Holdings

Request

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.

Security
JWT
Query
accountIdsArray of strings

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

vintageStartstring(date-time)

Vintage start (inclusive)

vintageEndstring(date-time)

Vintage end (exclusive)

subaccountTypeCodestring

Subaccount type code. If not specified, holdings will be returned regardless of status.

$filterstring

OData-like filter expression

$orderbystring

Comma-separated list of columns for sorting

$skipinteger(int32)

Number of records to skip

$topinteger(int32)

Maximum number of records to return

$applystring

OData-like apply expression with groupby and aggregate only

curl -i -X GET \
  'https://narenewables2.apx.com/ClientAPI/api/ledger/holding?accountIds=string&vintageStart=2019-08-24T14%3A15%3A22Z&vintageEnd=2019-08-24T14%3A15%3A22Z&subaccountTypeCode=string&%24filter=string&%24orderby=string&%24skip=0&%24top=0&%24apply=string' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Success

Bodyapplication/json
@countinteger(int32)
valueArray of objects(Holding)required
value[].​accountIdstringrequired

The account identifier

Example: "55"
value[].​notificationNamestringrequired

The name of the beneficial owner of a retirement

Example: "John Doe"
value[].​notificationEmailstringrequired

The email address of the beneficial owner of a retirement

Example: "jdoe@acmecorp.com"
value[].​certificateSerialNumberRangestringrequired

The certificate serial number range

Example: "NAR-REC-1234-CA-06-2024-555555-1 to 66"
value[].​certificateStatusstring

The certificate status - Active, Pending, Retired

Example: "RETIRED"
value[].​countryIso2Codestringrequired

The country to which resource belongs as an ISO-2 code

Example: "US"
value[].​fuelTypeCodestringrequired

The fuel type code: see documentation for possible values

Example: "H2O"
value[].​fuelTypeDescriptionstringrequired

The fuel type description

Example: "Hydroelectric Water"
value[].​quantitynumberrequired

The holding quantity

Example: 66
value[].​resourceNamestringrequired

The resource name

Example: "Acme Hydro"
value[].​resourceProgramAssignedIdentifierstringrequired

The resource identifier

Example: "GEN1234"
value[].​retirementDatestring(date-time)

The date the holding was retired

Example: "2024-10-06T22:38:15.08Z"
value[].​retirementDetailsstring

Additional retirement details

Example: "Retired of behalf of John Doe"
value[].​retirementReasonCodestring

The retirement reason code: see documentation for possible values

Example: "22"
value[].​retirementReasonDescriptionstring

The retirement reason description

Example: "REC-Only Product"
value[].​retirementComplianceStatestring

The State chosen for the retirement. (ISO 3166-2 code)

Example: "CA"
value[].​retirementYearinteger(int32)

The retirement year

Example: 2024
value[].​retirementTypeCodestring

The retirement type code: see documentation for possible values

Example: "GRN"
value[].​retirementTypeDescriptionstring

The retirement type description: see documentation for possible values

Example: "Green-e Energy Voluntary Market"
value[].​subaccountTypestring

The subaccount type code: see documentation for possible values

Example: "RET"
value[].​subaccountIdstring

The subaccount identifier

Example: "321"
value[].​subaccountNamestring

The subaccount name

Example: "Green-e Retirements 2024"
value[].​vintageMonthstringrequired

The vintage month (rendered as an ISO-8601 date)

Example: "06/2024"
value[].​eligibilitiesstring

a comma-delimited list of eligibility codes: see documentation for possible values

Example: "CRS Listed"
totalCountinteger(int32)
countExceededbooleanrequired
Response
application/json
{
  "@count": 0,
  "value": [
    { … }
  ],
  "totalCount": 0,
  "countExceeded": true
}

Pending Transfers

Request

Retrieve the list of all pending monthly certificate intra-registry transfers for Monthly vintage certificates for an account/accounts. Results do not include pending imports or export.

Security
JWT
Query
accountIdsArray of strings

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

directionstring

Transfer direction

Enum"I""O"
$filterstring

OData-like filter expression

$orderbystring

Comma-separated list of columns for sorting

$skipinteger(int32)

Number of records to skip

$topinteger(int32)

Maximum number of records to return

$applystring

OData-like apply expression with groupby and aggregate only

curl -i -X GET \
  'https://narenewables2.apx.com/ClientAPI/api/ledger/transfer/pending?accountIds=string&direction=I&%24filter=string&%24orderby=string&%24skip=0&%24top=0&%24apply=string' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Success

Bodyapplication/json
@countinteger(int32)
valueArray of objects(PendingTransfer)required
value[].​accountIdstringrequired

The account identifier

Example: "55"
value[].​certificateSerialNumberRangestringrequired

The certificate serial number range

Example: "NAR-REC-1234-CA-06-2024-555555-1 to 66"
value[].​dateInitiatedstring(date-time)required

The date the transfer was initiated

Example: "2024-10-06T22:38:15.08Z"
value[].​directionstringrequired

The transfer direction: I=Incoming, O=Outgoing

Enum"I""O"
Example: "O"
value[].​eligibilitiesstring

a comma-delimited list of eligibility codes: see documentation for possible values

Example: "CRS Listed"
value[].​fuelTypeCodestringrequired

The fuel type code: see documentation for possible values

Example: "H2O"
value[].​resourceNamestringrequired

The resource name

Example: "Acme Hydro"
value[].​resourceProgramAssignedIdentifierstringrequired

The resource identifier

Example: "GEN1234"
value[].​countrySubdivisionCodestring

State or Province that the resource is located in (ISO 3166-2 code)

Example: "CA"
value[].​notesstring

notes

Example: "For contract XYZ"
value[].​quantitynumberrequired

The transfer quantity

Example: 66
value[].​transfereeIdstringrequired

The transferee (buyer) account identifier

Example: "77"
value[].​transferIdstringrequired

The transfer identifier

Example: "5678"
value[].​transferorIdstringrequired

The transferor (seller) account identifier

Example: "55"
value[].​vintageMonthstringrequired

The vintage month (rendered as an ISO-8601 date)

Example: "06/2024"
totalCountinteger(int32)
countExceededbooleanrequired
Response
application/json
{
  "@count": 0,
  "value": [
    { … }
  ],
  "totalCount": 0,
  "countExceeded": true
}

subaccount

Subaccount Operations

Operations

system

System Information

Operations