BatchBook API

People

BatchBook Contacts are split up within the API into People and Companies. The examples below are for people, and the methods for companies 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/people/#{id}.xml
Returns a single Person. The image fields will be nil if they have not been set.

Response

    
      Status: 200
      
      <person>
        <id type="integer">1</id>
        <first_name>Matt</first_name>
        <last_name>Gillooly</last_name>
        <small_image>https://s3.amazonaws.com/someimage_thumbnail_small.png</small_image>
        <large_image>https://s3.amazonaws.com/someimage_thumbnail_large.png</large_image>
        <title>Old Friend</title>
        <company>BatchBlue Software</company>
        <company_id type="integer">1234</company_id>
        <tags type="array">
          <tag>
            <id>397</id>
            <name>something</name>
            <supertag>false</supertag>
          </tag>
          <tag>
            <id>412</id>
            <name>awesome</name>
            <supertag>true</supertag>
            <fields>
              <cool_dude>true</cool_dude>
              <cool_since>Sep 08, 1982  9:34PM</cool_since>
            </fields>
          </tag>
        </tags>
        <locations type="array">
          <location>
            <id type="integer">67905</id>
            <label>work</label>
            <primary type="boolean">true</primary>
            <email>mgillooly@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>
        <notes>Hangs out in the BatchBook Developers Forum</notes>
        <created_at>Fri Feb 12 22:39:39 UTC 2010</created_at>
        <updated_at>Fri Feb 12 22:42:22 UTC 2010</updated_at>
      </person>

List All

GET /service/people.xml
Returns all People. By default only in groups of 10.

Parameters

Option Default Comment
offset 0
limit 10

Response

    
      Status: 200
      
      <people type="array">
        <person>
          ...
        </person>
        <person>
          ...
        </person>
      </people>

List By Search Term

GET /service/people.xml?name=Eric&email=@batchblue.com
Returns a collection of people 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
      
      <people type="array">
        <person>
          ...
        </person>
        <person>
          ...
        </person>
      </people>

Create

POST /service/people.xml
Creates a new Person record. Note: Company is not required. If Company does not exist, a new Company contact will be created. Company_id is not required. If both company_id and company parameters are present, the company name is used.

Request

    
      <person>
        <first_name>Bob</first_name>
        <last_name>Smith</last_name>
        <title>Jester</title>
        <notes>Very funny guy</notes>
        <company>Bob's Food Shack'</company>
        <company_id>951</company_id>
      </person>

Response

    
    Status: 201
    Location: https://{#accountname}.batchbook.com/service/people/{#new_person_id}.xml

Update

PUT /service/people/#{id}.xml
Updates an existing person. Note: Company is not required. If left blank, the company association will be removed. If Company does not exist, a new Company contact will be created.

Request

    
      <person>
        <first_name>Bob</first_name>
        <last_name>Smith</last_name>
        <title>Jester</title>
        <notes>Very funny guy</notes>
        <company>Bob's Food Shack'</company>
      </person>

Response

    
      Status: 200

Destroy

DELETE /service/people/#{id}.xml
Destroys the person at the referenced url.

Response

    
      Status: 200

List all Communications with a Person

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

List all Todos for a Person

GET /service/people/#{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 Person

GET /service/people/#{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>Sibling</label>
        </affiliation>
        <affiliation>
          ...
        </affiliation>
      </affiliations>