Contact api update

source/includes/_api_endpoint_contacts.md

@@ -22,6 +22,7 @@ $contactApi = $api->newApi("contacts", $auth, $apiUrl);
 $contact = $contactApi->get($id);
 ```
 ```json
+  {
     "contact": {
         "id": 47,
         "dateAdded": "2015-07-21T12:27:12-05:00",
@@ -105,6 +106,7 @@ $contact = $contactApi->get($id);
             }
         }
     }
+  }
 ```
 Get an individual contact by ID.
 
@@ -320,13 +322,13 @@ Same as [Get Contact](#get-contact).
 ```php
 <?php
 
-$data = array(
+$data = [
     'firstname' => 'Jim',
     'lastname'  => 'Contact',
     'email'     => '[email protected]',
     'ipAddress' => $_SERVER['REMOTE_ADDR'],
     'overwriteWithBlank' => true,
-);
+];
 
 $contact = $contactApi->create($data);
 ```
@@ -358,20 +360,20 @@ Same as [Get Contact](#get-contact).
 ```php
 <?php
 
-$data = array(
-    array(
-	'firstname' => 'Jim',
-	'lastname'  => 'Contact',
-	'email'     => '[email protected]',
-	'ipAddress' => $_SERVER['REMOTE_ADDR']
-    ),
-    array(
-    	'firstname' => 'John',
-	'lastname'  => 'Doe',
-	'email'     => '[email protected]',
-	'ipAddress' => $_SERVER['REMOTE_ADDR']
-    )
-);
+$data = [
+    [
+        'firstname' => 'Jim',
+        'lastname'  => 'Contact',
+        'email'     => '[email protected]',
+        'ipAddress' => $_SERVER['REMOTE_ADDR']
+    ],
+    [
+        'firstname' => 'John',
+        'lastname'  => 'Doe',
+        'email'     => '[email protected]',
+        'ipAddress' => $_SERVER['REMOTE_ADDR']
+    ]
+];
 $contact = $contactApi->createBatch($data);
 ```
 Create a batch of new contacts.
@@ -402,10 +404,10 @@ Array of contacts. Record is the same as [Get Contact](#get-contact).
 <?php
 
 $id   = 1;
-$data = array(
+$data = [
     'email'     => '[email protected]',
     'ipAddress' => $_SERVER['REMOTE_ADDR'],    
-);
+];
 
 // Create new a contact of ID 1 is not found?
 $createIfNotFound = true;
@@ -454,22 +456,22 @@ Same as [Get Contact](#get-contact).
 ```php
 <?php
 
-$data = array(
-    array(
+$data = [
+    [
         'id'        => 1,
         'firstname' => 'Jim',
         'lastname'  => 'Contact',
         'email'     => '[email protected]',
         'ipAddress' => $_SERVER['REMOTE_ADDR']
-    ),
-    array(
+    ],
+    [
         'id'        => 1,
         'firstname' => 'John',
         'lastname'  => 'Doe',
         'email'     => '[email protected]',
         'ipAddress' => $_SERVER['REMOTE_ADDR']
-    )
-);
+    ]
+];
 
 $contact = $contactApi->editBatch($data);
 ```
@@ -511,6 +513,40 @@ Contacts array. Record same as [Get Contact](#get-contact).
 > Note: In order to remove tag from contact add minus `-` before it.
 > For example: `tags: ['one', '-two']`  - sending this in request body will add tag `one` and remove tag `two` from contact.
 
+### Batch create/update error examples
+
+#### Maximum batch size limit
+
+The batch size limit is configurable with the `api_batch_max_limit` option. The default batch limit is 200 contacts per request. It can be changed in the `app/console/local.php` file. Increasing it may lead to timeouts so make sure you test your setup under heavy load before you increase this option. The response code in this case is `500 Internal Server Error`.
+
+```json
+{"errors":[{"code":500,"message":"A max of 200 entities are supported at a time.","details":[]}]}
+```
+
+#### Validation error
+
+In case some of the contacts in the batch have invalid values then the overall response code will be `201 Created` so you'll have to check for the response code for each contact separately in the response. In this example there were 2 contacts sent and one of them had invalid email address. The key in the error JSON object equals the key in the request starting from zero. In the example response the key is `"1"` which means the secod contact had invalid email address.
+
+_Note: Make sure you are not sending multiple contacts with the same unique identifiers (email address by default) in one batch request. Those contacts will get merged into one and then the response key may not match the request key because the response will have less contacts to return._
+
+```json
+{
+  "contacts": [
+    "[here is the array of contacts that were successfully saved. Replaced by this message to save space]"
+  ],
+  "errors": {
+    "1": {
+      "code": 400,
+      "message": "email: A valid email is required.",
+      "details": {
+        "email": ["A valid email is required."]
+      },
+      "type": null
+    }
+  }
+}
+```
+
 ### Delete Contact
 ```php
 <?php
@@ -534,7 +570,7 @@ Same as [Get Contact](#get-contact).
 ### Delete Batch Contact
 ```php
 <?php
-$data = array(1, 2);
+$data = [1, 2];
 $contact = $contactApi->deleteBatch($data);
 ```
 Delete contacts.
@@ -594,6 +630,7 @@ Same as [Get Contact](#get-contact).
 ### Remove from Do Not Contact
 ```php
 <?php
+
 $contactApi->removeDnc($contactId, $channel);
 ```
 
@@ -619,7 +656,7 @@ Same as [Get Contact](#get-contact).
 ```php
 <?php
 
-$data = array(
+$data = [
     'utm_campaign' => 'apicampaign',
     'utm_source'   => 'fb',
     'utm_medium'   => 'social',
@@ -631,7 +668,7 @@ $data = array(
     'query'        => ['cid'=>'abc','cond'=>'new'], // or as string with "cid=abc&cond=new"
     'remotehost'   => 'example.com',
     'lastActive'   => '2017-01-17T00:30:08+00:00'
- );
+];
 $contactApi->addUtm($contactId, $data);
 ```
 
@@ -691,10 +728,10 @@ Same as [Get Contact](#get-contact) without the removed UTM Tags.
 ```php
 <?php
 
-$data = array(
+$data = [
 	 'eventName' => 'Score via api',
 	 'actionName' => 'Adding',
- );
+];
 $contactApi->addPoints($contactId, $pointDelta, $data);
 ```
 
@@ -726,10 +763,10 @@ actionName|Name of the action
 ```php
 <?php
 
-$data = array(
+$data = [
 	 'eventname' => 'Score via api',
 	 'actionname' => 'Subtracting',
- );
+];
 $contactApi->subtractPoints($contactId, $pointDelta, $data);
 ```
 Subtract contact points