Application & Process Automation

Getting Started
Authentication & Access
Agency and Program Information
Common Usage Scenarios
Create and Submit a Project
Add/Change Data in an Existing Project
Daily Polling for Project Changes
Using Custom IDs
API Method Reference
GetPrograms
URL Format
Response
XML Attributes
Sample Code
GetForms
URL Format
Response
Forms Attributes
AvailableInStatuses and LeadsToStatus
Status Attributes
Sample Code
GetFormSchema
V1 Response
V2 Response
Sample Code
GetProjects
V1 Response
V2 Response
Sample Code
GetProjectsByNumber
V1 Response
V2 Response
Sample Request
Sample Code
GetProjectsByData
Sample Request
Request XML Nodes and Attributes
V1 Response
V2 Response
CreateNewProject
Sample Response
Response XML Attributes
Sample Code
GetAllProjectData - Admin only
Sample Response
XML Attributes
Sample Code
GetProjectData
Sample Response
XML Attributes
Sample Code
SetProjectData
Sample Request
Request XML Attributes
Sample Response
Response XML Attributes
Sample Code
GetActiveAttachment
Sample Code
URL Format
GetAttachmentAsAdmin – Admin only
URL Format
SetProjectAttachment
Identifying attachment file types
URL Format
Sample Response
Response XML Attributes
Sample Code
SetAttachmentMetadata
Sample Request
Request XML Attributes
Sample Response
Response XML Attributes
Sample Code
GetAttachmentMetadata
URL Format
Sample Response
Response XML Attributes
Sample Code
SubmitProject
URL Format
Sample Response
Response XML Attributes
Sample Code
GetStatusList – Admin only
URL Format
Sample Response
Response XML Attributes
Sample Code
GetProjectStatusHistory – Admin only
URL Format
Sample Response
Response XML Attributes
Sample Code
SetProjectStatus – Admin only
URL Format
Sample Response
Response XML Attributes
Sample Code
GetExportProject – Admin only
URL Format
Sample Response
Response XML Attributes
Sample Code
Code Samples
EncodeAuthorizationHeader
MakeGetRequest
MakePostRequest
MakeGetFileRequest
PowerShell

Getting Started

The PowerClerk® API allows programmatic access to basic PowerClerk functions, including project creation, editing, and submission as well as getting attachments and approving/rejecting those. These API methods mirror the functionality of the PowerClerk web interface for working with projects.
 
This documentation assumes basic familiarity with the PowerClerk web interface.

Making API Calls

API calls are restricted to HTTPS using TLS 1.1 or later. Calls using HTTP or TLS v1.0 are not allowed by the service.
 
The BaseURL referenced below is determined as follows:
 

For testing (sandboxes): https://cleanpowerdemo.com/PCITrial/Services.svc/v1
Production: https://api.powerclerk.com/Services.svc/v1

 

Authentication & Access

 

API Key

Each user with authorized access to the PowerClerk API will receive an API key that must be sent with every request. API keys are issued and administered by Clean Power Research.
 
To send the API key, set the following request header.
Header name: X-ApiKey
Header value: <APIKey>
 

User Authentication

Upon submitting your request, you will be prompted by Basic Authentication for your PowerClerk login credentials. Please enter the same email address and password you use to access the PowerClerk web interface.
 
To bypass the step of manually entering your credentials with every request, set the following request header.
Header name: Authorization
Header value: Basic <EncodedCredentials>
 
See the section below for information about encoding user credentials.
 

Encoding User Credentials

User credentials are encoded using ISO 8859-1 in the format “username:password”.
 
See chapter Code Samples for sample code that programmatically performs the encoding.
 

Operation Rate Limit

When calling the API, users are limited to a rate of 30 operations per minute. Usage that exceeds this rate will result in automatic throttling wherein a “sleep” time will be introduced between API operations until users are back within the limit.
 

Agency and Program Information

 

The AgencyId Value

Your entry point into the API will be through a specific agency (e.g. NVEnergy, SCE, or PGE). Clean Power Research issues each agency a unique, static AgencyId that enables API access to that agency’s PowerClerk data, including programs, forms, projects, statuses.
 
You will receive the AgencyId for your affiliated organization at the same time you receive your personal API key from Clean Power Research.
 

Obtaining Program Information Using the AgencyId

In general, most API usage scenarios begin with a call to GetPrograms – passing the AgencyId as a parameter – to obtain information about the program you’d like to work with. From there, other API methods can be used to obtain information about the program’s forms, projects, and statuses.
 

Sample call to GetPrograms:
https://{BaseURL}/Programs?Agency=FN7635MW

What’s Next?