BatchBook API

Companies

BatchBook Contacts are split up within the API into People and Companies. While the examples below are for companies, the methods for people are documented here. Both are standard REST implementations with support for GET/POST/PUT/DELETE requests.

Note: Each of these requests requires that you authenticate with a BatchBook account. This requires an account name and an API token. For more information on authentication, visit the API homepage.

Methods

Show

GET /service/companies/#{id}.xml
Returns a single Company. The image fields will be nil if they have not been set.

Response

    
      Status: 200
      
      <company>
        <id type="integer">1</id>
        <name>BatchBlue Software</name>
        <notes>Makers of BatchBook</notes>
        <small_image>https://s3.amazonaws.com/someimage_thumbnail_small.png</small_image>
        <large_image>https://s3.amazonaws.com/someimage_thumbnail_large.png</large_image>
        <tags type="array">
          <tag>
            <id>397</id>
            <name>software company</name>
            <supertag>false</supertag>
          </tag>
          <tag>
            <id>216</id>
            <name>social media</name>
            <supertag>true</supertag>
            <fields>
              <twitter_username>batchblue</twitter_username>
              <flickr_username>batchbluesoftware</flickr_username>
              <work_blog>http://feeds.feedburner.com/batchblog</work_blog>
            </fields>
          </tag>
          <tag>
            <id>304</id>
            <name>freshbooks</name>
            <supertag>false</supertag>
          </tag>
        </tags>
        <locations type="array">
          <location>
            <id type="integer">67905</id>
            <label>work</label>
            <primary type="boolean">true</primary>
            <email>info@batchblue.com</email>
            <website>http://batchblue.com/</website>
            <phone>(888) 40-BATCH (22824)</phone>
            <cell></cell>
            <fax>(401) 633-6526</fax>
            <street_1>18 Maple Ave.</street_1>
            <street_2>Suite #300</street_2>
            <city>Barrington</city>
            <state>RI</state>
            <postal_code>02806</postal_code>
            <country>US</country>
          </location>
        </locations>
        <mega_comments type="array">
          <mega_comment>
            <id type="integer">156</id>
            <comment>Best comment ever</comment>
            <user>Eric Krause</user>
            <created_at type="datetime">2010-07-06 17:24:51 -0400</created_at>
            <record_id type="integer">1</record_id>
          </mega_comment>
        </mega_comments>
        <created_at>Thu Sep 02 14:34:34 UTC 2010</created_at>
        <updated_at>Thu Sep 02 16:33:23 UTC 2010</updated_at>
      </company>

List All

GET /service/companies.xml
Returns all Companies. By default only in groups of 10.

Parameters

Option Default Comment
offset 0
limit 10

Response

    
      Status: 200
      
      <companies type="array">
        <company>
          ...
        </company>
        <company>
          ...
        </company>
      </companies>

List By Search Term

GET /service/companies.xml?name=Batchblue&email=batchblue.com
Returns a collection of companies that match the query passed in through the url.

Parameters

Option Default Comment
name None Search for all People by name.
email None Search by email. Can be part of an email address as well.
updated_since None Search by the last time the record was updated. Example Jul 01 13:37:38 UTC 2010
tag None Search for all People with a given tag.
state None Search for all People in a state. Example: RI

Response

    
      Status: 200
      
      <companies type="array">
        <company>
          ...
        </company>
        <company>
          ...
        </company>
      </companies>

Create

POST /service/companies.xml
Creates a new Company record.

Request

    
      <company>
        <name>foo company</name>
        <notes>My favorite place to get foo</notes>
      </company>

Response

    
      Status: 201
      Location: https://{#accountname}.batchbook.com/service/companies/{#new_company_id}.xml

Update

PUT /service/companies/#{id}.xml
Updates an existing Company.

Request

    
      <company>
        <name>foo company</name>
        <notes>My favorite place to get foo</notes>
      </company>

Response

    
      Status: 20

Destroy

DELETE /service/companies/#{id}.xml
Destroys the company at the referenced url.

Response

    
      Status: 200

List all Communications with a Company

GET /service/companies/#{id}/communications.xml
This will get all of the communications that this company is involved in. Please see the Communications page for the format.

List all Todos for a Company

GET /service/companies/#{id}/todos.xml
This will get all of the todos for this person. Please see the Todos page for the format.

List all Affiliations for a Company

GET /service/companies/#{id}/affiliations.xml

Response

    
      Status: 200

      <affiliations type="array">
        <affiliation>
          <record_id type="integer">1234</record_id>
          <record_type>Individual</record_type>
          <record_name>Bob Smith</record_name>
          <label>Partner</label>
        </affiliation>
        <affiliation>
          ...
        </affiliation>
      </affiliations>

List all Employees of a Company

GET /service/companies/#{id}/people.xml
Returns the Person information for every employee. See the People resource for format.

Response

    
      Status: 200
      
      <people type="array">
        <person>
          <company>BatchBlue Software</company>
          <company_id type="integer">53005</company_id>
          ...
        </person>
        <person>
          <company>BatchBlue Software</company>
          <company_id type="integer">53005</company_id>
          ...
        </person>
      </people>