Application & Process Automation

Getting Started
Authentication & Access
Accounts with Multi-Factor Authentication
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
URL Format
Sample Code
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
Sample Code
URL Format
Sample Response
Response XML Attributes
GetCustomListChoices
URL Format
Sample Response
Response XML Attributes
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
Response XML Attributes
Sample Code
URL Format
Sample Response
CreateMfaSessionToken
URL Format
Sample Request
Request XML Attributes
Sample Response
Response XML Attributes
Sample Code
DeleteMfaSessionToken
URL Format
Sample Response
Sample Code
Code Samples
EncodeAuthorizationHeader
MakeGetRequest
MakePostRequest
MakeGetFileRequest
MakeDeleteRequest
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.
 

Accounts with Multi-Factor Authentication

If you have enabled Multi-Factor Authentication (MFA) on your PowerClerk account, you will be required to provide a second form of authentication when making API requests. You can do so by providing either a MFA Time-based-One-Time-Password (TOTP) from an authenticator application, just as you are required to do when signing into an MFA-protected account via the PowerClerk UI, or by providing an MFA Session Token (MST). While TOTPs remain valid only for a 30-second interval, MSTs offer greater flexibility since you can create and manage them yourself via the PowerClerk UI (My Account > Manage API Credentials), and you can configure the amount of time for which you would like them to remain valid, which can be anywhere from one minute to one day. Both forms of authentication will be accepted as a valid second factor for any API request.*
 
Providing an MFA Session Token as a second authentication factor:
Header name: Mfa-Session-Token
Header value: <Token value>
 
Providing an MFA Time-based-One-Time-Password as a second authentication factor:
Header name: Mfa-One-Time-Password
Header value: <6-digit code from authenticator application>
 
*The one exception to this is the CreateMfaSessionToken request, which only accepts a TOTP for authentication. If this request accepted an MST for authentication, it would be possible to effectively extend the expiration time of an MST indefinitely using only an existing MST. This would undermine the restriction that MSTs can only remain valid for up to one day.
 

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?