GetProjects

Retrieves a list of projects associated with the given program. Please note: This method will only retrieve projects that the API caller has read-access to.

HTTP verb: GET
Required inputs: ProgramId
Optional inputs: changed_since (timestamp), version (integer), limit (integer), offset (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.
limit	Integer	Optional	If the optional parameter “limit” is included, the call will retrieve the first N projects, ordered by project creation timestamps. The current max value of “limit” is 1000 projects. …/Projects?limit=10 will return the first 10 projects
offset	Integer	Optional	If the optional parameter “offset” is included, the call will skip over the first N projects, ordered by project creation timestamps. …/Projects?limit=10&offset=0 will return projects 1…10 …/Projects?limit=10&offset=10 will return projects 11…20

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
3	Includes OwnerEmailAddress

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.)

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.)

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.

Version 3 Response


<ProjectsResponse SchemaVersion="3" RequestTimestamp="2022-09-09T18:37:22.0892611+00:00" xmlns=http://service.powerclerk.com/api/v1/ xmlns:xsd=http://www.w3.org/2001/XMLSchema xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance>
    <Projects>
        <Project ProjectId="4SXT6YCPDQ8R" ProgramId="1HF29X4P" ProjectNumber="TEST-99998" Status="Unsubmitted" StatusTimestamp="2022-09-09T11:32:17-07:00" LastChangeTimestamp="2022-09-09T11:33:09-07:00" StatusPublicId="3X8KK600" OwnerEmailAddress=testuser42@cleanpower.com/>
    </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="StatusPublicId" use="required"/>
                      <xs:attribute type="xs:string" name="StatusCustomId" use="optional"/>
                      <xs:attribute type="xs:string" name="OwnerEmailAddress" 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" fixed="3.0"/>
      <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.)

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.
OwnerEmailAddress – Email address of the project owner.

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?

Cookie	Duration	Description
CloudFlare CDN	4 weeks	This cookie is set by CloudFare to identify individual clients behind a shared IP address and apply security settings on a per-client basis. It does not correspond to any user ID in the web application and does not store any personally identifiable information.
CookieLawInfo Checkbox Necessary	11 months	This cookie is set by GDPR Cookie Consent plugin. The cookie is used to store the user consent for the cookies in the category ‘Strictly Necessary’.
CookieLawInfo Checkbox Performance	11 months	This cookie is set by GDPR Cookie Consent plugin. The purpose of this cookie is to check whether or not the user has given the consent to the usage of cookies under the category ‘Performance’.
CookieLawInfo Checkbox Personalization	11 months	This cookie is set by GDPR Cookie Consent plugin. The purpose of this cookie is to check whether or not the user has given the consent to the usage of cookies under the category ‘Enhancements & Personalization’.
Viewed Cookie Policy	1 hour	This cookie is set by the GDPR Cookie Consent plugin and is used to store whether or not user has consented to the use of cookies. It does not store any personal data.
Website Search Interaction	Session	This cookie is set by Site Search 360, our search engine for all Clean Power Research websites, to record search session preferences and performance.
Website Search Session ID	11 months	This cookie is set by Site Search 360, our search engine for all Clean Power Research websites, to record search session preferences.

Cookie	Duration	Description
Google Analytics Data Limiter	1 minute	This cookie is installed by Google Universal Analytics to throttle the request rate to limit the colllection of data on high traffic sites.
Google Analytics Page Visits	1 day	This cookie is installed by Google Analytics. The cookie is used to store information of how visitors use a website and helps in creating an analytics report of how the wbsite is doing. The data collected including the number visitors, the source where they have come from, and the pages visted in an anonymous form.
Google Analytics Random Identifier	2 years	This cookie is installed by Google Analytics. The cookie is used to calculate visitor, session, campaign data and keep track of site usage for the site’s analytics report. The cookie stores information anonymously and assigns a randomly generated number to identify unique visitors.
Marketo Tracking	2 years	This cookie is associated with an email marketing service provided by Marketo. This tracking cookie allows the website to link visitor behavior to the recipient of an email marketing campaign, to measure campaign effectiveness.

Cookie	Duration	Description
Wistia Videos	11 months	Set by Wistia to support video functionality that may be found throughout the website. In addition to keeping track of the website visitor's position in a video should playback be interrupted, this cookie also notes user behavior regarding the video itself.
Wistia Videos Data	10 months	This cookie collects visitor interaction data regarding Wistia video content so that such content can be made more relevant to the visitor.

Application & Process Automation

GetProjects

URL Format

Version 1 Response

Response XML Attributes

Attributes

Version 2 Response

Response XML Attributes

Attributes

Version 3 Response

Response XML Attributes

Attributes

Sample Code

Polling For Project Changes

GetProjectsByNumber