API reference overview for Environmental Credit Service

Important

Some or all of this functionality is available as part of a preview release. The content and the functionality are subject to change. You can access the Environmental Credit Service (preview) sandbox environment for a 30-day trial. To use Environmental Credit Service (preview) in a production environment, complete the Environmental Credit Service (preview) sign up form.

This article helps you to perform tasks with the Environmental Credit Service REST APIs. To see the full API reference, go to Environmental Credit Service API reference. You can find the Swagger file at Environmental Credit Service REST APIs.

• Register projects
• Process claims
• Issue credits
• List credits
• Manage credits
• Set emission goals
• Track emissions
• Retire credits
• Manage files

Register projects

This section shows you how to create, submit, and review ecological projects via APIs. For instructions on using the user interface, go to Register projects in Environmental Credit Service.

• Create a project
• Save and submit a project
• View a project
• Approve or reject a proposal
• Delete a file
• Return a proposal for edits
• Register additional modular benefit projects
• Review a modular benefit project

Create a project

To upload and attach files at the time of project creation:

1. Upload files using the POST/files. Specify the following details in the API:

   • File or file URL
   • Descriptive tag for the file

2. Create the ecological project and corresponding modular benefit project and specify the fileID that's returned in the response of the POST/files API call as an attribute in the project creation API request body: POST/ecoprojects.

Save and submit a project

Fetch the details of the project:

   GET/ecoProjects/{ecoProjectId}

View the list of files (and their associated metadata) attached to the modular benefit project:

   GET/ecoprojects/{ecoProjectId}/mbps/{mbpId}

Download a file using the fileID that is available as part of the file metadata:

   GET/files/{fileId}

Add files to the modular benefit project:

   POST/files

Specify the modular benefit project's resource URI in the request body.

Submit modular benefit project for registration by submitting MBPRegister proposal:

   POST/proposals

View a project

Fetch all the proposals:

   GET/proposals

Fetch details of a specific proposal:

   GET/proposals/{proposalId}

Fetch details of a specific ecological project:

   GET/ecoProjects/{ecoProjectId}

Fetch details of the specific MBP to review:

   GET/ecoProjects/{ecoProjectId}/mbps/{mbpId}

Get the list of files (and the associated metadata) attached to the modular benefit project:

   GET/ecoprojects/{ecoProjectId}/mbps/{mbpId}

Download the files using the fileId that is available as part of the previous API response:

   GET/files/{fileId}

Attach a file to the modular benefit project:

   POST/files

Approve or reject a proposal

Upload files (if any):

POST/files and specify File (or FileUrl) and tag details

Reject the registration request:

POST/proposals/{proposalId}/action and specify the following details in the request body

• Action: Reject

• Message: Specify a comment (if any) that you want to provide for rejecting the registration.

• FileIDs: Specify the file IDs of the files that were uploaded.

Delete a file

View the list of files that are attached to the modular benefit project:

   GET/ecoprojects/{ecoProjectId}/mbps/{mbpId}

Identify the file that you have uploaded, because a user can delete only those files that they have uploaded.

Delete the file:

   DELETE/files/{fileId}

Return a proposal for edits

If there are some gaps or incorrect details in the project attributes or files that you want the supplier to correct or add, you can ask for edits on the project.

1. Upload files, if any, that must be shared with the supplier:

   POST/files

2. Move the MBPRegister proposal to submitterActionNeeded state by taking returnForEdits action using the POST/proposals/{proposalId}/action API and specify the following details in the request body:

   • Action: returnForEdits

   • Message: Specify a comment (if required) for supplier’s reference while returning the request for edits.

   • File IDs: Specify the file ID of the uploaded file here to attach the file to the concerned modular benefit project.

   After this is done, the modular benefit project moves to returnedForEdits state.

Suppliers can now view the proposal that was sent back for edits. They can now edit the modular benefit project attributes and upload more files to the modular benefit project.

• View proposal: GET/proposals/{proposalId}

• Upload and attach files to the modular benefit project: POST/files and specify the following details in the request body:

  • File or file URL
  • Tag: Descriptive file tag
  • ResourceURI: Specify resource URI of the respective modular benefit project.

• Update attributes of the modular benefit project

  • Get the updated modular benefit project details using the GET/ecoprojects/{ecoproject_id}/mbps/{mbp_id} and copy the Etag value from the response header.
  • Update the modular benefit project attributes using the PATCH/ecoprojects/{ecoproject_id}/mbps/{mbp_id} API and specify the Etag value in the If-Match key in the header.

After the changes are complete, the supplier can now submit the proposal back to the registry using the POST/proposals/{proposalId}/action API and specify the following details in the request:

• Action: Submit

• Message: Specify a comment (if any) for registry reference.

Register additional modular benefit projects

Submit the ecological benefit for registration to the issuing registry by creating and submitting an MBPRegister proposal:

   POST/proposal

Review a modular benefit project

View the proposal details:

   GET/proposals/{proposalId}

View the entire project details:

   GET/ecoProjects/{ecoProjectId}

View the details of the individual modular benefit project of the project:

   GET/ecoprojects/{ecoProjectId}/mbps/{mbpId}

Approve or reject the registration proposal, or return it for edits:

   POST/proposals/{proposalId}/action

Process claims

This section shows you how to process claims via APIs. For instructions on using the user interface, go to Process claims in Environmental Credit Service.

• Create claims
• Submit claims
• Verify claim
• Return claim request for edits
• Edit the returned proposal
• Withdraw the credit issuance request

Create claims

Create claim:

   POST/ecoprojects/{ecoProjectId}/mbps/{mbpId}/mbpClaims

Upload and attach files to claim checkpoints:

   POST/files

Specify the following details in the request:

• File or file URL
• Tag
• Resource URI of the claim

Submit claims

Create and submit the modular benefit projectClaimVerify proposal:

   POST/proposals

View details of the submitted proposal:

   GET/proposal/{proposalId}

View details of the claim:

   POST/ecoprojects/{ecoProjectId}/mbps/{mbpId}/mbpClaims/{mbpClaimId}

Verify claim

View proposals:

   GET/proposals

Fetch the details of a specific proposal:

   GET/proposals/{proposalId}

Fetch the details of a specific claim for which the verification proposal has been submitted:

   GET/ecoprojects/{ecoProjectId}/mbps/{mbpId}/mbpClaims/{mbpClaimId}

Accept the task of verifying the claim:

   POST/proposals/{proposalId}/action

List the files associated with a modular benefit project:

   GET/ecoprojects/{ecoProjectId}/mbps/{mbpId}

List the files associated with claim checkpoints:

   GET/ecoprojects/{ecoProjectId}/mbps/{mbpId}/mbpclaims/{claimId}/checkpoints

View a file attached to a specific asset:

   GET/files/{fileId}

Once the claim is accepted, a corresponding 'Processed claim' is created. Record your verification findings on the processed claim. This includes updating Quantity, Co benefits of the claim. Prior to submitting the credit issuance request, you must update the credit recommendations also on the processed claim:

• Get the processed claim details using the GET/processedClaims/{processed_claim_id} and copy the Etag value from the response header.
• Update the processed claim attributes using the PATCH/processedClaims/{processed_claim_id} API and specify the Etag value in the If-Match key in the header.

For each checkpoint that you verify, you can update your verification findings on the corresponding checkpoint result of the processed claim:

• Upload and attach your verification finding reports to the checkpoint result(s) of the processed claim using POST/files API and specify the File or file URL, Tag and ResourceUri (this will be checkpoint result's resource uri) in the request body.
• Update the environmental effect before and after attributes of the checkpoint result (if required):
  • Get the checkpoint result details using the GET/processedClaims/{processed_claim_Id}/checkpointResults/{checkpoint_result_Id} and copy the Etag value from the response header.
  • Update the checkpoint result's attributes using the PATCH/processedClaims/{processed_claim_Id}/checkpointResults/{checkpoint_result_Id} API and specify the Etag value in the If-Match key in the header.
  • You can also update the checkpoint results by using the patch API for processed claims.

Once verification is complete, approve or reject the MBPClaimVerify proposal:

   POST/proposals/{proposalId}/action

Specify the following details:

• Action: Approve or Reject

• Message: Specify a comment (if any) for supplier reference.

Once the MBPClaimVerify proposal is approved, Create and submit the CreditMint proposal to submit the credit issuance request:

   POST/proposals/

Return claim request for edits

If there are some gaps or incorrect details in the claim request that the Validation and Verification Body wants the supplier to correct, you can ask for edits on the claim request instead of approving or rejecting the request. This capability is available only via API.

1. Upload and attach files (that you want to share with the supplier) to the processed claim or to the checkpoint result of the processed claim: POST/files and specify the following details in the request body

   • File or file URL
   • Tag
   • Resource URI of the processed claim or checkpoint result of the processed claim to which the file must be added

2. Move the MBPClaimVerify proposal to submitterActionNeeded state by taking returnForEdits action using the POST/proposals/{proposalId}/action API and specify the following details in the request body:

   • Action: returnForEdits
   • Message: Specify a comment (if required) for supplier’s reference while returning the request for edits.

Edit the returned proposal

Suppliers can then view the proposal that was sent back for edits. They can now edit the claim and checkpoint attributes, and they can upload more files to the claim checkpoints:

1. View proposal: GET/proposals/{proposalId}

   • If required, supplier can also view the corresponding processed claim details using GET/processedClaims/{processed_claim_Id} API.

2. Upload and attach files (if any) to the claim checkpoints: POST/files and specify the following details in the request body

   • File or file URL
   • Tag
   • Resource URI of the checkpoint to which the file must be added

3. Update claim attributes using a PATCH operation:

   • Get the latest claim details and note the ETag value in the response header: GET/ecoprojects/{ecoproject_id}/mbps/{mbp_id}/mbpclaims/{mbpclaim_id}
   • Update the claim attributes and specify the Etag value in the ‘If-Match’ key of the request header: PATCH /ecoprojects/{ecoproject_id}/mbps/{mbp_id}/mbpclaims/{mbpclaim_id}

4. Update the claim’s checkpoint attributes using a PATCH operation:

   • Get the latest checkpoint details and note the ETag value in the response header: GET /ecoprojects/{ecoproject_id}/mbps/{mbp_id}/mbpclaims/{mbpclaim_id}/checkpoints/{mbpcheckpoint_id}

   • Update the claim attributes and specify the Etag value in the If-Match key of the request header: PATCH /ecoprojects/{ecoproject_id}/mbps/{mbp_id}/mbpclaims/{mbpclaim_id}/checkpoints/{mbpcheckpoint_id}

     Note

     While specifying the update attributes, ensure that the JSON request body follows the same structure as in the corresponding get API call.

5. After the modifications are done, the supplier can then submit the proposal back to the validation and verification body using POST/proposals/{proposalId}/action API and specify the following details in the request body:

   • Action: Resubmit
   • Message: Specify any comment (if required) for validation and verification body reference.

After the proposal is resubmitted, the Validation and Verification body can review the proposal and approve, reject, or again ask for edits.

Withdraw the credit issuance request

Option to withdraw the submitted credit issuance request (CreditMint)proposal:

After the credit issuance proposal is submitted to the registry, in case of any issues due to which you want to withdraw the submitted proposal, you can withdraw the submitted proposal if the registry has not acted upon the proposal. This capability is currently available only by APIs.

• Move the CreditMint proposal that is in submitted state to withdrawn state using POST/proposals/{proposalId}/action API and specify the following details in the request body:

  • Action: Withdraw
  • Message: Specify the reason (if any) for withdrawing the proposal for registry reference.

The status of the proposal is now Withdrawn.

After the credit issuance request is withdrawn, the validation and verification body can modify the ‘processed claim’ and the associated checkpoint results and then resubmit the credit issuance request.

• Upload and attach files to the processed claim’s checkpoint results: POST/files and specify the following details:

  • File or FileURL
  • Tag
  • ResourceURI of the associated checkpoint result.

• Update the attributes of the processed claim: PATCH/processedClaims/{processedClaim_Id}

• Resubmit the issuance request to the registry and specify the following details in the API request body: POST/proposals/{ proposal_id}/action

  • Action: Specify as Resubmit
  • Message: Specify a message/comment (if any) for registry reference

Issue credits

This section shows you how to view and issue credits via APIs. For instructions on using the user interface, go to Issue credits in Environmental Credit Service.

• Review proposals
• Approve credits
• Reject a proposal
• Return credit issuance request for edits
• View issued credits
• Search and view credits

Review credit issuance proposals

View the submitted ‘Token mint’ proposal and get the ‘processed claim’ resource URI that has been submitted for review :

GET/proposal/{proposalId}

Review the verification findings of the validation and verification body by viewing the processed claim and the associated checkpoint results (along with associated files):

GET/processedClaims/{processedClaims_Id} 

View the claim and corresponding checkpoint details (along with list of files attached by supplier for the checkpoints):

   GET/ecoprojects/{ecoProjectId}/mbps/{mbpId}/mbpClaims/{mbpClaimId}

View the modular benefit project details, along with the list of attached files:

   GET/ecoprojects/{ecoProjectId}/mbps/{mbpId}

Download a file using the file ID:

   GET/files/{fileId}

Approve credits

Upload files that you want to attach to the credit for issuance: POST/files and specify the following details in the request body:

• File or file URL
• Tag

Approve the proposal:

   POST/proposals/{proposalId}/action

Specify the following details in the request body:

• Action: specify as Mint
• Message: Specify the message (if any) for validation and verification body reference
• File IDs: Specify the file IDs of the uploaded files so that the files are attached to the issued credit
• Quantity
• Vintage
• Asset Id
• Determined value

Note

When the proposal is approved, a corresponding credit will be created.

Reject a proposal

Upload files (if any) to the processed claim: POST/files and specify the following details:

• File or file URL
• Tag

Reject the proposal:

   POST/proposals/{proposalId}/action

Specify the following details in the request body:

• Action: Reject
• Message: Specify a message (if any) for validation and verification body reference
• File IDs: Specify the file IDs of the uploaded file so that these are attached to the associated processed claim.

Return credit issuance request for edits

If there are gaps or incorrect details in the issuance request that you want the validation and verification body to correct, you can ask for edits on the issuance request. This capability is available only via API.

1. Upload files (if any) that you want to share with the validation and verification body as part sending the issuance request back for edits.

2. Move the issuance request (CreditMint proposal) to submitterActionNeeded state using POST/proposals/{proposalId}/action API and specify the following details:

   • Action: ReturnForEdits
   • Message: Specify a message (if any) for validation and verification body reference so that they can understand the reason for edit request.
   • File IDs: Specify the file IDs of the uploaded files (if any) so that the files are attached to the associated processed claim.

The validation and verification body can now view the proposal that has been sent back for edits. They can also now edit the corresponding processed claim and checkpoint results. They can update attributes as well as upload updated files to the checkpoint results.

If required, validation and verification body at this point can ask for clarifications on the verified claim by returning the claim for edits to the supplier. Once the supplier resubmits the claim, validation and verification body can review and verify the claim, update the corresponding processed claim and then resubmit the issuance request to the registry.

1. Upload and attach files to the checkpoint results: POST/files and specify the following details:

   • File or file URL
   • Tag
   • ResourceURI of the associated checkpoint results

2. Update the attributes of the processed claim including the credit recommendation: PATCH/processedClaim/{processed claim id}

3. Resubmit the issuance request and specify the details below in the API request body: POST/proposals/{ proposal_id}/action

   • Action: Resubmit
   • Message: Specify a message (if any) for registry reference

After the request is resubmitted, issuing registry can review the request and approve, reject, or again ask for edits.

View issued credits

   GET/credits

Search and view credits

Fetch all credits:

   GET/credits

Note

This API will return the list of all the credits. Buyers can then filter the list on their own based on credit status for viewing only listed credits.

View the credit details (including lineage) for a specific credit displayed in the list:

   GET/credits/{creditId}/lineage

List credits

This section shows you how to to list credits on a marketplace for trade via APIs. For instructions on using the user interface, go to List credits in Environmental Credit Service.

• Register as a buyer on a marketplace
• Submit proposal to list a credit
• Review proposal to list a credit

Register as a buyer or a marketplace

Submit the MarketplaceTraderRegister proposal as a credit owner or buyer:

   POST/proposals

Fetch and review all the MarketplaceTraderRegister proposals as a marketplace:

   GET/proposals

Approve or reject the proposals as a marketplace:

   POST/proposals/{proposalId}/action

Fetch and view all the traders registered on their platform as a marketplace:

   GET/marketplaces/{marketplaceId}/traders

Submit proposal to list a credit

Create and submit MarketplaceListingRegister proposal:

   POST/proposals

Review proposal to list a credit

   GET/proposals

   POST /proposals/{proposalId}/action

Manage credits

This section shows you how to manage credits via APIs. For instructions on using the user interface, go to Manage credits in Environmental Credit Service.

• Delist a credit
• Transfer ownership
• View credit lineage
• Split a credit
• Transfer credit listing

Delist a credit

Splitting a credit is an independent operation in Environmental Credit Service. For information about splitting a credit via API, go to Split a credit. After the credit splits, you can continue with the next step.

Create and submit MarketplaceListingDeregister proposal:

   POST/proposals

View all the MarketplaceListingDeregister proposals submitted for review:

   GET/proposals

To approve or reject the proposal:

   POST/proposals/{proposalId}/action

Transfer ownership

   POST/credits/{creditId}/transfer/

View credit lineage

Organizations with supplier and registry roles can view the credit lineage for the credits they own or have issued:

   GET/credits/{creditId}/lineage

Split a credit

You can split a credit into child credits. This functionality is currently available only via API.

Split the credit by specifying the quantities (in mtCO2e) for at least two child credits as a credit owner (for the credits they own) or as a marketplace (for the credits listed on their platform):

   POST/credits/{creditId}/split

Transfer credit listing

A marketplace can transfer a credit listing from their platform to another marketplace. This transfer is also known as transfer of encumbrance. In the traditional flow, a supplier would list the credits on a marketplace that will help with demand, clearing, and settlement. Sometimes a marketplace might not be able to perform the payment clearing and settlement on its own and might depend on a different platform to perform it. In this case, the asset must be transferred to the new marketplace to complete the transaction. This feature is currently available only via APIs.

As a marketplace, create and submit the MarketplaceListingTransfer proposal for a credit listed on your platform:

   POST/proposals

As an approver marketplace, view all the MarketplaceListingTransfer proposals submitted to them for review:

   GET/proposals

As an approver marketplace, approve or reject the proposal. If the proposal is approved, then the credits encumbrance is transferred from initial marketplace to the approver marketplace:

   POST/proposals/{proposalId}/action

Partial transfer of encumbrance: A marketplace can transfer encumbrance for partial credit by first splitting the credit as an independent action. For information about how to split a credit, go to Split a credit. After the credit is split, continue with the above steps for transfer of encumbrance for child credits.

Set emission goals

This section shows you how to set up emission reduction goals and targets via APIs.

• Create emission goals
• View emission goals

Create emission goals

   POST/esgs

View emission goals

   GET/esgs

Track emissions

This section shows you how to track your emissions against the emission scorecard you set via APIs. For instructions on using the user interface, go to Track emission goals in Environmental Credit Service.

• Create milestones for specific reporting period
• Track actual emissions against the milestone

Create milestones for specific reporting period

   POST/esgs/{esgScorecardId}/milestones

Fetch all the milestones:

   GET/esgs/{esgScorecardId}/milestones

Fetch specific milestone:

   GET/esgs/{esgScorecardId}/milestones/{esgMilestoneId}

Track actual emissions against the milestone

   POST/esgs/{esgScorecardId}/milestones/{esgMilestoneId}/reportingPeriods/{esgReportingPeriodId}/emissions

   GET/esgs/{esgScorecardId}/milestones/{esgMilestoneId}/reportingPeriods/{esgReportingPeriodId}

Retire credits

This section shows you how to offset excess emissions by retiring owned carbon credits via APIs. For instructions on using the user interface, go to Retire credits in Environmental Credit Service.

• Submit credit retirement proposal
• Review credit retirement proposal
• Partial credit retirement

Submit credit retirement proposal

Create and submit ESGEmissionOffset proposal:

   POST/proposals

Buyers can also retire carbon credit directly without specifying the emissions to offset. This functionality is available only via API.

Create and submit CreditRetire proposal:

   POST/proposals

Review credit retirement proposal

   GET/proposals

   GET/proposals/{proposalId}

Attach file to the credit that is being reviewed for retirement:

   POST/files

   POST/proposals/{proposalId}/action

Partial credit retirement

For information about splitting a credit via API, go to Split a credit.

After the credit is split, use the APIs in previous steps for offset and retirement.

Manage files

This section shows you how to attach, view, and delete files for assets like project, claim, and credits via APIs. For instructions on using the user interface, go to Manage files in Environmental Credit Service.

• Attach files
• View files
• Delete files

Attach files

Use the POST/files API to attach a file to an asset. You need to specify the following details:

• File or file URI
• Resource URI of the asset
• Descriptive tag for the file

View files

View the list of files along with file properties for an asset using the asset details API:

Modular benefit project:

   GET/ecoprojects/{ecoProjectId}/mbps/{mbpId}

Claims:

   GET/ecoprojects/{ecoProjectId}/mbps/{modular benefit projectId}/mbpClaims/{mbpClaimId}

Claim checkpoints:

   GET/ecoprojects/{ecoProjectId}/modular benefit projects/{mbpId}/mbpClaims/{mbpClaimId}/checkpoints

Credit:

   GET/credits/{creditId}

Use the file ID present in the file properties of the file to download the file:

   GET/files/{fileId}

Delete files

Use the file ID of the file to call the delete API:

   DELETE/files/{fileId}

See also

Environmental Credit Service overview
Configure Environmental Credit Service
Environmental Credit Service glossary