API

• 201. Additionally, an HTTP Location: header that points to the new API URL for the new employee will be returned.

• 400 if the posted XML is invalid or the firstName/lastName fields are not provided.

<!-- Sample request that creates a new employee and sets their first and last names. -->
<employee>	
	<field id="firstName">John</field>	
	<field id="lastName">Doe</field>
</employee>

• The {fieldList} is a comma separated list of values taken from the official list of field names.
• {number} is an employee id. The special employee id of zero (0) means to use the employee id associated with the API key (if any).

• 200. The response content will be an XML document with the requested information. Any fields that the API user does not have permission to see will be empty in the response.

• 403 if the API user does not have permission to see the requested employee
• 404 if the employee does not exist

• XML
• JSON

<employee id="123">
	<field id="firstName">John</field>
	<field id="lastName">Doe</field>
</employee>

{
	"id":123,
	"firstName":"John",
	"lastName":"Doe"
}

• 200. A successful response is possible even if one or more updates were dis-allowed because of permissions. As long as a single field is updated a 200 response will be returned.

• 400 if the provided XML is bad
• 403 if the user doesn't have perms to see the employee
• 403 if the user doesn't have perms to update ANY of the requested fields
• 404 if the employee to be updated doesn't exist

<employee>
	<field id="firstName">John</field>
	<field id="lastName">Doe</field>
</employee>

• 200. The response content will be an XML document with the directory information. Only configured fields will be included in the directory. This directory bypasses normal permissions, and shows information for all employees in the company.

• 403 if the directory has not been shared company-wide

• XML
• JSON

<directory>
	<fieldset>
		<field id="displayName">Display name</field>
		<field id="firstName">First name</field>
		<field id="lastName">Last name</field>
		<field id="jobTitle">Job title</field>
		<field id="workPhone">Work Phone</field>
		<field id="workPhoneExtension">Work Extension</field>
	</fieldset>
	<employees>
		<employee id="123">
			<field id="displayName">John Doe</field>
			<field id="firstName">John</field>
			<field id="lastName">Doe</field>
			<field id="jobTitle">Customer Service Representative</field>
			<field id="workPhone">555-555-5555</field>
			<field id="workPhoneExtension"/>
		</employee>
	</employees>
</directory>

{
	"fields": [
		{
			"id": "displayName",
			"type": "text",
			"name": "Display Name"
		},
		{
			"id": "firstName",
			"type": "text",
			"name": "First Name"
		},
		{
			"id": "lastName",
			"type": "text",
			"name": "Last Name"
		},
		{
			"id": "jobTitle",
			"type": "list",
			"name": "Job Title"
		},
		{
			"id": "workPhone",
			"type": "text",
			"name": "Work Phone"
		},
		{
			"id": "workPhoneExtension",
			"type": "text",
			"name": "Work Extension"
		}
	],
	"employees": [
		{
			"id":123,
			"displayName":"John Doe",
			"firstName":"John",
			"lastName":"Doe",
			"jobTitle":"Customer Service Representative",
			"workPhone":"555-555-5555",
			"workPhoneExtension":null
		}
	]
}

• format - the output format for the report. Supported formats: csv, pdf, xls, xml, json
• fd (optional) - yes=apply standard duplicate field filtering, no=return the raw results with no duplicate filtering. Default value is "yes".

• 200 The report will be generated in the requested format. The HTTP Content-type header will be set with the mime type for the response.

• 404 if you request a non-existant report number

• XML
• JSON

<report>
	<title>This is my report</title>
	<!-- The "fields" section provides some metadata about the result set -->
	<fields>
		<field id="firstName" type="text" />
		<field id="lastName" type="text" />
	</fields>
	<data>
		<row>
			<!-- See the "fields" section above to determine field order -->
			<field>Jane</field>
			<field>Doe</field>
		</row>
		<row>
			<field>John</field>
			<field>Doe</field>
		</row>
	</data>
</report>

{
	"title": "This is my report",
	"fields": [
		{
			"id": "firstName",
			"type": "text",
			"name": "First Name"
		},
		{
			"id": "lastName",
			"type": "text",
			"name": "Last Name"
		},
	],
	"employees": [
		{
			"firstName":"John",
			"lastName":"Doe",
		}
	]
}

You may specify a filter section with a <lastChanged> tag (see below). If you add a filter then you must provide a date in ISO 8601 format and the report will only include those employees whose records have changed since that time.

Note: prior to June 2011, last change information was not tracked. Employees who have not changed since that time will always be returned in this API, unless you specify that the filter not include null changed dates. To hide null change dates set includeNull="no", as demonstrated in the example below.

• 200 The report will be generated in the requested format. The HTTP Content-type header will be set with the mime type for the response.

<report output="pdf">
	<title>This is my report</title>
	<!-- The filters section is optional -->	
	<filters>
		<lastChanged includeNull="no">2012-10-17T16:00:00Z</lastChanged>
	</filters>
	<!-- End optional section -->
	<fields>
		<field id="firstName" />
		<field id="lastName" />
	</fields>	
</report>

• XML
• JSON

<report>
	<title>This is my report</title>
	<!-- The "fields" section provides some metadata about the result set -->
	<fields>
		<field id="firstName" type="text" />
		<field id="lastName" type="text" />
	</fields>
	<data>
		<row>
			<!-- See the "fields" section above to determine field order -->
			<field>Jane</field>
			<field>Doe</field>
		</row>
		<row>
			<field>John</field>
			<field>Doe</field>
		</row>
	</data>
</report>

{
	"title": "This is my report",
	"fields": [
		{
			"id": "firstName",
			"type": "text",
			"name": "First Name"
		},
		{
			"id": "lastName",
			"type": "text",
			"name": "Last Name"
		},
	],
	"employees": [
		{
			"firstName":"John",
			"lastName":"Doe",
		}
	]
}

• 200 The response content will be an XML document with the requested information. The files will be contained within their category's xml wrapper.

• 404 if no files are found for this employee.
• 403 if the API user does not have permission to see the requested employee or the employee's files

<employee id="123">
	<category id="1">
		<name>New Hire Docs</name>
		<file id="1234">
			<name>Employee handbook</name>
			<originalFileName>employee_handbook.doc</originalFileName>
			<size>23552</size>
			<dateCreated>2011-06-28 16:50:52</dateCreated>
			<createdBy>John Doe</createdBy>
			<shareWithEmployee>yes</shareWithEmployee>
		</file>
	</category>
	<category id="112">
		<name>Training Docs</name>
	</category>
</employee>

• 201 The category was created.

• 403 if the API user does not have permission to create employee categories
• 400 if the posted XML is invalid or there was no category name given
• 500 there was an unknown server error.

<employee>
	<category>A new category</category>
</employee>

• name: rename the file
• categoryId: move the file to a different category
• shareWithEmployee: update whether this file is shared or not

• 200 if the file was updated.

• 403 if the API user does not have permission to see the requested employee or the employee's files
• 400 if the posted XML is invalid
• 404 if the employee file or category was not found

<file>
	<name>This is a new name for the file</name>
	<categoryId>4</categoryId>
	<shareWithEmployee>no</shareWithEmployee>
</file>

• 200 if the file was successfully retrieved. Additionally, HTTP headers are sent that provide the Content-Type, Content-Length, and Content-Disposition for the file. The file contents will be contained in the response contents.

• 403 if the API user does not have permission to see the requested employee or the employee's files
• 404 if the employee file was not found

• category - the category id to place the new file in.
• fileName - the file name to associate with the file.
• share - whether to make the file available to the employee (options are "yes" and "no")
• file - the file to upload. Note that the field must be named "file".

• 201 if the file was successfully uploaded.

• 403 if the API user does not have permission to see the requested employee or the employee's files
• 404 if the category ID was not found
• 413 if the file size exceeds 20 MB or the storage limit for the company

The file upload methods accept multi-part forms. To build a multi-part form concatenate the individual sections together separated by a boundary. Then take the length of the resulting body and use that as the Content-Length for the submission. (See here, here, and here.)

POST /api/gateway.php/sample/v1/employees/1/files/ HTTP/1.0
Host: api.bamboohr.com
Content-Type: multipart/form-data; boundary=----BambooHR-MultiPart-Mime-Boundary----
Content-Length: 520

------BambooHR-MultiPart-Mime-Boundary----
Content-Disposition: form-data; name="category"

112
------BambooHR-MultiPart-Mime-Boundary----
Content-Disposition: form-data; name="fileName"

readme.txt
------BambooHR-MultiPart-Mime-Boundary----
Content-Disposition: form-data; name="share"

yes
------BambooHR-MultiPart-Mime-Boundary----
Content-Disposition: form-data; name="file"; filename="readme.txt"
Content-Type: text/plain

This is a sample text file.

------BambooHR-MultiPart-Mime-Boundary------
							

• 200 The response content will be an XML document with the requested information. The files will be contained within their category's xml wrapper.

• 404 if no files or categories are found.
• 403 if the API user does not have permission to see the company files

<files>
 <category id="20">
  <name>New Employee Docs</name>
  <file id="387">
   <name>Direct Deposit Form</name>
   <originalFileName>Direct Deposit Form.rtf</originalFileName>
   <size>57028</size>
   <dateCreated>2009-08-28 15:56:58</dateCreated>
   <createdBy></createdBy>
   <shareWithEmployee>no</shareWithEmployee>
  </file>
 </category>
</files>

• 201 The category was created.

• 403 if the API user does not have permission to see the company files
• 400 if the posted XML is invalid or there was no category name given
• 500 there was an unknown server error.

<files>
	<category>A new category</category>
</files>

• name: rename the file
• categoryId: move the file to a different category
• shareWithEmployees: update whether this file is shared or not

• 200 if the file was updated.

• 403 if the API user does not have permission to see the company files
• 400 if the posted XML is invalid
• 404 if the file or category was not found

<file>
	<name>This is a new name for the file</name>
	<categoryId>4</categoryId>
	<shareWithEmployees>no</shareWithEmployee>
</file>

• 200 if the file was successfully retrieved. Additionally, HTTP headers are sent that provide the Content-Type, Content-Length, and Content-Disposition for the file. The file contents will be contained in the response contents.

• 403 if the API user does not have permission to see the company files
• 404 if the file was not found

• category - the category id to place the new file in.
• fileName - the file name to associate with the file.
• share - whether to make the file available to employees (options are "yes" and "no")
• file - the file to upload. Note that the field must be named "file".

• 201 if the file was successfully uploaded.

• 403 if the API user does not have permission to see the company files
• 404 if the category ID was not found
• 413 if the file size exceeds 20 MB or the storage limit for the company

The file upload methods accept multi-part forms. To build a multi-part form concatenate the individual sections together separated by a boundary. Then take the length of the resulting body and use that as the Content-Length for the submission. (See here, here, and here.)

POST /api/gateway.php/sample/v1/files/ HTTP/1.0
Host: api.bamboohr.com
Content-Type: multipart/form-data; boundary=----BambooHR-MultiPart-Mime-Boundary----
Content-Length: 520

------BambooHR-MultiPart-Mime-Boundary----
Content-Disposition: form-data; name="category"

112
------BambooHR-MultiPart-Mime-Boundary----
Content-Disposition: form-data; name="fileName"

readme.txt
------BambooHR-MultiPart-Mime-Boundary----
Content-Disposition: form-data; name="share"

yes
------BambooHR-MultiPart-Mime-Boundary----
Content-Disposition: form-data; name="file"; filename="readme.txt"
Content-Type: text/plain

This is a sample text file.

------BambooHR-MultiPart-Mime-Boundary------