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