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

GetProjectsByData

Retrieves a list of projects associated with the given program that are read-accessible to the user that have the data field content specified as specified by the request body. Important limitation: the data fields to be queried on MUST be on the dashboard in a column that’s visible to the calling user. The calling user MUST be in a role that has Access Breadth set to All Projects in the given program.
 
HTTP verb: GET
Required inputs: ProgramId

Why a POST request and not a GET request?

HTTP specifications say that GET responses can’t depend on a body and with a POST body the request is not restricted by URL length.

URL Format

Format: https://{BaseURL}/Programs/{ProgramId}/Projects/ByData
 
Sample: https://{BaseURL}/Programs/1HF29X4P/Projects/ByData

Sample Request


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

<ProjectByDataRequest xmlns="http://service.powerclerk.com/api/v1/">
    <FilterByCurrentStatuses Operation=”Exclude”>
        <Status Id=”3X8KK600” />
        <Status Id=”ApplicationInProcess” />
    </FilterByCurrentStatuses>
    <FilterByStatusDate>
        <Status Id=”ApplicationSubmitted” DateTime=”2017-06-08T18:10:01” Operator=”lt” />
    </FilterByCurrentStatuses>
    <DataFields>
        <Field Id=”9KE8MJ45” Content=”12345” Operator=”eq”/>
        <Field Id=”MeterNumber” Content=”54321” Operator=”eq”/>
    </DataFields>
</ProjectByNumberRequest>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="http://service.powerclerk.com/api/v1/">
  <xs:element name="ProjectByDataRequest">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="DataFields" minOccurs="1">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="Field" minOccurs="1" maxOccurs="unbounded">
                <xs:complexType>
                  <xs:attribute name="Id" type="xs:string" use="required" />
                  <xs:attribute name="Content" type="xs:string" use="required" />
                  <xs:attribute name="Operator" type="xs:string" use="required" />
                </xs:complexType>
              </xs:element>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="FilterByCurrentStatuses" maxOccurs="1" minOccurs="0">
          <xs:complexType>
            <xs:sequence>
              <xs:element maxOccurs="unbounded" minOccurs="1" name="Status">
                <xs:complexType>
                  <xs:attribute name="Id" type="xs:string" use="required" />
                </xs:complexType>
              </xs:element>
            </xs:sequence>
            <xs:attribute type="xs:string" name="Operation" use="optional"/>
          </xs:complexType>
        </xs:element>
        <xs:element name="FilterByStatusDate" maxOccurs="1" minOccurs="0">
          <xs:complexType>
            <xs:simpleContent>
              <xs:extension base="xs:string">
                <xs:attribute name="Id" type="xs:string" use="required" />
                <xs:attribute name="Operator" type="xs:string" use="required" />
                <xs:attribute name="DateTime" type="xs:dateTime" use="required" />
              </xs:extension>
            </xs:simpleContent>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

Request XML Nodes and Attributes

<DataFields> Node

Contains the set of data fields, the content to look for and the operator to apply. Only projects that satisfy all conditions are returned.
 

<Field> Node

Describes the comparison to apply per field.
 
Attributes:
Id – Unique identifier of the data field, Custom ID allowable if set. Field MUST be on the dashboard, in a column accessible to the calling user. Read more about Project Views in the Support Center.
Content – value to look for. For DateTime fields, format MUST be yyyy-MM-dd’T’HH:mm:ss in UTC.
Operator – identifies the comparison to applied in between the data fields content and the value of the Content attribute. Must be one of:

  • “eq” : value must equal Content (valid for all data types)
  • “neq” : value must NOT equal Content (valid for all data types)
  • “lt” : value must be less than Content (valid for data types DateTime, Decimal and Integer)
  • “lte” : value must be less than or equal Content (valid for data types DateTime, Decimal and Integer)
  • “gt” : value must be greater than Content (valid for data types DateTime, Decimal and Integer)
  • “gte” : value must be greater than or equal Content (valid for data types DateTime, Decimal and Integer)

 

<FilterByCurrentStatuses> Node

Contains the statuses that projects must be in that are looked at.
Operation – If set to “Exclude”, all projects in statuses contained in the list will be excluded. If set to “Include” or omitted, the response only includes projects in those statuses.
 

<Status> Node

Defines which statuses to filter the results on, based on the Operation attribute of the parent node.
 
Attributes:
Id – Unique identifier of the status, Custom ID allowable if set

<FilterByStatusDate> Node

Allows to specify what status in the project history must have reached by what date in order to be included. If this node is not specified, projects are examined regardless of history.
 
Attributes:
Id – Unique identifier of the status, Custom ID allowable if set DateTime – point in time to compare the given status history entry to. Must be in format yyyy-MM-dd’T’HH:mm:ss in UTC.
Operator – identifies the comparison to applied in between the data fields content and the value of the DateTime attribute

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>

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>

What’s Next?