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

GetProjectsByNumber

Retrieves a list of projects associated with the given program that are read-accessible to the user that have a project number that matches a project number in the request body.
 
HTTP verb: POST
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/ByNumber?version={VersionNumber}
 
Samples: https://{BaseURL}/Programs/1HF29X4P/Projects/ByNumber?version=2
 
Please note: in the 1.1 version of the API this method had a different URL format. The earlier one is supported for backwards compatibility only, please use the documented format above for all new API integrations.

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>

Sample Request


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

<ProjectByNumberRequest xmlns="http://service.powerclerk.com/api/v1/">
    <Project ProjectNumber="TEST-00001" />
    <Project ProjectNumber="TEST-00021" />
    <Project ProjectNumber="TEST-00035" />
    <Project ProjectNumber="TEST-00036" />
</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="ProjectByNumberRequest">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="Project" maxOccurs="unbounded" minOccurs="0">
          <xs:complexType>
            <xs:attribute type="xs:string" name="ProjectNumber" use="required"/>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

Sample Code


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

public static List<Tuple<string, string>> GetProjectsByNumber(string programId, List<string> projectNumberIds, 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/";
    List<XElement> projectNumbers = projectNumberIds.Select(projectNumber => new XElement(ns + "Project", new XAttribute("ProjectNumber", projectNumber))).ToList();

    XDocument xDocument = new XDocument(
        new XElement(ns + "ProjectByNumberRequest",
            projectNumbers));

    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";
    XDocument xmlResponse =
        MakePostRequest(BaseUrl + url, username, password, apiKey, requestPayload);

    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;
}

See Chapter Code Samples for MakePostRequest sample code.

What’s Next?