Differences

This shows you the differences between two versions of the page.

--- api-contacts [2015/10/22 12:18]
ben [Request Body]
+++ api-contacts [2018/05/23 11:29] (current)
benc
@@ Line 2: / Line 2: @@
 The Contact Endpoints are used to modify Contacts within Sentori.
+===== Get a Contact =====
+This endpoint is used to retrieve a [[/contacts|Contact]] from your Sentori Account, either by their SystemID or EmailAddress.
+All Fields that can be exported through the web interface are included in the response.
+==== Endpoint ====
+|URI| <nowiki>https://api.sentoriapp.com/v2.0/contact/get/[SystemID or EmailAddress]/</nowiki>|
+|Method| GET|
+Examples:
+<nowiki>GET https://api.sentoriapp.com/v2.0/contact/get/joe%40example.sentoriapp.com/</nowiki>
+<nowiki>GET https://api.sentoriapp.com/v2.0/contact/get/16382/</nowiki>
+==== Response ====
+|HTTP Status|Description|
+|200|The Contact was found and returned.|
+For other response codes, see the [[api-errors|Error List]].
+|Example Response:|<code javascript>
+{
+  "IsSuppressed" : false,
+  "IsBadEmailAddress" : false,
+  "SystemID" : 16382,
+  "CRMID" : null,
+  "Title" : "Mr",
+  "FirstName" : "Joe",
+  "LastName" : "Example",
+  "KnownAs" : null,
+  "EmailAddress" : "joe@example.sentoriapp.com",
+  "CompanyName" : null,
+  "PhoneNumber" : null,
+  "MobilePhoneNumber" : null,
+  "CreatedSourceValue" : "Uploaded",
+  "CreatedIPAddress" : "127.0.0.1",
+  "CreatedHttpReferrerUrl" : null,
+  "CreatedTimestamp" : "2010-05-13T09:00:00",
+  "ModifiedTimestamp" : "2010-05-13T09:00:00",
+  "IsConfirmed" : true,
+  "IsBadMobilePhoneNumber" : false
+}
+</code>|
 ===== Add a Contact =====
-This endpoint is used to add a new [[/contacts|Contact]] to the Sentori Account. If no [[/contact-fields|Contact Fields]] need to be set then the [[/contacts|Contact]] can be added using a GET request, when including [[/contact-fields|Contact Fields]] in a request then they must be in a POST request body.
+This endpoint is used to add a new [[/contacts|Contact]] to the Sentori Account.
 Note: The EmailAddress [[/contact-fields|Contact Field]] should not appear in the Add request body, and will fail if it doesn't match the request URI.
@@ Line 11: / Line 59: @@
 |URI| <nowiki>https://api.sentoriapp.com/v2.0/contact/add/joe%40example.sentoriapp.com/</nowiki>|
-|Method| GET, or POST if sending additional fields|
+|Method| POST|
 ==== Request Body ====
-Request body is only required if including [[/contact-fields|Contact Fields]]. The example below would add a new [[/contacts|Contact]] with the FirstName and LastName [[/contact-fields|Contact Fields]] being set.
+Request body is only needed if including [[/contact-fields|Contact Fields]]. The example below would add a new [[/contacts|Contact]] with the FirstName and LastName [[/contact-fields|Contact Fields]] being set.
 |Example|<code javascript>{
@@ Line 22: / Line 70: @@
 }</code>|
+==== Response ====
+The complete Contact as it then exists in Sentori is returned.
+See the [[#get-a-contact|Get a Contact]] endpoint's Example Response for details.
 ===== Update a Contact =====
@@ Line 43: / Line 95: @@
 }</code>|
+==== Response ====
+The complete Contact as it then exists in Sentori is returned.
+See the [[#get-a-contact|Get a Contact]] endpoint's Example Response for details.
 ===== Add or Update a Contact =====
@@ Line 86: / Line 142: @@
 For other responses, see the [[api-errors|Error List]].
+For a successful result, the complete Contact as it then exists in Sentori is returned.
+See the [[#get-a-contact|Get a Contact]] endpoint's Example Response for details.
+In the described situation of the original Request's URI //and// body containing an Email Address and a Contact eixsting for both of them, the Contact with the body's Email Address is returned.
+===== Delete a Contact =====
+This endpoint is used to delete an existing [[/contacts|Contact]] from the Sentori Account.
+==== Endpoint ====
+|URI| <nowiki>https://api.sentoriapp.com/v2.0/contact/delete/joe%40example.sentoriapp.com/</nowiki>|
+|Method| POST|
+==== Request Body ====
+Leave blank.
+===== Get Contact Structure =====
+This endpoint is used to retrieve an example structure of a [[/contacts|Contact]] in your Sentori Account.  This may be useful when integrating Sentori with another system that has the ability to represent this within its interface.
+Only Fields that can be imported into are included in the response.
+==== Endpoint ====
+|URI| <nowiki>https://api.sentoriapp.com/v2.0/contact/getstructure/[single or list]/</nowiki>|
+|Method| GET|
+Examples:
+<nowiki>GET https://api.sentoriapp.com/v2.0/contact/getstructure/single/</nowiki>
+<nowiki>GET https://api.sentoriapp.com/v2.0/contact/getstructure/list/</nowiki>
+==== Response ====
+|HTTP Status|Description|
+|200|The Contact structure was successfully returned.|
+For other response codes, see the [[api-errors|Error List]].
+|Example "single" Response:|<code javascript>
+{
+  "IsBadEmailAddress" : false,
+  "CRMID" : "string",
+  "Title" : "string",
+  "FirstName" : "string",
+  "LastName" : "string",
+  "KnownAs" : "string",
+  "EmailAddress" : "string",
+  "CompanyName" : "string",
+  "PhoneNumber" : "string",
+  "MobilePhoneNumber" : "string",
+  "IsBadMobilePhoneNumber" : false
+}
+</code>|
+|Example "list" Response:|<code javascript>
+[
+  {
+    "IsBadEmailAddress" : false,
+    "CRMID" : "string",
+    "Title" : "string",
+    "FirstName" : "string",
+    "LastName" : "string",
+    "KnownAs" : "string",
+    "EmailAddress" : "string",
+    "CompanyName" : "string",
+    "PhoneNumber" : "string",
+    "MobilePhoneNumber" : "string",
+    "IsBadMobilePhoneNumber" : false
+  }
+]
+</code>|
@@ Line 96: / Line 233: @@
 |URI| <nowiki>https://api.sentoriapp.com/v2.0/contact/subscribe/joe%40example.sentoriapp.com/MailingListExternalID/</nowiki>|
-|Method| GET |
+|Method| POST |
 ===== Unsubscribe Contact from Mailing List =====
@@ Line 106: / Line 243: @@
 |URI| <nowiki>https://api.sentoriapp.com/v2.0/contact/unsubscribe/joe%40example.sentoriapp.com/MailingListExternalID/</nowiki>|
-|Method| GET |
+|Method| POST |
 ===== Unsubscribe Contact =====
@@ Line 116: / Line 253: @@
 |URI| <nowiki>https://api.sentoriapp.com/v2.0/contact/unsubscribe/joe%40example.sentoriapp.com/</nowiki>|
-|Method| GET |
+|Method| POST |
 ===== Import Contacts =====
@@ Line 130: / Line 267: @@
 |Field| Type|Required|Description |
-|Contacts|array|true| Array of the [[/contacts|Contacts]] to be included in the import. Must include the Email Address.|
+|Contacts|array|yes| Array of the [[/contacts|Contacts]] to be included in the import. Must include the Email Address.|
-|Description|string|false| Will be the description of the created [[/upload-groups|Upload Group]].|
+|Description|string|no| Will be the description of the created [[/upload-groups|Upload Group]].|
-|Name|string|false| Will be the name of the created [[/upload-groups|Upload Group]].|
+|Name|string|no| Will be the name of the created [[/upload-groups|Upload Group]].|
 |Example|<code javascript>{
@@ Line 148: / Line 285: @@
 |Field| Type|Description |
-|CreatedContacts|int| Number of new [[/contacts|Contacts]] created.|
+|TotalRows|int| Number of contacts in the request.|
-|UpdatedContacts|int| Number of existing [[/contacts|Contacts]] who where updated.|
+|EmailableRowsCreated|int| Number of new and Emailable [[/contacts|Contacts]] created.|
-|InvalidEmailAddresses|int| Number of  [[/contacts|Contacts]] who couldn't be Imported as the Email Addresses weren't valid.|
+|EmailableRowsUpdated|int| Number of existing and Emailable [[/contacts|Contacts]] who where updated.|
-|IgnoredAsSuppressed|int| Number of [[/contacts|Contacts]] who weren't Imported as they are already [[/suppressed-contacts|Suppressed]].|
+|SuppressedUpdated|int| Number of [[/contacts|Contacts]] who are [[/suppressed-contacts|Suppressed]] and were updated.|
-|IgnoredAsDuplicate|int| Number of [[/contacts|Contacts]] who weren't Imported as they where duplicated in the request.|
+|BadEmailUpdated|int| Number of existing Bad Email Address [[/contacts|Contacts]] who were updated.|
-|IgnoredAsRoleBased|int| Number of [[/contacts|Contacts]] who weren't Imported as they are role based.|
+|ExcludedDuplicates|int| Number of [[/contacts|Contacts]] who weren't Imported as they where duplicated in the request.|
-|UploadGroupID|int| ID of the [[/upload-groups|Upload Group]] created by this Import.|
+|ExcludedInvalidEmail|int| Number of  [[/contacts|Contacts]] who couldn't be Imported as the email addresses weren't valid.|
+|ExcludedRoleBased|int| Number of [[/contacts|Contacts]] who weren't Imported as they have role-based email addresses.|
+|UploadGroupExternalID|string| ExternalID of the [[/upload-groups|Upload Group]] created by this Import or null if no Contacts were actually imported.|
-|Example|<code javascript>
-{"CreatedContacts":4,"UpdatedContacts":2,"InvalidEmailAddresses":1,"IgnoredAsSuppressed":0,"IgnoredAsDuplicate":0,"IgnoredAsRoleBased":1,"UploadGroupID":1}</code>|
-===== Import Contacts, Attach to Draft Email =====
+Example
+<code javascript>
+{
+	"TotalRows": 4,
+	"EmailableRowsCreated": 1,
+	"EmailableRowsUpdated": 2,
+	"SuppressedUpdated": 1,
+	"BadEmailUpdated": 0,
+	"ExcludedDuplicates": 0,
+	"ExcludedInvalidEmail": 0,
+	"ExcludedRoleBased": 0,
+	"UploadGroupExternalID": "1234ABCD"
+}
+</code>
-This endpoint is used to attach an Upload Group to a Draft Email.
+===== Attach an Upload Group to Draft Email =====
+This endpoint is used to attach an existing Upload Group to a Draft Email in preparation for sending.
 ==== Endpoint ====
-|URI| <nowiki>https://api.sentoriapp.com/v2.0/contact/import/{{UploadGroupID}}/attach/{{ExternalID}}</nowiki>|
+|URI| <nowiki>https://api.sentoriapp.com/v2.0/contact/import/{{UploadGroupExternalID}}/attach/{{DocumentExternalID}}</nowiki>|
-|Method| GET |
+|Method| POST |