====== API Contact Endpoints ======

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.

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.

==== Endpoint ====

|URI| <nowiki>https://api.sentoriapp.com/v2.0/contact/add/joe%40example.sentoriapp.com/</nowiki>|
|Method| POST|

==== Request Body ====

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>{
    "FirstName":"Joe",
    "LastName":"Bloggs"
}</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 =====

This endpoint is used to update an existing [[/contacts|Contact's]] [[/contact-fields|Contact Fields]] in the Sentori Account. \\
If updating the EmailAddress use the existing one in the URI (and URL encode it) and the new one in the request body.

==== Endpoint ====

|URI| <nowiki>https://api.sentoriapp.com/v2.0/contact/update/joe%40example.sentoriapp.com/</nowiki>|
|Method| POST|

==== Request Body ====

Request body should contain the [[/contact-fields|Contact Fields]] to update. The below example updates the email address and first/last names.

|Example|<code javascript>{
    "EmailAddress":"joe@example.sentoriapp.com",
    "FirstName":"Joe",
    "LastName":"Bloggs"
}</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 =====

This endpoint can be used when you have some contact data and wish Sentori to decide whether it should perform an Add or an Update with it.

If you DON'T include an Email Address in the request's body, it behaves very simply:

  * Email Address doesn't exist: a new Contact is created.
  * Email Address does exist: the existing Contact is updated.


If you DO include an Email Address in the request body, it becomes more interesting.  Here are some examples showing what happens when a Contact does or does not exist:

  * URI's Email Address exists, body's doesn't: the existing Contact is updated and their Email Address changed.
  * Neither the URI's nor the body's Email Address exists: the endpoint will create a new Contact from the body's Email Address and values.
  * URI's Email Address doesn't exist, body's does: the endpoint will update the Contact that has the body's Email Address.
  * The URI's and body's Email Addresses both exist (and are different): both matching Contacts are updated with the body values (apart from Email Address).

==== Endpoint ====

|URI| <nowiki>https://api.sentoriapp.com/v2.0/contact/addorupdate/joe%40example.sentoriapp.com/</nowiki>|
|Method| POST|

==== Request Body ====

The Request body can contain [[/contact-fields|Contact Fields]] to add or update a Contact, as appropriate.  The below example includes the first and last names.

When including Email Address in the body, see the examples above for possible scenarios.

|Example|<code javascript>{
    "FirstName":"Joe",
    "LastName":"Bloggs"
}</code>|


==== Response ====

|HTTP Status|Description|
|200|A successful Update was performed.|
|201|A successful Add was performed.|

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>|


===== Subscribe Contact to Mailing List =====

This endpoint is used to subscribe a [[/contacts|Contact]] to a [[/mailing-lists|Mailing List]].\\
You can find the [[/mailing-lists|Mailing List]] external IDs on the [[/mailing-lists|Mailing List]] page in Sentori.

==== Endpoint ====

|URI| <nowiki>https://api.sentoriapp.com/v2.0/contact/subscribe/joe%40example.sentoriapp.com/MailingListExternalID/</nowiki>|
|Method| POST |

===== Unsubscribe Contact from Mailing List =====

This endpoint is used to unsubscribe a [[/contacts|Contact]] from a [[/mailing-lists|Mailing List]].\\
You can find the [[/mailing-lists|Mailing List]] external IDs on the [[/mailing-lists|Mailing List]] page in Sentori.

==== Endpoint ====

|URI| <nowiki>https://api.sentoriapp.com/v2.0/contact/unsubscribe/joe%40example.sentoriapp.com/MailingListExternalID/</nowiki>|
|Method| POST |

===== Unsubscribe Contact =====

This endpoint is used to unsubscribe a [[/contacts|Contact]] from all [[/mailing-lists|Mailing Lists]] and add them to the [[/suppressed-contacts#suppression-list|Suppression List]].

If no Contact exists for the Email Address, it'll simply be added to the Account's Suppression List.
==== Endpoint ====

|URI| <nowiki>https://api.sentoriapp.com/v2.0/contact/unsubscribe/joe%40example.sentoriapp.com/</nowiki>|
|Method| POST |

===== Import Contacts =====

This endpoint is used to add & update many [[/contacts|Contacts]] to a Sentori Account, when imported a new [[/upload-groups|Upload Group]] will appear in the Sentori Account.

==== Endpoint ====

|URI| <nowiki>https://api.sentoriapp.com/v2.0/contact/import/</nowiki>|
|Method| POST |

==== Request Body ====

|Field| Type|Required|Description |
|Contacts|array|yes| Array of the [[/contacts|Contacts]] to be included in the import. Must include the Email Address.|
|Description|string|no| Will be the description of the created [[/upload-groups|Upload Group]].|
|Name|string|no| Will be the name of the created [[/upload-groups|Upload Group]].|

|Example|<code javascript>{
"Name":"My API Import",
"Description":"This Upload Group was created by an API Import",
"Contacts":[
{ "EmailAddress":"contact1@example.sentoriapp.com","FirstName":"Joe"},
{ "EmailAddress":"contact2@example.sentoriapp.com","FirstName":"Mary"},
{ "EmailAddress":"contact3@example.sentoriapp.com","FirstName":"John"},
{ "EmailAddress":"contact4@example.sentoriapp.com","FirstName":"Jane"}
]
}</code>|

==== Response ====

|Field| Type|Description |
|TotalRows|int| Number of contacts in the request.|
|EmailableRowsCreated|int| Number of new and Emailable [[/contacts|Contacts]] created.|
|EmailableRowsUpdated|int| Number of existing and Emailable [[/contacts|Contacts]] who where updated.|
|SuppressedUpdated|int| Number of [[/contacts|Contacts]] who are [[/suppressed-contacts|Suppressed]] and were updated.|
|BadEmailUpdated|int| Number of existing Bad Email Address [[/contacts|Contacts]] who were updated.|
|ExcludedDuplicates|int| Number of [[/contacts|Contacts]] who weren't Imported as they where duplicated in the request.|
|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>
{
	"TotalRows": 4,
	"EmailableRowsCreated": 1,
	"EmailableRowsUpdated": 2,
	"SuppressedUpdated": 1,
	"BadEmailUpdated": 0,
	"ExcludedDuplicates": 0,
	"ExcludedInvalidEmail": 0,
	"ExcludedRoleBased": 0,
	"UploadGroupExternalID": "1234ABCD"
}
</code>

===== 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/{{UploadGroupExternalID}}/attach/{{DocumentExternalID}}</nowiki>|
|Method| POST |