BatchBook API

Deals

Standard REST implementations with support for GET/POST/PUT/DELETE requests. Nested resources will be explained on their respective pages.

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/deals/#{id}.xml
Returns a single deal.

Response

    
    Status: 200
  
    <deal>
     <id type="integer">66765</id>
     <title>Integration</title>
     <description></description>
     <deal_with>ABC Company</deal_with>
     <deal_with_id>64642</deal_with_id>
     <status>pending</status>
     <assigned_to>Pamela O'Hara</assigned_to>
     <amount>0.00</amount>
     <attached_communications>
       <attached_communication_id type="integer">66634767</attached_communication_id>
     </attached_communications>
     <attached_contacts>
       <attached_contacts_id type="integer">66506767</attached_contacts_id>
       <attached_contacts_id type="integer">66553767</attached_contacts_id>
     </attached_contacts>
     <todos>
       <todo_id type="integer">691837676</todo_id>
       <todo_id type="integer">6918276767</todo_id>
     </todos>
     <tags type="array">
       <tag name="something">
         <id>397</id>
         <name>something</name>
         <supertag>false</supertag>
       </tag>
     </tags>
     <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>
    </deal>

List All

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

Parameters

Option Default Comment
offset 0
limit 10

Response

    
    Status: 200
  
    <deals type="array">
      <deal>
        ...
      </deal>
      <deal>
        ...
      </deal>
    </deals>

List By Search Term

GET /service/deals.xml?status=Pending&assigned_to=eric@yourcompany.com
Returns a collection of deals that match the the query passed in through the url.

Parameters

Option Default Comment
assigned_to None Search for all deals assigned to a user by email address. /service/users.xml for list of users and their email addresses
status None Search by status. /service/deals/statuses.xml for list of statuses
updated_since None Search by the last time the record was updated. Example Jul 01 13:37:38 UTC 2010

Response

    
    Status: 200
  
    <deals type="array">
      <deal>
        ...
        <status>pending</status>
        <assigned_to>Eric Krause</assigned_to>
      </deal>
      <deal>
        ...
        <status>pending</status>
        <assigned_to>Eric Krause</assigned_to>
      </deal>
    </deals>

Create

POST /service/deals.xml
Creates a new deal. Note: assigned_to is optional. If it isn't sent, the todo will by default be assigned to the current user. Also note that assigned_to is returned as the user's name in the Show action. However, to assign the todo to another user, the user's email address must be used. If the user name is sent back, it will be ignored. This will be deprecated in future releases most likely to be replaced by assigned_to and assigned_to_id.

Request

    
      <deal>
        <title>Integration</title>
        <description>This integration is very important</description>
        <amount>2.50</amount>
        <status>won</status>
        <deal_with_id>51</deal_with_id>
        <assigned_to>eric@yourcompany.com</assigned_to>
      </deal>

Response

    
    Status: 201
    Location: https://{#accountname}.batchbook.com/service/deals/{#new_deal_id}.xml

Update

PUT /service/deals/#{id}.xml
Updates an existing deal. Note: assigned_to is optional. If it isn't sent, the todo will by default be assigned to the current user. Also note that assigned_to is returned as the user's name in the Show action. However, to assign the todo to another user, the user's email address must be used. If the user name is sent back, it will be ignored. This will be deprecated in future releases most likely to be replaced by assigned_to and assigned_to_id.

Request

    
      <deal>
        <title>Integration</title>
        <description>This integration is very important</description>
        <amount>2.50</amount>
        <status>won</status>
        <deal_with_id>1234</deal_with_id>
        <assigned_to>eric@yourcompany.com</assigned_to>
      </deal>

Response

    
    Status: 200

Destroy

DELETE /service/deals/#{id}.xml
Destroys the deal at the referenced url.

Response

    
    Status: 200

Statuses

GET /service/deals/statuses.xml
Returns a listing of possible deal statuses.

Response

    
    Status: 200
    
    <statuses type="array">
      <status>Failure</status>
      <status>Lost</status>
      <status>Pending</status>
      <status>Won</status>
    </statuses>

Show Related Contacts Information

GET /service/deals/#{id}/people.xml
If the information for the attached_contacts for the Deal's Show action aren't enough, use the nested people resource to list the Person's details. This is currently only configured for People records, and not Companies. If you would like that functionality, please request it on the forums.

Response

    
      Status: 200
      See the People resource for format.