Table of Contents

API Contact Endpoints

The Contact Endpoints are used to modify Contacts within Sentori.

Get a Contact

This endpoint is used to retrieve a 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 https://api.sentoriapp.com/v2.0/contact/get/[SystemID or EmailAddress]/
Method GET

Examples:

GET https://api.sentoriapp.com/v2.0/contact/get/joe%40example.sentoriapp.com/

GET https://api.sentoriapp.com/v2.0/contact/get/16382/

Response

HTTP StatusDescription
200The Contact was found and returned.

For other response codes, see the Error List.

Example Response:
{
  "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
}

Add a Contact

This endpoint is used to add a new Contact to the Sentori Account.

Note: The EmailAddress Contact Field should not appear in the Add request body, and will fail if it doesn't match the request URI.

Endpoint

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

Request Body

Request body is only needed if including Contact Fields. The example below would add a new Contact with the FirstName and LastName Contact Fields being set.

Example
{
    "FirstName":"Joe",
    "LastName":"Bloggs"
}

Response

The complete Contact as it then exists in Sentori is returned.

See the Get a Contact endpoint's Example Response for details.

Update a Contact

This endpoint is used to update an existing Contact's 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 https://api.sentoriapp.com/v2.0/contact/update/joe%40example.sentoriapp.com/
Method POST

Request Body

Request body should contain the Contact Fields to update. The below example updates the email address and first/last names.

Example
{
    "EmailAddress":"joe@example.sentoriapp.com",
    "FirstName":"Joe",
    "LastName":"Bloggs"
}

Response

The complete Contact as it then exists in Sentori is returned.

See the 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:

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:

Endpoint

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

Request Body

The Request body can contain 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
{
    "FirstName":"Joe",
    "LastName":"Bloggs"
}

Response

HTTP StatusDescription
200A successful Update was performed.
201A successful Add was performed.

For other responses, see the Error List.

For a successful result, the complete Contact as it then exists in Sentori is returned.

See the 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 Contact from the Sentori Account.

Endpoint

URI https://api.sentoriapp.com/v2.0/contact/delete/joe%40example.sentoriapp.com/
Method POST

Request Body

Leave blank.

Get Contact Structure

This endpoint is used to retrieve an example structure of a 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 https://api.sentoriapp.com/v2.0/contact/getstructure/[single or list]/
Method GET

Examples:

GET https://api.sentoriapp.com/v2.0/contact/getstructure/single/

GET https://api.sentoriapp.com/v2.0/contact/getstructure/list/

Response

HTTP StatusDescription
200The Contact structure was successfully returned.

For other response codes, see the Error List.

Example “single” Response:
{
  "IsBadEmailAddress" : false,
  "CRMID" : "string",
  "Title" : "string",
  "FirstName" : "string",
  "LastName" : "string",
  "KnownAs" : "string",
  "EmailAddress" : "string",
  "CompanyName" : "string",
  "PhoneNumber" : "string",
  "MobilePhoneNumber" : "string",
  "IsBadMobilePhoneNumber" : false
}
Example “list” Response:
[
  {
    "IsBadEmailAddress" : false,
    "CRMID" : "string",
    "Title" : "string",
    "FirstName" : "string",
    "LastName" : "string",
    "KnownAs" : "string",
    "EmailAddress" : "string",
    "CompanyName" : "string",
    "PhoneNumber" : "string",
    "MobilePhoneNumber" : "string",
    "IsBadMobilePhoneNumber" : false
  }
]

Subscribe Contact to Mailing List

This endpoint is used to subscribe a Contact to a Mailing List.
You can find the Mailing List external IDs on the Mailing List page in Sentori.

Endpoint

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

Unsubscribe Contact from Mailing List

This endpoint is used to unsubscribe a Contact from a Mailing List.
You can find the Mailing List external IDs on the Mailing List page in Sentori.

Endpoint

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

Unsubscribe Contact

This endpoint is used to unsubscribe a Contact from all Mailing Lists and add them to the Suppression List.

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

Endpoint

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

Import Contacts

This endpoint is used to add & update many Contacts to a Sentori Account, when imported a new Upload Group will appear in the Sentori Account.

Endpoint

URI https://api.sentoriapp.com/v2.0/contact/import/
Method POST

Request Body

Field TypeRequiredDescription
Contactsarrayyes Array of the Contacts to be included in the import. Must include the Email Address.
Descriptionstringno Will be the description of the created Upload Group.
Namestringno Will be the name of the created Upload Group.
Example
{
"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"}
]
}

Response

Field TypeDescription
TotalRowsint Number of contacts in the request.
EmailableRowsCreatedint Number of new and Emailable Contacts created.
EmailableRowsUpdatedint Number of existing and Emailable Contacts who where updated.
SuppressedUpdatedint Number of Contacts who are Suppressed and were updated.
BadEmailUpdatedint Number of existing Bad Email Address Contacts who were updated.
ExcludedDuplicatesint Number of Contacts who weren't Imported as they where duplicated in the request.
ExcludedInvalidEmailint Number of Contacts who couldn't be Imported as the email addresses weren't valid.
ExcludedRoleBasedint Number of Contacts who weren't Imported as they have role-based email addresses.
UploadGroupExternalIDstring ExternalID of the Upload Group created by this Import or null if no Contacts were actually imported.

Example

{
	"TotalRows": 4,
	"EmailableRowsCreated": 1,
	"EmailableRowsUpdated": 2,
	"SuppressedUpdated": 1,
	"BadEmailUpdated": 0,
	"ExcludedDuplicates": 0,
	"ExcludedInvalidEmail": 0,
	"ExcludedRoleBased": 0,
	"UploadGroupExternalID": "1234ABCD"
}

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 https://api.sentoriapp.com/v2.0/contact/import/{{UploadGroupExternalID}}/attach/{{DocumentExternalID}}
Method POST