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

GetProjectData

Retrieves the most recently submitted draft data for each data field in the given project form. Requires read access to the project. Difference to GetAllProjectData is that this is available to non-admins, returns only the data in the form and indicates whether the form is filled out complete enough to be submitted.
 
HTTP verb: GET
Required inputs: ProgramId, ProjectId, FormId
Optional inputs: reveal_sensitive_data
 

Path parameter Description
ProgramId The ID of the program of the project for which you want to get data
ProjectId The project in which you want to get the data on a form
FormId The form in the project whose data you want to retrieve

Query string parameters

Name Data Type Required/Optional Description
reveal_sensitive_data Boolean Optional If the requested project form contains sensitive data, by default this request will only retrieve the obfuscated value. If you would like to retrieve the plaintext value, you can supply this query parameter with a value of “true.” In addition, the account making the request must have MFA enabled and must have the appropriate privilege to view sensitive data in this program, or the whole request will fail.
include_calculated_fields Boolean Optional Append this parameter to also retrieve Calculated Fields.

URL Format

Format: https://{BaseURL}/Programs/{ProgramId}/Projects/{ProjectId}/Forms/{FormId}/Data
 
Samples:
 https://{BaseURL}/Programs/A43FN6B/Projects/D4GJR65/Forms/47LEZF8/Data
 https://{BaseURL}/Programs/A43FN6B/Projects/D4GJR65/Forms/47LEZF8/Data?reveal_sensitive_data=true
 https://{BaseURL}/Programs/A43FN6B/Projects/D4GJR65/Forms/47LEZF8/Data?reveal_sensitive_data=false
 https://{BaseURL}/Programs/A43FN6B/Projects/D4GJR65/Forms/47LEZF8/Data?include_calculated_fields=true
 https://{BaseURL}/Programs/A43FN6B/Projects/D4GJR65/Forms/47LEZF8/Data?include_calculated_fields=false

Sample Response


<ProjectDataGetResponse>
    <Project ProjectId="8V7CD47WG8" ProgramId="1HF29X4P" CanSubmit="true" ProjectNumber="TEST-00010">
        <Url Value="http://testagency.powerclerk.com/Projects/ProjectList?ProgramId=1HF29X4P"/>
        <CurrentStatus StatusId="3X8KK600" Name="Application Review" Timestamp="2014-10-23T08:07:26-07:00"/>
        <DataFields>
            <DataField DataFieldId="NY9MS9D3" Name="Application Date" Value="9/3/2014"/>
            <DataField DataFieldId="9KE8MJ45" Name="Account Number" Value="123456789"/>
            <DataField DataFieldId="VH7SU5AX" Name="Meter Number" Value="3434343"/>
            <DataField DataFieldId="4QG2ZD7V" Name="Possible meter access issues" Value="None"/>
            <DataField DataFieldId="P4QG1P7H" Name="Applicant City" Value="Kirkland"/>
            <DataField DataFieldId="CZ9B0KG1" Name="Applicant Company" Value=""/>
            <DataField DataFieldId="MC7E3AR0" Name="Applicant Email" Value="solar@cleanpower.com"/>
            <DataField DataFieldId="73XH0BK1" Name="Applicant First" Value="Bob"/>
            <DataField DataFieldId="HF1H4FR6" Name="Applicant Last" Value="Solar"/>
            <DataField DataFieldId="AZ988PB5" Name="Applicant Line 1" Value="123 Main St."/>
            <DataField DataFieldId="MV51QW29" Name="Applicant Line 2" Value=""/>
            <DataField DataFieldId="86DP8K63" Name="Applicant Phone" Value="425-555-5555"/>
            <DataField DataFieldId="YJ2Z4C38" Name="Applicant State" Value="WA"/>
            <DataField DataFieldId="M3BK799M" Name="Applicant Zip Code" Value="98033"/>
            <DataField DataFieldId="3WE8N4DR" Name="Contractor act customer behalf" Value="True"/>
            <DataField DataFieldId="ND0AR5HV" Name="PV System CEC Rating" Value="25.055"/>
            <DataField DataFieldId="8G7ES4PP" Name="PV System Design Factor" Value="90.8"/>
            <DataField DataFieldId="J1J6QV0Y" Name="PV System Estimated Production" Value="2463"/>
            <DataField DataFieldId="FG95YH30" Name="PV System Inverter Manufacturer" Value="GreenVolts" Instance="0"/>
            <DataField DataFieldId="FG95YH30" Name="PV System Inverter Manufacturer" Value="Aero-Sharp" Instance="1"/>
            <DataField DataFieldId="FG95YH30" Name="PV System Inverter Manufacturer" Value="Kaco" Instance="2"/>
            <DataField DataFieldId="PX49AU23" Name="PV System Inverter Model" Value="GV-SCP001" Instance="0"/>
            <DataField DataFieldId="PX49AU23" Name="PV System Inverter Model" Value="X01-040L2E1" Instance="1"/>
            <DataField DataFieldId="PX49AU23" Name="PV System Inverter Model" Value="blueplanet 1501xi" Instance="2"/>
            <DataField DataFieldId="X4JC121E" Name="PV System Inverter Quantity" Value="1" Instance="0"/>
            <DataField DataFieldId="X4JC121E" Name="PV System Inverter Quantity" Value="3" Instance="1"/>
            <DataField DataFieldId="X4JC121E" Name="PV System Inverter Quantity" Value="2" Instance="2"/>
            <DataField DataFieldId="MK66BF6W" Name="PV System Nameplate Rating" Value="29.52"/>
            <DataField DataFieldId="BW480G7P" Name="PV System PV Module Assigned Inverter" Value="0" Instance="0"/>
            <DataField DataFieldId="BW480G7P" Name="PV System PV Module Assigned Inverter" Value="1" Instance="1"/>
            <DataField DataFieldId="BW480G7P" Name="PV System PV Module Assigned Inverter" Value="1" Instance="2"/>
            <DataField DataFieldId="BW480G7P" Name="PV System PV Module Assigned Inverter" Value="2" Instance="3"/>
            <DataField DataFieldId="JN5GZ009" Name="PV System PV Module Azimuth" Value="0" Instance="0"/>
            <DataField DataFieldId="JN5GZ009" Name="PV System PV Module Azimuth" Value="180" Instance="1"/>
            <DataField DataFieldId="JN5GZ009" Name="PV System PV Module Azimuth" Value="180" Instance="2"/>
            <DataField DataFieldId="JN5GZ009" Name="PV System PV Module Azimuth" Value="0" Instance="3"/>
            <DataField DataFieldId="GR51SN56" Name="PV System PV Module Manufacturer" Value="AblyTek" Instance="0"/>
            <DataField DataFieldId="GR51SN56" Name="PV System PV Module Manufacturer" Value="Global Sun" Instance="1"/>
            <DataField DataFieldId="GR51SN56" Name="PV System PV Module Manufacturer" Value="Lumeta" Instance="2"/>
            <DataField DataFieldId="GR51SN56" Name="PV System PV Module Manufacturer" Value="Ritek" Instance="3"/>
            <DataField DataFieldId="22FU5824" Name="PV System PV Module Model" Value="5MN6C175-A0" Instance="0"/>
            <DataField DataFieldId="22FU5824" Name="PV System PV Module Model" Value="P-225GS" Instance="1"/>
            <DataField DataFieldId="22FU5824" Name="PV System PV Module Model" Value="LEF028B" Instance="2"/>
            <DataField DataFieldId="22FU5824" Name="PV System PV Module Model" Value="MM135" Instance="3"/>
            <DataField DataFieldId="26JN87YE" Name="PV System PV Module Monthly Shading" Value="100,100,100,100,100,100,100,100,100,100,100,100" Instance="0"/>
            <DataField DataFieldId="26JN87YE" Name="PV System PV Module Monthly Shading" Value="98,100,100,98,100,100,100,99,100,99,100,100" Instance="1"/>
            <DataField DataFieldId="26JN87YE" Name="PV System PV Module Monthly Shading" Value="100,99,97,99,99,99,99,97,100,100,100,100" Instance="2"/>
            <DataField DataFieldId="26JN87YE" Name="PV System PV Module Monthly Shading" Value="100,99,99,98,99,99,96,99,98,99,87,99" Instance="3"/>
            <DataField DataFieldId="ZU044VZ8" Name="PV System PV Module Quantity" Value="21" Instance="0"/>
            <DataField DataFieldId="ZU044VZ8" Name="PV System PV Module Quantity" Value="15" Instance="1"/>
            <DataField DataFieldId="ZU044VZ8" Name="PV System PV Module Quantity" Value="27" Instance="2"/>
            <DataField DataFieldId="ZU044VZ8" Name="PV System PV Module Quantity" Value="18" Instance="3"/>
            <DataField DataFieldId="MK2HP7S8" Name="PV System PV Module Tilt" Value="0" Instance="0"/>
            <DataField DataFieldId="MK2HP7S8" Name="PV System PV Module Tilt" Value="0" Instance="1"/>
            <DataField DataFieldId="MK2HP7S8" Name="PV System PV Module Tilt" Value="0" Instance="2"/>
            <DataField DataFieldId="MK2HP7S8" Name="PV System PV Module Tilt" Value="0" Instance="3"/>
            <DataField DataFieldId="QV7HB9FD" Name="PV System PV Module Tracking" Value="Fixed" Instance="0"/>
            <DataField DataFieldId="QV7HB9FD" Name="PV System PV Module Tracking" Value="Fixed" Instance="1"/>
            <DataField DataFieldId="QV7HB9FD" Name="PV System PV Module Tracking" Value="Fixed" Instance="2"/>
            <DataField DataFieldId="QV7HB9FD" Name="PV System PV Module Tracking" Value="Fixed" Instance="3"/>
        </DataFields>
        <Attachments>
            <Attachment AttachmentId="3QX3VQ18" Name="Copy Of Utility Bill" FileName="utility_bill.pdf"/>
        </Attachments>
    </Project>
</ProjectDataGetResponse>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="http://services.powerclerk.com/api/v1/">
  <xs:element name="ProjectDataGetResponse">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="Project">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="Url">
                <xs:complexType>
                  <xs:simpleContent>
                    <xs:extension base="xs:string">
                      <xs:attribute type="xs:anyURI" name="Value" use="required"/>
                    </xs:extension>
                  </xs:simpleContent>
                </xs:complexType>
              </xs:element>
              <xs:element name="CurrentStatus">
                <xs:complexType>
                  <xs:simpleContent>
                    <xs:extension base="xs:string">
                      <xs:attribute type="xs:string" name="StatusId" use="required"/>
                      <xs:attribute type="xs:string" name="CustomId" use="optional"/>
                      <xs:attribute type="xs:string" name="Name" use="required"/>
                      <xs:attribute type="xs:dateTime" name="Timestamp" use="required"/>
                    </xs:extension>
                  </xs:simpleContent>
                </xs:complexType>
              </xs:element>
              <xs:element name="DataFields">
                <xs:complexType>
                  <xs:sequence>
                    <xs:element name="DataField" maxOccurs="unbounded" minOccurs="0">
                      <xs:complexType>
                        <xs:simpleContent>
                          <xs:extension base="xs:string">
                            <xs:attribute type="xs:string" name="DataFieldId" use="required"/>
                            <xs:attribute type="xs:string" name="CustomId" use="optional"/>
                            <xs:attribute type="xs:string" name="Name" use="required"/>
                            <xs:attribute type="xs:string" name="Value" use="required"/>
                            <xs:attribute type="xs:byte" name="Instance" use="optional"/>
                          </xs:extension>
                        </xs:simpleContent>
                      </xs:complexType>
                    </xs:element>
                  </xs:sequence>
                </xs:complexType>
              </xs:element>
              <xs:element name="Attachments">
                <xs:complexType>
                  <xs:sequence>
                    <xs:element name="Attachment" maxOccurs="unbounded" minOccurs="0">
                      <xs:complexType>
                        <xs:simpleContent>
                          <xs:extension base="xs:string">
                            <xs:attribute type="xs:string" name="AttachmentId" use="required"/>
                            <xs:attribute type="xs:string" name="CustomId" use="optional"/>
                            <xs:attribute type="xs:string" name="Name" use="required"/>
                            <xs:attribute type="xs:string" name="FileName" use="required"/>
                          </xs:extension>
                        </xs:simpleContent>
                      </xs:complexType>
                    </xs:element>
                  </xs:sequence>                      
                </xs:complexType>
              </xs:element>
            </xs:sequence>
            <xs:attribute type="xs:string" name="ProjectId" use="required"/>
            <xs:attribute type="xs:string" name="ProgramId" use="required"/>
            <xs:attribute type="xs:string" name="CanSubmit" use="required"/>
            <xs:attribute type="xs:string" name="ProjectNumber" use="optional"/>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
      <xs:attribute type="xs:float" name="SchemaVersion"/>
    </xs:complexType>
  </xs:element>
</xs:schema>

Response XML Attributes

<Project> Attributes

ProjectId – Unique identifier for the project
ProgramId – Unique identifier for the program
CanSubmit – Boolean. True if required data/attachment conditions have been satisfied and the form can be submitted.
ProjectNumber – The project number. Projects are assigned a project number when they have been submitted.
 

<Url> Attributes

Value – The URL for this program’s project list
 

<CurrentStatus> Attributes

StatusId – Unique identifier for the status
Name – Current status of the project
Timestamp – Timestamp of when the project entered the current status. Converted to user’s local timezone.
 

<DataField> Attributes

DataFieldId – Unique identifier for the data field
Value – Current value of the data field
Instance – Instance id of the data field (for multi-instance data fields only)
 

<Attachment> Attributes

AttachmentId – Unique identifier for the attachment
Name – Attachment name
FileName – Attachment filename

Sample Code


// Retrieves all data field values for the given project in the specified form.
// Returns a list of <DataFieldId, DataFieldName, DataValue> tuples, one for each data field value
// in the project.

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

    XNamespace ns = "http://services.powerclerk.com/api/v1/";
    List<XElement> dataElements = xmlResponse.Descendants(ns + "DataField").ToList();

    List<Tuple<string, string, string>> projectData = new List<Tuple<string, string, string>>();
    foreach (XElement dataElement in dataElements)
    {
        string fieldId = dataElement.Attribute("DataFieldId").Value;
        string fieldName = dataElement.Attribute("Name").Value;
        string value = dataElement.Attribute("Value").Value;
        projectData.Add(new Tuple<string, string, string>(fieldId, fieldName, value));
    }
    return projectData;
}

function getProjectData(programId, projectId, formId) {
    // Use $.ajax jQuery method to execute the API call
    $.ajax({
        type: "GET",
        url: "https://{BaseURL}/Programs/" + programId + "/Projects/" + projectId + "/Forms/" + formId + "/Data",
        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.

What’s Next?