Application & Process Automation

Getting Started
Authentication & Access
Accounts with Multi-Factor Authentication
Using method GetPrograms
Common Usage Scenarios
Create and Submit a Project
Add/Change Data in an Existing Project
Daily Polling for Project Changes
Troubleshooting
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
V3 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
SetAssignee
URL Format
Sample Request
Request XML Attributes
Sample Response
Response XML Attributes
SetProjectOwner
URL Format
Sample Request
Request XML Attributes
Sample Response
Response XML Attributes
GetInquiryThreads – Admin Only
GetNotesInInquiryThread – Admin Only
SetInquiryNote – Admin Only
SetInquiryThreadStatus – Admin Only
SetInquiryThreadExternalId – Admin Only
SetProjectStatusReportAs – Admin only
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.
 
Please Note: When developing your API integration for PowerClerk, please ensure your code is as efficient as possible to avoid poor performance or API limit issues due to excessive API calls. in addition, please consider using incremental processing to only query projects that show changed data. For example, you could use the changed_since parameter with the GetProjects method to only receive a response with updated projects since the date selected instead of querying for the entire list of projects available in your PowerClerk program. This approach will greatly improve performance and reduce the number of API operations.
Making API Calls

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

For testing (sandboxes): https://api.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 60 operations per minute. Usage that exceeds this rate significantly will result in the calls being answered with a failure HTTP status code of 429 – “Too Many Requests” until enough time has passed for additional requests to be handled.
 

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.

If you want to automate API calls while using an account with MFA enabled, you will need a way to automatically generate either an MST or a TOTP to provide as the second authentication factor along with every API call. We recommend that you modify your API integration to do one of the following:

  1. Before every API call, generate a valid TOTP and pass that as the second authentication factor under the Mfa-One-Time-Password header.
  2. Before a set of API calls, generate a valid TOTP once and pass that as the second authentication factor to the CreateMfaSessionToken API in order to create an MST. Then for subsequent requests, provide that MST as the second authentication factor under the Mfa-Session-Token header. This option may make sense in cases where the API is going to perform several requests in a short amount of time, since the MST will expire after the period of time specified on creation.

In both of these cases, your API integration needs a way to programmatically generate a valid TOTP. TOTPs are calculated based on a standard algorithm, where the only inputs are the “MFA Secret” and the current time. The MFA Secret is generally a string of random text. In PowerClerk, the MFA Secret is visible underneath the QR code when you first set up MFA for your account. When you set up MFA on your PowerClerk account by scanning that QR code with an authenticator application such as Google Authenticator, that app is using the standard TOTP algorithm and the Secret to generate the TOTPs you see in the app. You can either implement the TOTP algorithm yourself in your API code, or use an existing open source library to do so. While we cannot recommend specific libraries, you can find various options by doing a web search for “TOTP algorithm” along with the programming language of your API integration. Make sure that however you choose to implement your “TOTP generator,” it is critical that you store the MFA Secret securely. Unlike TOTPs, the MFA Secret never changes unless you disable and re-enable MFA for the account. If that Secret is obtained by a bad actor who also knows the account password, they may be able to access your PowerClerk account.
 

Using method GetPrograms

In general, most API usage scenarios begin with a call to GetPrograms 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
The response will list all the programs you can interact with via PowerClerk’s API. The response will also return the AgencyId value, which can be optionally used with the GetPrograms method to filter programs per AgencyId as follows:
Sample call to GetPrograms filtered by AgencyId: https://{BaseURL}/Programs?AgencyId=FN7635MW
The AgencyId value shown in this example (FN7635MW) should of course be replaced by the the value of the AgencyId you wish to filter by.

What’s Next?