batchblue / batchbook-api

Official API documentation for Batchbook

Batchbook API

THIS API IS DEPRECATED AND WILL BE RETIRED SOON. PLEASE CONTACT US FOR MORE DETAILS BEFORE BEGINNING ANY DEVELOPMENT AGAINST IT

The BB2 API is a RESTful interface for accessing and modifying your account.It supports both XML and JSON and a ruby library will be provided to help build client functionality.

Endpoints

• People
• Companies
• Custom Fields
• Affiliations
• Affiliation Types
• Users
• Roles
• Communications

Authentication

Authentication at launch will be using token authentication. The api_key for the user will be found at https://account_name.batchbook.com/preferences The api_key must be passed as a query parameter with the key "auth_token". For example. https://apitest.batchbook.com/api/v1/people.json?auth_token=GR5doLv88FrnLyLGIwok

There has been some work done on implementing oauth2 but it isn't complete at launch. If you feel this would make things easier for your integration please let us know.

Api Test Account

If you would like to quickly test some code against the api, you can use our open apitest account at apitest.batchbook.com. If you would like a personal account to test your integration against please write in to [email protected]. If you'd like to see how the data is rendering in batchbook you can go to https://apitest.batchbook.com/?auth_token=mXZ8syJrMYHzcxf8j83D

The apitest account has 4 users to use for testing.

[email protected], api key is 6B8YOw9x1tnbKZuUeVkc [email protected], GR5doLv88FrnLyLGIwok [email protected], mXZ8syJrMYHzcxf8j83D [email protected], DGJFgqRAmxGRVnM9wtYq

batchbook-api's Issues

Caching of auth_token or reading from cookie?

Seems that calling the api from the browser returns different results if you call it for multiple accounts in the same session (i.e. from a browser),

i.e.
https://apitest.batchbook.com/api/v1/people.xml?auth_token=GR5doLv88FrnLyLGIwok
and then
https://apitest.batchbook.com/api/v1/people.xml?auth_token=6B8YOw9x1tnbKZuUeVkc

both return data, but calling them in reverse order in a new session both return blank results. Seems to be related to a batchdeux_session cookie.

POST /people

Hi guys,

Getting 500 POSTing to this endpoint:

https://[account_name].batchbook.com/api/v1/people.json?auth_token=[auth_token]

Sending this json:

{'person': {'first_name': 'Test', 'last_name': 'Name'}}

Wanted to see if this was an issue on my end or if there a legitimate 500 error on your side.

[Update]: same for /companies

[Update]: Derp. My bad. Issue with my json.

Will there be a updated_since param?

Wil there be a updated_since parameter for gettings objects that have been updated since a specific date?

I need this for my app..

Add Tag to Person

Is there a way to add a tag and then add that tag to a person? Trying to create a tag, I'm getting a 501 (Not Implemented) posting to /api/v1/tags.xml (or json).

Primary Email, Phone, Address Indicators

Are there email, phone, or address indicators to indicate which one is the primary ones? It appears in the software for at least companies, there's a method to set one as primary/displayed, but doesn't seem to be anything in the API.

API does not accept the date format that it uses to format its own dates

We have a custom field set with a date value. When we access data from the Batchbook API, the date is returned to us like this:

{"id":xxxx,"custom_field_definition_id":34,"custom_field_definition_name":"Do Not Contact Before","datetime_value":"2013-10-07T00:00:00-07:00"}]}

Note the -07:00 GMT offset. However, if we try to simply send this value back, we receive a 422 Unprocessable Entity. Removing the GMT offset such that dates look like this:

{"id":xxxx,"custom_field_definition_id":34,"custom_field_definition_name":"Do Not Contact Before","datetime_value":"2013-10-07T00:00:00"}]}

Works and is accepted. It isn't practical to modify the values in data returned to us by the API in order to send them back to the API. Whatever it spits out, it should also accept.

Please change the API to accept the datetime values with GMT offset.

Production ready?

Is this API production ready?

Fetching people with email returns all record where email is similar

Hi,

I tried the following two requests.

/api/v1/people.xml?email=[email protected]&auth_token=xyz
/api/v1/people.xml?email=[email protected]&auth_token=xyz

Its mentioned in the docs that search with email is an exact search but the first record returns multiple records where the email matches it. The email id ex - [email protected] - returns one record where as search with email id [email protected] returns the record matching [email protected] and other records.

Is that how email is searched (performing a similar search and not returning records where the email exactly matches the email id passed in request)

OAuth2

Noticed you were listing this as coming. It really helps user adoption for integrations to have this. Fetching an API key for some users can be tricky.

Unable to POST to people

Hi guys,

Getting 422 POSTing to this endpoint:

https://[ACCOUNT].batchbook.com/api/v1/people.json?auth_token=[TOKEN]

Sending this json:

{'person': {'first_name': 'Test', 'last_name': 'Name'}}

Same with XML

Create a person

I am having a trouble creating a person.

Acording to the documentation. I've tried the following request:

request.post (https://"my account".batchbook.com/api/v1/people.json?auth_token="MyApikey", json=my_json)

my_json={"person":{"prefix":"Mr.", "first_name":"Eric","middle_name":"M","last_name":"Krause",
"emails":[{"address":"[email protected]","label":"work","primary": true}],}

The person is created successfully, but the fields emails is empty. This is my response:

{'person': {'comments': [], 'addresses': [], 'about': None, 'created_at': '2017-10-26T17:33:18-04:00', 'emails': [], 'cf_records': [], 'last_name': 'Krause', 'prefix': 'Mr.', 'websites': [], 'updated_at': '2017-10-26T17:33:18-04:00', 'id': 24, 'middle_name': 'M', 'first_name': 'Eric', 'phones': [], 'company_affiliations': [], 'tags': [], 'champion': False}}

I get the same result with the fields "phones" and "addresses"

Problem with tags removing

I have a problem with tags removing. I tried with (as documentation says):

"person":{
  "tags":[
    {
      "name":"One",
      "_destroy":"1"
    }
  ]
}

but tags are not removed. I tried also:

"person":{
  "tags":[
    {
      "id":2,
      "_destroy":"1"
    }
  ]
}

and:

"person":{
  "tags":[
    {
      "id":2,
      "name":"One",
      "_destroy":"1"
    }
  ]
}

I'm able to destroy email without a problem, but tags are not removed.

Here is curl command:

$ curl -i -H "Content-Type: application/json" -X PUT -d '{"person":{"tags":[{"name":"One","_destroy":"1"}]}}' -# https://bonias.batchbook.com/api/v1/people/1594.json?auth_token=xxx | head -n 1
######################################################################## 100,0%
HTTP/1.1 200 OK


$ curl https://bonias.batchbook.com/api/v1/people/1594.json?auth_token=xxx
{"person":{"id":1594,"about":null,"emails":[],"phones":[],"websites":[],"addresses":[],"tags":[{"id":2,"name":"One"}],"comments":[],"cf_records":[],"created_at":"2015-09-22T10:32:10-04:00","updated_at":"2015-09-22T10:39:00-04:00","prefix":null,"first_name":"TestContact remove tag","middle_name":null,"last_name":null,"champion":false,"company_affiliations":[]}}

Updating a custom field value

`I'm having trouble updating a custom field value.

According to the documentation, to update a nested field you just include the id. I've tried the following that return a status code 200 but doesn't update the boolean_value:
var update_options = { url : 'https://goalkeeper.batchbook.com/api/v1/people/' + 592 + '.json?auth_token=redacted', method: 'PUT', json: {person: { id:592, cf_records:[{ id: 1999, custom_field_set_id:6, custom_field_values:[ { id: 3986, custom_field_definition_id:43, boolean_value :false }] }] } } }

Company Affiliation -> Current Field changed to Primary-Detail

The People -> Company-Affiliations -> Company-Affiliation -> Current field appears to have been replaced with 'primary-detail'. This broke the integration I had. I've fixed my integration, however, it appears the documentation on the people page hasn't been updated and still shows the field as current.

Intermittent 503 responses

Hi guys,

We're getting 503 unavailable errors when creating a bunch of contacts through the API. We're trying to create 240 contacts but only 100-150 are actually created on first try. The others fail with:

"<html>\r\n<head><title>503 Service Temporarily Unavailable</title></head>\r\n<body bgcolor=\"white\">\r\n<center><h1>503 Service Temporarily Unavailable</h1></center>\r\n<hr><center>nginx/1.6.0</center>\r\n</body>\r\n</html>\r\n

Is this some kind of rate limiting on your side or is there a problem with the API currently?

Thanks!

Todos and comments

Are there plans to provide a service for todos and comments in the new api?