Batchbook curl post to api

batchbook_curl_post_api.md

Use the following curl command to POST xml data to the Batchbook api people endpoint. This will create a new Person contact in the apitest account.

curl -X POST -H "Content-Type: text/xml" -d "xml-string-data" "url"

where "xml-string-data" is something like:

<?xml version='1.0' encoding='UTF-8'?> <person> <about nil='true'/><champion type='boolean'>false</champion> <first-name>MyXml</first-name> <last-name>ApiTest</last-name> <middle-name nil='true'/> <name nil='true'/> <prefix nil='true'/> </person>

and "url" is your account url, with your auth_token and specified endpoint and data format, like: "https://apitest.batchbook.com/api/v1/people.xml?auth_token=DGJFgqRAmxGRVnM9wtYq"

Upon a successful post, this will return status code 200, the location of the new object, and the xml passed in. Errors will be returned if the record cannot be created.

If you are going to create custom field values via the API, first ensure you are using your correct custom-field-set-id and custom-field-definition-id. These values are the actual ids of existing custom field sets and custom field definitions. You can get all of your custom field sets and view the ids by doing something like curl "https://apitest.batchbook.com/api/v1/custom_field_sets.xml?auth_token=DGJFgqRAmxGRVnM9wtYq"

The same goes for comments attached to a specific user - the user-id you specify needs to be an actual user in your account.

Here's some xml that includes custom fields:

<person>
  <about>All around cool guy.</about>
  <prefix>Mr.</prefix>
  <first-name>MyXml</first-name>
  <middle-name>Is</middle-name>
  <last-name>Great</last-name>
  <champion>true</champion>
  <emails type="array">
    <email>
      <address>[email protected]</address>
      <label>work</label>
      <primary type="boolean">true</primary>
    </email>
  </emails>
  <phones type="array">
    <phone>
      <number>1 401 867 5309</number>
      <label>cell</label>
      <primary type="boolean">true</primary>
    </phone>
  </phones>
  <websites type="array">
    <website>
      <address>http://batchblue.com</address>
      <label>work</label>
      <primary type="boolean">true</primary>
    </website>
  </websites>
  <addresses type="array">
    <address>
      <address-1>171 Chestnut st</address-1>
      <address-2>2L</address-2>
      <city>Providence</city>
      <state>RI</state>
      <postal-code>02903</postal-code>
      <country>United States</country>
      <label>work</label>
      <primary type="boolean">true</primary>
    </address>
  </addresses>
  <tags type="array">
    <tag>
      <name>awesome</name>
    </tag>
  </tags>
  <comments type="array">
    <comment>
      <comment>A Simple Comment</comment>
      <user-id type="integer">1</user-id>
    </comment>
  </comments>
  <cf-records type="array">
    <cf-record>
      <custom-field-set-id type="integer">3</custom-field-set-id>
      <custom-field-values type="array">
        <custom-field-value>
          <custom-field-definition-id type="integer">3</custom-field-definition-id>
          <text-value>something important</text-value>
        </custom-field-value>
        <custom-field-value>
          <custom-field-definition-id type="integer">3</custom-field-definition-id>
          <text-value>also important</text-value>
        </custom-field-value>
      </custom-field-values>
    </cf-record>
  </cf-records>
</person>

Note that xml attributes such as email type="array" are double quoted, so the entire block of xml will need single quotes around it.

View the documentation here (https://github.com/batchblue/batchbook-api/blob/master/sections/people.md#create)

Spoke a bit too soon. The post is not creating an error, but the boolean data is not getting saved. My xml looks like:

<custom-field-value> <custom-field-definition-id type="integer">27</custom-field-definition-id> <boolean>%s</boolean> </custom-field-value>

which gets posted as:

<custom-field-value> <custom-field-definition-id type="integer">27</custom-field-definition-id> <boolean>True</boolean> </custom-field-value>

But the field is missing in the response.

For posting boolean custom field values, use the following format:

<boolean-value type="boolean">false</boolean-value>

and for true

<boolean-value type="boolean">true</boolean-value>

(note lowercase true / false and field name is boolean-value)

The custom field should be set up as Type: Yes or No

It's a little hidden in our documentation - sorry about that!
Here's details on setting up custom field xml

Hope this helps!