Payroll API

Global Parameters

Name Required (Y/N) Format/Value Description Example
type_of_data Y String – Maximum 15 Characters. Allows user to select different types of data. Value must be one of the following:Contracts, Budget, Revenue, Payroll, Spending, Spending_OGE, Contracts_OGE, Spending_NYCHA, Contracts_NYCHA and Payroll_NYCHA Payroll
max_records N String - Maximum 4 Characters Allows you to set the maximum number of records retrieved to fewer than 1000 500
record_from N String - Maximum 15 Characters Allows you to set the starting position of the records to be retrieved 12500

Back to the top

type_of_data:Payroll

Payroll Parameters – All the parameters are optional, meaning that you can send only 1 or all of them. If you choose to not send any, you will receive random transactions in return, as these parameters are the filter.

Name Required (Y/N/C)
(Yes/No/
Conditional)		 Type of Criteria (value/range) Format/Value Description Applicable Filters Reference Codes Example
fiscal_year C value String - YYYY - Maximum 4 characters Fiscal Year. Must be exactly 4 characters. It is mandatory to select either fiscal year or calendar year. Citywide Agencies and Other Government Entities (NYCHA)   2005
calendar_year C value String - YYYY - Maximum 4 characters Calendar Year. Must be exactly 4 characters. It is mandatory to select either fiscal year or calendar year. Citywide Agencies   2011
agency_code N value String - Maximum 3 characters Identification code associated with agency. Citywide Agencies Citywide: Agency Codes List 127
pay_frequency N value String - Maximum 18 characters Possible values are: BI-WEEKLY, WEEKLY, SEMI-MONTHLY, SUPPLEMENTAL, DAILY AND HOURLY Citywide Agencies and Other Government Entities (NYCHA) Possible values are: BI-WEEKLY, WEEKLY, SEMI-MONTHLY, SUPPLEMENTAL, DAILY AND HOURLY BI-WEEKLY
title N value String - Maximum 100 characters Displays employees civil service title Citywide Agencies and Other Government Entities (NYCHA)   teacher
pay_date N range String - YYYY-MM-DD Date of payment Citywide Agencies and Other Government Entities (NYCHA)   2001-08-12
amount N range String - Maximum 18 characters Citywide Agencies and Other Government Entities (NYCHA) If amount is provided, then amount type needs to be provided in order to distinguish annual, rate and all. By default, data for all types is provided.   250000.00
amount_type N value String - Maximum 18 characters Possible values are “ANNUAL”, ”RATE” and ”ALL” Citywide Agencies and Other Government Entities (NYCHA) Three possible columns should be in this format: ANNUAL, RATE and ALL. By default, ‘ALL’ is preselected. ANNUAL
gross_pay N range String - Maximum 18 characters A dollar amount which is summation of base pay, other payments and overtime amounts. Citywide Agencies and Other Government Entities (NYCHA)   250000.00
base_pay N range String - Maximum 18 characters An employee's base pay can be expressed as a base hourly rate of pay or as an annual salary Citywide Agencies and Other Government Entities (NYCHA)   250000.00
other_payments N range String - Maximum 18 characters Other payments associated to an employee salary. Citywide Agencies and Other Government Entities (NYCHA)   250000.00
overtime_payments N range String - Maximum 18 characters Employee's overtime pay Citywide Agencies and Other Government Entities (NYCHA)   250000.00
gross_pay_ytd N range String - Maximum 18 characters The Total Gross pay would be displayed based on the selected Fiscal year or calendar year. Citywide Agencies and Other Government Entities (NYCHA)   250000.00

Back to the top

Possible response columns:

User would be able to select which columns he would like to view in his output. Below mentioned are the possible column names for payroll domain. The user should include the required column names in the request xml in an element called <response_coloumns>

 
(Citywide) Response Column Names
agency base_pay
fiscal_year other_payments
pay_frequency overtime_payments
hourly_rate gross_pay_ytd
gross_pay calendar_year
title annual_salary
pay_date payroll_type
 
(Other Government Entities - NYCHA) Response Column Names
annual_salary base_pay
fiscal_year other_payments
pay_frequency overtime_payments
hourly_rate gross_pay_ytd
gross_pay title
payroll_type pay_date

Back to the top

 

Predefined Entities in XML

The user has to encode the names using the predefined entities list embedded below, while searching using names (payee_name, budget_name, vendor, and purpose). The table below lists the five XML predefined entities. The "Name" column mentions the entity's name. The "Character" column shows the character. To render the character, the format &name; is used; for example, &amp; renders as &.

Name Character Description Representation Example Text Example Request/Response
quot " double quotation mark &quot; “Gilbane” &quot;Gilbane&quot;
amp & ampersand &amp; Mckissack & Mckissack Mckissack &amp; Mckissack
apos ' apostrophe (apostrophe-quote) &apos; ‘turner’ &apos; turner &apos;
lt < less-than sign &lt; <gilbane building &lt;gilbane building
gt > greater-than sign &gt; gilbane building> gilbane building&gt;

Back to the top

 

Sample XML Requests and Responses

The following xml file will specify API method calls and the details for each call.

The request xml would include global parameters which specify the selected domain, records from and maximum records to return in response. It also includes search parameters along with requested response column.

In the response xml, the actual search parameters that were sent will be returned in an element called <search_criteria> along with the actual result for a given search criteria will be displayed in an element called <result_records>.

The total number of resulting records for a given search criteria will be displayed within an element called <record_count>, which helps user to view the total number of records found for a given search criteria.

The response xml also includes status messages for the result. If there is an error, corresponding error code along with description will be included in an element called <messages> for user reference.

Back to the top

Sample Request: Payroll Transactions (CITYWIDE)

<request>
  <type_of_data>Payroll</type_of_data>
  <records_from>1</records_from>
  <max_records>5</max_records>
  <search_criteria>
    <criteria>
      <name>fiscal_year</name>
      <type>value</type>
      <value>2011</value>
    </criteria>
    <criteria>
      <name>agency_code</name>
      <type>value</type>
      <value>040</value>
    </criteria>
    <criteria>
      <name>pay_frequency</name>
      <type>value</type>
      <value>SEMI-MONTHLY</value>
    </criteria>
    <criteria>
      <name>pay_date</name>
      <type>range</type>
      <start>2011-01-30</start>
      <end>2011-07-30</end>
    </criteria>
    <criteria>
      <name>amount</name>
      <type>range</type>
      <start>0.00</start>
      <end>100000000.00</end>
    </criteria>
    <criteria>
      <name>amount_type</name>
      <type>value</type>
      <value>ANNUAL</value>
    </criteria>
    <criteria>
      <name>gross_pay</name>
      <type>range</type>
      <start>0.00</start>
      <end>100000000.00</end>
    </criteria>
    <criteria>
      <name>base_pay</name>
      <type>range</type>
      <start>0.00</start>
      <end>100000000.00</end>
    </criteria>
    <criteria>
      <name>other_payments</name>
      <type>range</type>
      <start>0.00</start>
      <end>100000000.00</end>
    </criteria>
    <criteria>
      <name>overtime_payments</name>
      <type>range</type>
      <start>0.00</start>
      <end>100000000.00</end>
    </criteria>
    <criteria>
      <name>gross_pay_ytd</name>
      <type>range</type>
      <start>0.00</start>
      <end>100000000.00</end>
    </criteria>
    <criteria>
      <name>title</name>
      <type>value</type>
      <value>teacher</value>
    </criteria>
  </search_criteria>
  <response_columns>
    <column>agency</column>
    <column>title</column>
    <column>pay_frequency</column>
    <column>pay_date</column>
    <column>annual_salary</column>
    <column>hourly_rate</column>
    <column>gross_pay</column>
    <column>base_pay</column>
    <column>other_payments</column>
    <column>overtime_payments</column>
    <column>gross_pay_ytd</column>
    <column>fiscal_year</column>
    <column>calendar_year</column>
  </response_columns>
</request>

Back to the top

Sample Response: Payroll Transactions (CITYWIDE)

<response>
  <status>
    <result>success</result>
  </status>
  <request_criteria>
    <request>
      <type_of_data>Payroll</type_of_data>
      <records_from>1</records_from>
      <max_records>5</max_records>
      <search_criteria>
        <criteria>
          <name>fiscal_year</name>
          <type>value</type>
          <value>2011</value>
        </criteria>
        <criteria>
          <name>agency_code</name>
          <type>value</type>
          <value>040</value>
        </criteria>
        <criteria>
          <name>pay_frequency</name>
          <type>value</type>
          <value>SEMI-MONTHLY</value>
        </criteria>
        <criteria>
          <name>pay_date</name>
          <type>range</type>
          <start>2011-01-30</start>
          <end>2011-07-30</end>
        </criteria>
        <criteria>
          <name>amount</name>
          <type>range</type>
          <start>0.00</start>
          <end>100000000.00</end>
        </criteria>
        <criteria>
          <name>amount_type</name>
          <type>value</type>
          <value>ANNUAL</value>
        </criteria>
        <criteria>
          <name>gross_pay</name>
          <type>range</type>
          <start>0.00</start>
          <end>100000000.00</end>
        </criteria>
        <criteria>
          <name>base_pay</name>
          <type>range</type>
          <start>0.00</start>
          <end>100000000.00</end>
        </criteria>
        <criteria>
          <name>other_payments</name>
          <type>range</type>
          <start>0.00</start>
          <end>100000000.00</end>
        </criteria>
        <criteria>
          <name>overtime_payments</name>
          <type>range</type>
          <start>0.00</start>
          <end>100000000.00</end>
        </criteria>
        <criteria>
          <name>gross_pay_ytd</name>
          <type>range</type>
          <start>0.00</start>
          <end>100000000.00</end>
        </criteria>
        <criteria>
          <name>title</name>
          <type>value</type>
          <value>teacher</value>
        </criteria>
      </search_criteria>
    </request>
  </request_criteria>
  <result_records>
    <record_count>1</record_count>
    <payroll_transactions>
      <transaction>
        <agency>Department of Education</agency>
        <title>TEACHER-REG</title>
        <pay_frequency>SEMI-MONTHLY</pay_frequency>
        <pay_date>2011-01-31</pay_date>
        <annual_salary>57320.00</annual_salary>
        <hourly_rate>0.00</hourly_rate>
        <gross_pay>58654.89</gross_pay>
        <base_pay>57001.48</base_pay>
        <other_payments>1653.41</other_payments>
        <overtime_payments>0.00</overtime_payments>
        <gross_pay_ytd>58654.89</gross_pay_ytd>
        <fiscal_year>2011</fiscal_year>
        <calendar_year>2011</calendar_year>
      </transaction>
    </payroll_transactions>
  </result_records>
</response>

Back to the top

Sample Request: Payroll Transactions(OTHER GOVERNMENT ENTITIES - NYCHA)

<request>
  <type_of_data>Payroll_NYCHA</type_of_data>
  <records_from>1</records_from>
  <max_records>1</max_records>
  <search_criteria>
    <criteria>
      <name>fiscal_year</name>
      <type>value</type>
      <value>2017</value>
    </criteria>
    <criteria>
      <name>pay_frequency</name>
      <type>value</type>
      <value>BI-WEEKLY</value>
    </criteria>
    <criteria>
      <name>pay_date</name>
      <type>range</type>
      <start>2016-11-18</start>
      <end>2018-11-30</end>
    </criteria>
    <criteria>
      <name>amount</name>
      <type>range</type>
      <start>0.00</start>
      <end>100000000.00</end>
    </criteria>
    <criteria>
      <name>amount_type</name>
      <type>value</type>
      <value>ANNUAL</value>
    </criteria>
    <criteria>
      <name>gross_pay</name>
      <type>range</type>
      <start>0.00</start>
      <end>100000000.00</end>
    </criteria>
    <criteria>
      <name>base_pay</name>
      <type>range</type>
      <start>0.00</start>
      <end>100000000.00</end>
    </criteria>
    <criteria>
      <name>other_payments</name>
      <type>range</type>
      <start>0.00</start>
      <end>100000000.00</end>
    </criteria>
    <criteria>
      <name>overtime_payments</name>
      <type>range</type>
      <start>0.00</start>
      <end>100000000.00</end>
    </criteria>
    <criteria>
      <name>gross_pay_ytd</name>
      <type>range</type>
      <start>0.00</start>
      <end>100000000.00</end>
    </criteria>
    <criteria>
      <name>title</name>
      <type>value</type>
      <value>COMMUNITY ASSOCIATE</value>
    </criteria>
  </search_criteria>
  <response_columns>
    <column>title</column>
    <column>pay_frequency</column>
    <column>pay_date</column>
    <column>annual_salary</column>
    <column>hourly_rate</column>
    <column>gross_pay</column>
    <column>base_pay</column>
    <column>other_payments</column>
    <column>overtime_payments</column>
    <column>gross_pay_ytd</column>
    <column>fiscal_year</column>
  </response_columns>
</request>

Back to the top

Sample Response: Payroll Transactions(OTHER GOVERNMENT ENTITIES -NYCHA)

<response>
  <status>
    <result>success</result>
  </status>
  <request_criteria>
    <request>
      <type_of_data>Payroll_NYCHA</type_of_data>
      <records_from>1</records_from>
      <max_records>1</max_records>
      <search_criteria>
        <criteria>
          <name>fiscal_year</name>
          <type>value</type>
          <value>2017</value>
        </criteria>
        <criteria>
          <name>pay_frequency</name>
          <type>value</type>
          <value>BI-WEEKLY</value>
        </criteria>
        <criteria>
          <name>pay_date</name>
          <type>range</type>
          <start>2016-11-18</start>
          <end>2018-11-30</end>
        </criteria>
        <criteria>
          <name>amount</name>
          <type>range</type>
          <start>0.00</start>
          <end>100000000.00</end>
        </criteria>
        <criteria>
          <name>amount_type</name>
          <type>value</type>
          <value>ANNUAL</value>
        </criteria>
        <criteria>
          <name>gross_pay</name>
          <type>range</type>
          <start>0.00</start>
          <end>100000000.00</end>
        </criteria>
        <criteria>
          <name>base_pay</name>
          <type>range</type>
          <start>0.00</start>
          <end>100000000.00</end>
        </criteria>
        <criteria>
          <name>other_payments</name>
          <type>range</type>
          <start>0.00</start>
          <end>100000000.00</end>
        </criteria>
        <criteria>
          <name>overtime_payments</name>
          <type>range</type>
          <start>0.00</start>
          <end>100000000.00</end>
        </criteria>
        <criteria>
          <name>gross_pay_ytd</name>
          <type>range</type>
          <start>0.00</start>
          <end>100000000.00</end>
        </criteria>
        <criteria>
          <name>title</name>
          <type>value</type>
          <value>COMMUNITY ASSOCIATE</value>
        </criteria>
      </search_criteria>
      <response_columns>
        <column>title</column>
        <column>pay_frequency</column>
        <column>pay_date</column>
        <column>annual_salary</column>
        <column>hourly_rate</column>
        <column>gross_pay</column>
        <column>base_pay</column>
        <column>other_payments</column>
        <column>overtime_payments</column>
        <column>gross_pay_ytd</column>
        <column>fiscal_year</column>
      </response_columns>
    </request>
  </request_criteria>
  <result_records>
    <record_count>2042</record_count>
    <payroll_transactions>
      <transaction>
        <title>COMMUNITY ASSOCIATE</title>
        <pay_frequency>BI-WEEKLY</pay_frequency>
        <pay_date>2017-09-28</pay_date>
        <annual_salary>59429</annual_salary>
        <hourly_rate>0.00</hourly_rate>
        <gross_pay>3699.46</gross_pay>
        <base_pay>2279.47</base_pay>
        <other_payments>141.65</other_payments>
        <overtime_payments>1278.34</overtime_payments>
        <gross_pay_ytd>57335.22</gross_pay_ytd>
        <fiscal_year>2017</fiscal_year>
      </transaction>
    </payroll_transactions>
  </result_records>
</response>

Back to the top

Status Codes and Messages

Status messages are categorized and displayed as status codes with short description for the user to understand the cause of the error. In case of an error no result records will be displayed and the error message will be displayed inside the <message> XML element as shown below. See here for list of status codes and messages

Example:

Result is Success:

<status>
  <result>success</result>
  <messages>
    <message>
      <code>1</code>
      <description>The status is still a success but there are no results found for given search criteria</description>
    </message>
  </messages>
</status>

Example: Result is Failure

 <status>
  <result>error</result>
  <messages>
    <message>
      <code>1000</code>
      <description>Required parameter 'type_of_data' is missing</description>
    </message>
  </messages>
</status>

Back to the top
 

Status Code Description
1 The status is still a success but there are no results found for given search criteria.
1000 Required parameter 'type_of_data' is missing.
1001 Invalid value 'PayrollRequest' is provided for 'type_of_data'. Valid values are Payroll, Contracts, Budget, Spending, and Revenue.
1002 Provided value '2.1' for 'records_from' is not an integer. Valid value is a number values without decimal places
1003 Total number of requested records '1001' exceeds allowed limit of '1000' records
1101 Provided request parameter 'date' is not valid for 'Payroll' domain. Valid values are 'fiscal_year, agency_code, department_code, budget_code, expense_category, adopted_budget, current_modified_budget, pre_encumbered, encumbered, cash_expense, post_adjustment, accrued_expense
1102 No value is provided for request parameter 'fiscal_year'.
1103 Provided value '20000' for request parameter 'fiscal_year' is not valid year.
1104 Provided 'start' value '200s' for request parameter 'adopted_budget' is not valid amount.
1105 Provided start value '1000' is greater than end value '500' for request parameter 'adopted_budget'.
1106 Provided response column 'agencyname' value is not allowed for 'Payroll' domain. Valid values are 'agency_name, department_name, expense_category, budget_code, budget_code_name, current_modified_budget, adopted_budget, pre_encumbered, encumbered, cash_expense, post_adjustment, accrued_expense'.
1108 Provided value 'abcd' for request parameter 'agency_code' exceeds maximum allowed '3' characters.
1109 Provided 'start' value '1234567890' for request parameter 'adopted_budget' exceeds maximum allowed '5' characters.
1110 Request parameter 'agency_code' do not support range values.
 

Overview

In July of 2010 the New York City Comptroller’s Office launched Checkbook NYC, an online transparency tool that for the first time placed the City’s day-to-day spending in the public domain. Using an intuitive dashboard approach that combines a series of graphs and user-friendly tables, Checkbook NYC provides up-to-date information about the City's financial condition.

Checkbook NYC has been ranked the top transparency tool in the nation for tracking government spending by the United States Public Interest Research Group, and was named New York City 2013 “Best External Application” by Government Technology Magazine.


 

Spotlight