Merge pull request #1908 from sendgrid/contactdb_api_update

Update Contacts API docs

Author: eschallock

source/API_Reference/Web_API_v3/Marketing_Campaigns/contactdb.apiblueprint

@@ -40,7 +40,8 @@ Lists
 
 Recipients
 <ul>
-<li><a href="{{root_url}}/API_Reference/Web_API_v3/Marketing_Campaigns/contactdb.html#Add-Recipients-POST">Add Recipients - POST</a></li>
+<li><a href="{{root_url}}/API_Reference/Web_API_v3/Marketing_Campaigns/contactdb.html#Add-Single-Recipient-POST">Add a Single Recipient - POST</a></li>
+<li><a href="{{root_url}}{{root_url}}/API_Reference/Web_API_v3/Marketing_Campaigns/contactdb.html#Add-Multiple-Recipients-POST">Add Multiple Recipients - POST</a></li>
 <li><a href="{{root_url}}/API_Reference/Web_API_v3/Marketing_Campaigns/contactdb.html#Update-Recipient-PATCH">Update a Recipient - PATCH</a></li>
 <li><a href="{{root_url}}/API_Reference/Web_API_v3/Marketing_Campaigns/contactdb.html#Delete-Recipient-DELETE">Delete one or more Recipients - DELETE</a></li>
 <li><a href="{{root_url}}/API_Reference/Web_API_v3/Marketing_Campaigns/contactdb.html#List-Recipients-GET">List Recipients - GET</a></li>
@@ -412,25 +413,51 @@ The rate at which recipients may be added to a list is limited to 1 request per
 
 ## Recipients [/contactdb/recipients]
 
-### Add Recipients [POST]
+{% info %}
+If you make a request to upload a duplicate recipient and your request would make no change to the original recipient, the original recipient will remain unchanged and its index will be added to the unmodified_indices list.
+{% endinfo %}
+
+### Add Single Recipient [POST]
 
 The rate at which recipients may be uploaded is limited to 3 requests every 2 seconds. Recipients may be uploaded in batches of 1000 per request. This results in a maximum upload rate of 1500 recipients per second.
 
++ Request (application/json)
+
+     + Body
+
+            [{"email": "[email protected]", "last_name": "Jones", "pet": "Fluffy", "age": 25}]
+
++ Response 201
+
+     + Body
+
+            {"error_count":0,"error_indices":[],"unmodified_indices":[],"new_count":1,"persisted_recipients":["am9uZXNAZXhhbXBsZS5jb20="],"updated_count":0}
+
++ Response 400
+
+     + Body
+
+            "" : "Returned if request body is not valid json"
+
+
+### Add Multiple Recipients [POST]
+
 + Request (application/json)
 
      + Body
 
             [
-                {"email": "[email protected]", "last_name": "Jones", "pet": "Indiana", "age": 25},
+                {"email": "[email protected]", "last_name": "Jones", "pet": "Fluffy", "age": 25},
                 {"email": "[email protected]", "last_name": "Miller", "pet": "FrouFrou", "age": 32},
-                {"email": "invalid_email", "last_name": "Smith", "pet": "Spot", "age": 17}
+                {"email": "invalid_email", "last_name": "Smith", "pet": "Spot", "age": 17},
+                {"email": "[email protected]"}
             ]
 
 + Response 201
 
      + Body
 
-            {"error_count":1,"error_indices":[2],"new_count":2,"persisted_recipients":["YUBh", "bWlsbGVyQG1pbGxlci50ZXN0"],"updated_count":0, "errors":[{"message":"Invalid email.", "error_indices":[2]}]}
+            {"error_count":1,"error_indices":[2],"unmodified_indices":[3],"new_count":2,"persisted_recipients":["YUBh", "bWlsbGVyQG1pbGxlci50ZXN0"],"updated_count":0, "errors":[{"message":"Invalid email.", "error_indices":[2]}]}
 
 + Response 400
 
@@ -447,14 +474,15 @@ Updates one or more recipients. The body is a list of recipient objects.
      + Body
 
             [
-              {"email": "[email protected]", "last_name": "Jones"}
+              {"email": "[email protected]", "last_name": "Jones"},
+              {"email": "[email protected]"}
             ]
 
 + Response 201
 
      + Body
 
-            {"error_count":0,"error_indices":[],"new_count":0,"persisted_recipients":["am9uZXNAZXhhbXBsZS5jb20="],"updated_count":1}
+            {"error_count":0,"error_indices":[],"unmodified_indices":[1],"new_count":0,"persisted_recipients":["am9uZXNAZXhhbXBsZS5jb20="],"updated_count":1}
 
 + Response 400
 
@@ -485,7 +513,6 @@ Returned if at least one recipient was deleted
             "" : "Returned if all of the provided recipient ids are invalid"
             "" : "Returned if request body is not valid json"
 
-
 ## Recipients [/contactdb/recipients?page_size=100&page=1]
 
 {% info %}