This API is deprecated.

We have launched a new version of Batchbook and it has its own API which can be found here.

Please do not develop new integrations agains this API! We are leaving it this documentation in place soley as a reference for developers supporting existing integrations with “Batchbook Classic.”

BatchBook API

Communications

Standard REST implementations with support for GET/POST/PUT/DELETE requests. Custom methods exist for listing, adding and removing participants from a communication.

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
  • List All
  • Search
  • Create
  • Update
  • Destroy
  • Participants:
  • Tags:
  • Comments:
  • Show

    GET /service/communications/#{id}.xml
    Returns a single communication.

    Response

        
          Status: 200
    
          <communication>
            <id type="integer">69522</id>
            <subject>Re: Hi again!</subject>
            <body>The body of the email</body>
            <date>2010-05-28 10:53:00 -0400</date>
            <ctype>Email</ctype>
            <tags type="array">
            </tags>
            <mega_comments type="array">
            </mega_comments>
            <created_at>Fri May 28 14:53:32 UTC 2010</created_at>
            <updated_at>Fri May 28 14:53:44 UTC 2010</updated_at>
          </communication>
        
      

    List All

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

    Parameters

    Option Default Comment
    offset 0
    limit 10

    Response

        
          Status: 200
    
          <communications type="array">
            <communication>
              ...
            </communication>
            <communication>
              ...
            </communication>
          </communications>
        
      

    Search

    GET /service/communications.xml
    Returns a collection of communications that match the query passed in through the url.

    Parameters

    Option Default Comment
    ctype None Communication Type (one of: "email", "note", "phone", or "chat")
    contact_id None The ID of the contact you would like query the communications for.
    updated_since None Search by the last time the communication was updated. Example Jul 01 13:37:38 UTC 2010
    updated_before None Return all communications that have been updated before a given time. Most likely used to return a range of dates with 'update_since'. Example Jul 01 13:37:38 UTC 2010
    created_since None Search by the creation date/time. Example Jul 01 13:37:38 UTC 2010
    created_before None Return all communications that were created before a given time. Most likely used to return a range of dates with 'created_since'. Example Jul 01 13:37:38 UTC 2010

    Response

        
          Status: 200
    
          <communications type="array">
            <communication>
              ...
              <ctype>Email</ctype>
            </communication>
            <communication>
              ...
              <ctype>Email</ctype>
            </communication>
          </communications>
        
      

    Create

    POST /service/communications.xml
    Create a new communication

    Request

        
          <communication>
            <subject>A Simple Communication</subject>
            <body>The body of the message</body>
            <date>Jul 01 13:37:38 UTC 2010</date>
            <ctype>note</ctype>
          </communication>
        
      

    Response

        
          Status: 201
          Location: https://{#accountname}.batchbook.com/service/communications/{#new_communication_id}.xml
        
      

    Update

    PUT /service/communications/#{id}.xml
    Updates and existing communication.

    Request

        
          <communication>
            <subject>A Simple Communication</subject>
            <body>The body of the message</body>
            <date>Jul 01 13:37:38 UTC 2010</date>
            <ctype>email</ctype>
          </communication>
        
      

    Response

        
          Status: 200
    
        
      

    Destroy

    DELETE /service/communications/#{id}.xml
    Destroys the communication at the referenced url.

    Response

        
          Status: 200
    
        
      

    List All Participants

    GET /service/communications/#{id}/participants.xml
    Returns all participants involved in the communication.

    Response

        
          Status: 200
    
          <participants type="array">
            <participant>
              <name>Matt Gillooly</name>
              <contact_id type="integer">4</contact_id>
              <role>from</role>
            </participant>
            <participant>
              <name>Pamela O'Hara</name>
              <contact_id type="integer">1</contact_id>
              <role>cc</role>
            </participant>
            <participant>
              ...
            </participant>
          </participants>
        
      

    List By Search Term

    GET /service/communications/#{id}/participants.xml
    Returns a collection of participants for a communication for a role.

    Parameters

    Option Default Comment
    role None Options are 'cc', 'bcc', 'to' and 'from'

    Response

        
          Status: 200
    
          <participants type="array">
            <participant>
              ...
              <role>cc</role>
            </participant>
            <participant>
              <name>Pamela O'Hara</name>
              <contact_id type="integer">1</contact_id>
              <role>cc</role>
            </participant>
            <participant>
              ...
              <role>cc</role>
            </participant>
          </participants>
        
      

    Add a Participant to a Communication

    PUT /service/communications/#{id}/add_participant.xml
    Adds a contact to a communication as a participant. The API won't accept this request as xml since there is no root node. This will be fixed in the future.

    Parameters

    Option Default Comment
    contact_id, person_id, or company_id None Required. The id of the contact being added as a participant.
    role None Required. The role the participant will play. Options are 'cc', 'bcc', 'to' and 'from'

    Response

        
          Status: 200
    
        
      

    Remove a Participant from a Communication

    DELETE /service/communications/#{id}/remove_participant.xml
    Removes a contact from a communication as a participant. The API won't accept this request as xml since there is no root node. This will be fixed in the future.

    Parameters

    Option Default Comment
    contact_id, person_id, or company_id None Required. The id of the contact being added as a participant.
    role None Required. The role the participant will play. Options are 'cc', 'bcc', 'to' and 'from'

    Response

        
          Status: 200