====== API - Contact Signup ======

This API method allows you to integrate with a Sentori signup form that you have created; for example, to connect your website's form to put contacts into Sentori. 

The Contact Signup method is different to the [[api-import-contacts|API Contact Import]] method; it is intended to action a single contact signup rather than be a bulk operation. 

In addition to adding a contact to Sentori, its integration with a [[forms|form]] allows it to action all of the features of the form you have built in Sentori: for example, double opt-in, assignment of [[mailing-lists|mailing lists]] and [[tags|tags]], the sending of alert emails, and the triggering of [[automation|automations]].

===== Overview =====

| URL | <nowiki>https://api.sentoriapp.com/webhooks/contact/signup.ashx</nowiki> |
| HTTP METHOD | POST |
| Content-Type | application/json |

===== JSON Request Parameters =====

^ Name ^ Required ^ Type ^ Description ^
| ApiKey | True | String | This is the key to access the API for your Sentori account. |
| EmailAddress | True | String | The Email Address of the Contact being signed up. |
| SignUpFormExternalID | True | String | The external ID of the Signup Form to use for this signup. |
| MailingLists | False | Array[] | Array of Mailing List External ID’s for the Contact to be subscribed to. |
| ContactFields | Dependent on Form Fields | Object {} | Object containing Contact Field key value pairs. Required if fields on form are required. |
| Tags | False | Array[] | Array of Tags that the Contact should be tagged with. |
| RequireConfirmation | False | String | Whether to await confirmation before applying the submitted values.  "false" will immediately set the values.  "true", or not specifying a value, will send a confirmation email. |

===== API Responses =====

^ HTTP Code ^ Status ^ Description ^
| 200 | OK | The Signup was successful.  If RequireConfirmation was specified and set as “false” the submitted values have been set, otherwise the Contact will have been sent the opt-in confirmation email. |
| 206 | Contact created but failed to send confirmation email | The signup has been successful however the contact hasn’t been sent the opt-in confirmation email. |
| 400 | Invalid Parameters [*] | Some of the JSON parameters are missing or invalid. * is the name. |
| 403 | No API Key Specified | No API key was specified in the request JSON. |
| 404 | Account not found | The Sentori Account was not found, make sure the API key is correct. |
| 404 | Signup Form not found | There is no Signup form that matches SignupFormExternalID. |
| 404 | Mailing list not found [*] | The mailing list could not be found. * is the MailingListExternalID. |
| 404 | No Contact Fields submitted, but form has required fields | The Signup Form requires a Contact Field but no ContactFields in JSON. |
| 404 | Required Contact Field is missing or blank [*] | The Signup Form requires a Contact Field that either wasn’t specified or was blank. * is the Contact Field SystemName. |
| 404 | Tag not found [*] | The specified Tag could not be found. * is the Tag name. |
| 500 | Internal Error | The server has encountered a problem. |

===== Examples =====

==== Minimal example ====

=== Request ===

<code>
POST https://api.sentoriapp.com/webhooks/contact/signup.ashx HTTP/1.1
Host: api.sentoriapp.com
Content-Type: application/json
Content-Length: 144

{
	"ApiKey":"00000000-0000-0000-0000-000000000000",
	"EmailAddress":"example@sentoriapp.com",
	"SignUpFormExternalID":"12ABCDE3"
}
</code>

=== Response ===

<code>
HTTP/1.1 200 Ok
Cache-Control: private
Transfer-Encoding: chunked
Server: Microsoft-IIS/8.5
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
Date: Mon, 20 Jan 2014 15:41:38 GMT
</code>

==== Full example ====

=== Request ===

<code>
POST https://api.sentoriapp.com/webhooks/contact/signup.ashx HTTP/1.1
Host: api.sentoriapp.com
Content-Type: application/json
Content-Length: 269

{
	"ApiKey":"00000000-0000-0000-0000-000000000000",
	"EmailAddress":"example@sentoriapp.com",
	"SignUpFormExternalID":"12ABCDE3", 
	"MailingLists":["QWERTY1A","ABCDEFG1"],
	"ContactFields":{"FirstName":"Example", "LastName":"Contact"},
	"Tags":["Example","SentoriApp"],
	"RequireConfirmation":"true"
}
</code>

=== Response ===

<code>
HTTP/1.1 200 Ok
Cache-Control: private
Transfer-Encoding: chunked
Server: Microsoft-IIS/8.5
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
Date: Mon, 20 Jan 2014 15:42:25 GMT
</code>