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

SetProjectData

Sets data for data fields in the given project form and returns the updated set of data values for the form. Requires write access to the project.
 
HTTP verb: POST
Required inputs: ProgramId, ProjectId, FormId
 
Please note: Using SetProjectData with a PowerClerk account that does not have administrative privileges enabled, will create a draft version of the respective data field values targeted via API and requires the use of SubmitProject to submit the underlying Form and commit these draft values.

URL Format

Format: https://{BaseURL}/Programs/{ProgramId}/Projects/{ProjectId}/Forms/{FormId}/Data
 
Sample: https://{BaseURL}/Programs/A43FN6B/Projects/D4GJR65/Forms/47LEZF8/Data

Sample Request

Note: Request payloads must include the namespace “http://service.powerclerk.com/api/v1” (see below).


<ProjectDataRequest xmlns="http://service.powerclerk.com/api/v1/">
    <Project ProjectId="D4GJR65" FormId="47LEZF8">
        <DataFields>
            <DataField DataFieldId="NY9MS9D3" Name="Application Date" Value="2014-10-28"/>
            <DataField DataFieldId="4QG2ZD7V" Name="Possible meter access issues" Value="Locked gate"/>
            <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="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="ZU044VZ8" Name="PV System Inverter Quantity" Value="1" Instance="0"/>
            <DataField DataFieldId="ZU044VZ8" Name="PV System Inverter Quantity" Value="3" Instance="1"/>
            <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="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="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="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="26JN87YE" Name="PV System PV Module Monthly Shading" Value="90,90,90,90,10,10,90,10,90,90,80,10" Instance="0"/>
            <DataField DataFieldId="26JN87YE" Name="PV System PV Module Monthly Shading" Value="98,10,10,98,10,10,10,99,10,99,100,100" Instance="1"/>
            <DataField DataFieldId="26JN87YE" Name="PV System PV Module Monthly Shading" Value="100,99,97,99,99,99,99,97,10,100,10,100" Instance="2"/>
            <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="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="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"/>
        </DataFields>
    </Project>
</ProjectDataRequest>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" attributeformdefault="unqualified" elementformdefault="qualified" targetnamespace="http://service.powerclerk.com/api/v1/">
  <xs:element name="ProjectDataRequest">
    <xs:complextype>
      <xs:sequence>
        <xs:element name="Project">
          <xs:complextype>
            <xs:sequence>
              <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>
                            <xs:attribute type="xs:string" name="Name" use="optional"></xs:attribute>
                            <xs:attribute type="xs:string" name="Value" use="required"></xs:attribute>
                            <xs:attribute type="xs:byte" name="Instance" use="optional"></xs:attribute>
                          </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>
            <xs:attribute type="xs:string" name="FormId" use="required"></xs:attribute>
          </xs:complextype>
        </xs:element>
      </xs:sequence>
      <xs:attribute type="xs:float" name="SchemaVersion"></xs:attribute>
    </xs:complextype>
  </xs:element>
</xs:schema>

Request XML Attributes

<DataField> Attributes

DataFieldId – Required. Unique identifier for the data field – can either be the automatically generated DataFieldId, or the admin-set custom ID.
Name – Optional. The name of the data field.
Value – Required. The value to set for the data field.
Instance – Required for multi-instance data fields. The instance id of the data field.

Sample Response

Fields that have been set by the above sample request are highlighted in bold.


<ProjectDataSetResponse>
    <Project ProjectId="HM7RC1XF5U" ProgramId="1HF29X4P" CanSubmit="false">
        <Url Value="http://testagency.powerclerk.com/Projects/ProjectList?ProgramId=1HF29X4P"/>
        <CurrentStatus StatusId="3X8KK600" Name="Unsubmitted" Timestamp="2014-10-06T21:21:20-07:00"/>
        <DataFields>
            <DataField DataFieldId="NY9MS9D3" Name="Application Date" Value="2014-10-28"/>
            <DataField DataFieldId="9KE8MJ45" Name="Account Number" Value=""/>
            <DataField DataFieldId="VH7SU5AX" Name="Meter Number" Value=""/>
            <DataField DataFieldId="4QG2ZD7V" Name="Possible meter access issues" Value="Locked gate"/>
            <DataField DataFieldId="P4QG1P7H" Name="Applicant City" Value="Kirkland"/>
            <DataField DataFieldId="CZ9B0KG1" Name="Applicant Company" Value=""/>
            <DataField DataFieldId="MC7E3AR0" Name="Applicant Email" Value=""/>
            <DataField DataFieldId="73XH0BK1" Name="Applicant First" Value="John"/>
            <DataField DataFieldId="HF1H4FR6" Name="Applicant Last" Value="Smith"/>
            <DataField DataFieldId="AZ988PB5" Name="Applicant Line 1" Value="123 Solar Way"/>
            <DataField DataFieldId="MV51QW29" Name="Applicant Line 2" Value="Apt 7"/>
            <DataField DataFieldId="86DP8K63" Name="Applicant Phone" Value=""/>
            <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=""/>
            <DataField DataFieldId="ND0AR5HV" Name="PV System CEC Rating" Value="11.327"/>
            <DataField DataFieldId="8G7ES4PP" Name="PV System Design Factor" Value="31.4"/>
            <DataField DataFieldId="J1J6QV0Y" Name="PV System Estimated Production" Value="6186"/>
            <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="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="X4JC121E" Name="PV System Inverter Quantity" Value="1" Instance="0"/>
            <DataField DataFieldId="X4JC121E" Name="PV System Inverter Quantity" Value="3" Instance="1"/>
            <DataField DataFieldId="MK66BF6W" Name="PV System Nameplate Rating" Value="13.736"/>
            <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="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="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="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="26JN87YE" Name="PV System PV Module Monthly Shading" Value="90,90,90,90,10,10,90,10,90,90,80,10" Instance="0"/>
            <DataField DataFieldId="26JN87YE" Name="PV System PV Module Monthly Shading" Value="98,10,10,98,10,10,10,99,10,99,100,100" Instance="1"/>
            <DataField DataFieldId="26JN87YE" Name="PV System PV Module Monthly Shading" Value="100,99,97,99,99,99,99,97,10,100,10,100" Instance="2"/>
            <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="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="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"/>
        </DataFields>
        <CalculatedDataFields>
            <DataField DataFieldId="J1J6QV0Y" Name="PV System Estimated Production" Value="6186"/>
            <DataField DataFieldId="MK66BF6W" Name="PV System Nameplate Rating" Value="13.736"/>
            <DataField DataFieldId="ND0AR5HV" Name="PV System CEC Rating" Value="11.327"/>
            <DataField DataFieldId="8G7ES4PP" Name="PV System Design Factor" Value="31.4"/>
        </CalculatedDataFields>
        <Attachments>
            <Attachment AttachmentId="3QX3VQ18" Name="Copy Of Utility Bill" FileName="bill.pdf"/>
        </Attachments>
    </Project>
</ProjectDataSetResponse>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="http://services.powerclerk.com/api/v1/">
  <xs:element name="ProjectDataSetResponse">
    <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"/>
                      <xs:attribute type="xs:string" name="CustomId" use="optional"/>
                      <xs:attribute type="xs:string" name="Name"/>
                      <xs:attribute type="xs:dateTime" name="Timestamp"/>
                    </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="CalculatedDataFields">
                <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"/>
                            <xs:attribute type="xs:string" name="Name" use="required"/>
                            <xs:attribute type="xs:float" name="Value" use="required"/>
                          </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"/>
                            <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="ProjectNumber" use="optional"/>
            <xs:attribute type="xs:string" name="CanSubmit" use="required"/>
          </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

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

<DataField> Attributes

Name – Data field name
Value – Current value of the data field
Instance – Instance id of the data field (for multi-instance data fields only)
 

<CalculatedDataFields>

<CalculatedDataFields> – List of data field values that have been automatically changed to reflect project data values submitted in the request payload. The <CalculatedDataFields> element only displays changes to calculated data field values; if no calculated data field values have been affected by the request payload, the element will be empty.
 

<Attachment> Attributes

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

Sample Code


// For a given project, sets the first name and last name fields in an application form.
// Returns the updated values in the application form as a list of
// <DataFieldId, DataFieldName, DataValue> tuples, one for each data field value in the project.

public List<Tuple<string, string, string>> SetApplicantName(string programId, string projectId, string formId, string firstNameFieldId, string lastNameFieldId, string firstName, string lastName, string username, string password, string apiKey)
{
    // Create an XML request payload that assigns first name and last name values to the
    // corresponding data fields
    XNamespace ns = "http://service.powerclerk.com/api/v1/";
    XDocument xDocument = new XDocument(
        new XElement(ns + "ProjectDataRequest",
            new XElement(ns + "Project",
                new XElement(ns + "DataFields",
                    new XElement(ns + "DataField",
                        new XAttribute("DataFieldId", firstNameFieldId),
                        new XAttribute("Value", firstName)),
                    new XElement(ns + "DataField",
                        new XAttribute("DataFieldId", lastNameFieldId),
                        new XAttribute("Value", lastName)),
                    new XAttribute("ProjectId", projectId),
                    new XAttribute("FormId", formId)))));

    XmlDocument requestPayload = new XmlDocument();
    using (XmlReader xmlReader = xDocument.CreateReader())
    {
        requestPayload.Load(xmlReader);
    }

    // Generate url and execute request with the XML payload we created earlier
    string url = "/Programs/" + programId + "/Projects/" + projectId + "/Forms/" + formId + "/Data";
    XDocument xmlResponse =
        MakePostRequest(BaseUrl + url, username, password, apiKey, requestPayload);

    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 setProjectData(programId, projectId, formId, firstName, lastName, address1, address2, city, state, zip) {
    var payload = {xmlPayload};
    // Use $.ajax jQuery method to execute the API call
    $.ajax({
        type: "POST",
        processData: false,
        data: payload,
        url: "https://{BaseURL}/Programs/" + programId + "/Projects/" + projectId + "/Forms/" + formId + "/Data",
        contentType: "text/xml",
        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
        }
    });
}

What’s Next?