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

GetProjects

Retrieves a list of projects associated with the given program that are read-accessible to the user.
 
HTTP verb: GET
Required inputs: ProgramId
Optional inputs: changed_since (timestamp), version (integer)
 

Path Parameters
Path parameter Description
ProgramId The ID of the program in which you want to look up Projects for.

 

Query string parameters
Name Data Type Required/Optional Description
changed_since Timestamp Optional If the optional “changed_since” parameter is included, the call retrieves only the projects that have been updated after the timestamp value of the parameter.
 
The following are acceptable timestamp formats for the changed_since parameter.
 
yyyy-MM-dd (ex. 2014-10-20)
yyyy-MM-ddTHH:mm:sszzz (ex. 2014-10-22T00:26:26-07:00)
yyyy-MM-ddTHH:mm:ss:fffffffzzz (ex. 2014-10-24T10:00:15.6487539-07:00 or 2014-10-22T23:00:28.6263508%2B00:00)
 
Note: Please replace “+” with “%2B” instead in timezone specifications
version Integer Optional If the optional “version” parameter is set format the data to that version. If the “version” parameter is not included the API will default to use Version 1.

The version parameter allows the PowerClerk API to expand and grow as the product grows while keeping the API backwards compatible. The following are acceptable values for the version parameter.
 

Version Content in the version
1 Default content
2 Includes the StatusPublicId and StatusCustomId

URL Format

Format: https://{BaseURL}/Programs/{ProgramId}/Projects?changed_since={changed_since}&version={VersionNumber}
 
Samples: https://{BaseURL}/Programs/1HF29X4P/Projects?changed_since=2014-10-24&version=2
https://{BaseURL}/Programs/1HF29X4P/Projects?version=2
https://{BaseURL}/Programs/1HF29X4P/Projects?changed_since=2014-10-24T10:00:15.6487539-07:00
https://{BaseURL}/Programs/1HF29X4P/Projects?version=2&changed_since=2014-10-24T10:00:15.6487539-07:00

Version 1 Response


<ProjectsResponse RequestTimestamp="2014-10-24T17:00:15.6487539+00:00">
    <Projects>
        <Project ProjectId="R4NC48YU" ProgramId="1HF29X4P" ProjectNumber="TEST-00001" Status="Set Meter Request Pending" StatusTimestamp="2014-09-05T13:34:39-07:00" LastChangeTimestamp="2014-10-15T09:07:15-07:00"/>
        <Project ProjectId="AK6ZP5H9" ProgramId="1HF29X4P" ProjectNumber="TEST-00004" Status="Application in Process" StatusTimestamp="2014-10-10T14:15:04-07:00" LastChangeTimestamp="2014-10-10T14:15:23-07:00"/>
        <Project ProjectId="54X25DK7CB" ProgramId="1HF29X4P" ProjectNumber="TEST-00003" Status="Application in Process" StatusTimestamp="2014-10-03T16:22:09-07:00" LastChangeTimestamp="2014-10-03T16:22:08-07:00"/>
        <Project ProjectId="9RZ2BR69UP" ProgramId="1HF29X4P" Status="Unsubmitted" StatusTimestamp="2014-10-17T13:09:05-07:00" LastChangeTimestamp="2014-10-17T13:09:09-07:00"/>
        <Project ProjectId="F8ZK6BK2CU" ProgramId="1HF29X4P" Status="Unsubmitted" StatusTimestamp="2014-10-21T14:22:13-07:00" LastChangeTimestamp="2014-10-21T14:59:40-07:00"/>
    </Projects>
</ProjectsResponse>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="http://service.powerclerk.com/api/v1/">
  <xs:element name="ProjectsResponse">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="Projects">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="Project" maxOccurs="unbounded" minOccurs="0">
                <xs:complexType>
                  <xs:simpleContent>
                    <xs:extension base="xs:string">
                      <xs:attribute type="xs:string" name="ProjectId" use="required"/>
                      <xs:attribute type="xs:string" name="ProgramId" use="required"/>
                      <xs:attribute type="xs:string" name="ProjectNumber" use="optional"/>
                      <xs:attribute type="xs:string" name="Status" use="required"/>
                      <xs:attribute type="xs:dateTime" name="StatusTimestamp" use="required"/>
                      <xs:attribute type="xs:dateTime" name="LastChangeTimestamp" use="required"/>
                    </xs:extension>
                  </xs:simpleContent>
                </xs:complexType>
              </xs:element>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
      <xs:attribute type="xs:float" name="SchemaVersion"/>
      <xs:attribute type="xs:dateTime" name="RequestTimestamp"/>
    </xs:complexType>
  </xs:element>
</xs:schema>

Response XML Attributes

<ProjectsResponse> Attributes

RequestTimestamp – Timestamp of when the request was made. This values is always converted to UTC. (All other timestamps returned by the API are converted to the program’s local timezone.)

<Project> Attributes

ProjectId – Unique identifier for the project
ProgramId – Unique identifier for the program
ProjectNumber – The project number. Projects are assigned a project number when they have been submitted.
Status – Current status of the project
StatusTimestamp – Timestamp of when the project entered the current status. Converted to user’s local timezone.
LastChangeTimestamp – Timestamp of the last change made to the project. Converted to user’s local timezone.

Version 2 Response


<ProjectsResponse RequestTimestamp="2014-10-24T17:00:15.6487539+00:00">
    <Projects>
        <Project ProjectId="R4NC48YU" ProgramId="1HF29X4P" ProjectNumber="TEST-00001" Status="Set Meter Request Pending" StatusTimestamp="2014-09-05T13:34:39-07:00" LastChangeTimestamp="2014-10-15T09:07:15-07:00" StatusPublicId=”93JH4U3Z”/>
        <Project ProjectId="AK6ZP5H9" ProgramId="1HF29X4P" ProjectNumber="TEST-00004" Status="Application in Process" StatusTimestamp="2014-10-10T14:15:04-07:00" LastChangeTimestamp="2014-10-10T14:15:23-07:00" StatusPublicId="SE0BU2DG" />
        <Project ProjectId="54X25DK7CB" ProgramId="1HF29X4P" ProjectNumber="TEST-00003" Status="Application in Process" StatusTimestamp="2014-10-03T16:22:09-07:00" LastChangeTimestamp="2014-10-03T16:22:08-07:00" StatusPublicId="SE0BU2DG" />
        <Project ProjectId="9RZ2BR69UP" ProgramId="1HF29X4P" Status="Unsubmitted" StatusTimestamp="2014-10-17T13:09:05-07:00" LastChangeTimestamp="2014-10-17T13:09:09-07:00" StatusCustomId="CustomStatusId" StatusPublicId="3X8KK600" />
        <Project ProjectId="F8ZK6BK2CU" ProgramId="1HF29X4P" Status="Unsubmitted" StatusTimestamp="2014-10-21T14:22:13-07:00" LastChangeTimestamp="2014-10-21T14:59:40-07:00" StatusCustomId="CustomStatusId" StatusPublicId="3X8KK600" />
    </Projects>
</ProjectsResponse>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="http://service.powerclerk.com/api/v1/">
  <xs:element name="ProjectsResponse">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="Projects">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="Project" maxOccurs="unbounded" minOccurs="0">
                <xs:complexType>
                  <xs:simpleContent>
                    <xs:extension base="xs:string">
                      <xs:attribute type="xs:string" name="ProjectId" use="required"/>
                      <xs:attribute type="xs:string" name="ProgramId" use="required"/>
                      <xs:attribute type="xs:string" name="ProjectNumber" use="optional"/>
                      <xs:attribute type="xs:string" name="Status" use="required"/>
                      <xs:attribute type="xs:string" name="StatusCustomId" use="required"/>
                      <xs:attribute type="xs:string" name="StatusPublicId" use="required"/>
                      <xs:attribute type="xs:dateTime" name="StatusTimestamp" use="required"/>
                      <xs:attribute type="xs:dateTime" name="LastChangeTimestamp" use="required"/>
                    </xs:extension>
                  </xs:simpleContent>
                </xs:complexType>
              </xs:element>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
      <xs:attribute type="xs:float" name="SchemaVersion"/>
      <xs:attribute type="xs:dateTime" name="RequestTimestamp"/>
    </xs:complexType>
  </xs:element>
</xs:schema>

Response XML Attributes

<ProjectsResponse> Attributes

RequestTimestamp – Timestamp of when the request was made. This values is always converted to UTC. (All other timestamps returned by the API are converted to the program’s local timezone.)

<Project> Attributes

ProjectId – Unique identifier for the project
ProgramId – Unique identifier for the program
ProjectNumber – The project number. Projects are assigned a project number when they have been submitted.
Status – Current status of the project
StatusCustomId – Optional, admin-set unique identifier for the status
StatusPublicId – Unique identifier for the status
StatusTimestamp – Timestamp of when the project entered the current status. Converted to user’s local timezone.
LastChangeTimestamp – Timestamp of the last change made to the project. Converted to user’s local timezone.

Sample Code


// Retrieves info about all accessible projects in the given program.
// Returns a list of <ProjectId, ProjectNumber> pairs corresponding to each project in the list.

public List<Tuple<string, string>> GetProjects(string programId, string username, string password, string apiKey)
{
    string url = "/Programs/" + programId + "/Projects";
    XDocument xmlResponse = MakeGetRequest(BaseUrl + url, username, password, apiKey);

    XNamespace ns = "http://service.powerclerk.com/api/v1/";
    List<XElement> projectElements = xmlResponse.Descendants(ns + "Project").ToList();

    List<Tuple<string, string>> projects = new List<Tuple<string, string>>();
    foreach (XElement projectElement in projectElements)
    {
        string projectId = projectElement.Attribute("ProjectId").Value;
        string projectNumber = projectElement.Attribute("ProjectNumber") != null ? projectElement.Attribute("ProjectNumber").Value : String.Empty;
        projects.Add(new Tuple<string, string>(projectId, projectNumber));
    }
    return projects;
}


function getProjects(programId) {
    // Use $.ajax jQuery method to execute the API call
    $.ajax({
        type: "GET",
        url: "https://{BaseURL}/Programs/" + programId + "/Projects",
        dataType: "xml",
        beforeSend: function (xhr) {
            xhr.setRequestHeader("Authorization", "Basic " + hashedCredentials);
            xhr.setRequestHeader("X-ApiKey", apiKey);
        },
        success: function (xml) {
            // Display data
        },
        error: function (xhr) {
            // Display error
        }
    });
}

See Chapter Code Samples for MakeGetRequest sample code.

Polling For Project Changes

The GetProjects method can be used to monitor the status of a program, regularly checking for project updates. After the first GetProjects call, note the RequestTimestamp attribute on the ProjectResponse. This denotes the time the request was made. When you’d like to check for updates again, use the value of the RequestTimestamp attribute as the changed_since parameter on your second GetProjects call. This will return any projects that have been changed since the initial request.

What’s Next?