Getting Started

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:
 

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.