Improve documentation for Attendee and Signature create (#138)

* fix typo on consent_content_version_external_id

* revamp attendee-create documentation with the full set of fields, working JSON example, and separate Required column

* use new style for signature create table too

source/includes/authenticated_api/_attendees.md.erb

@@ -75,26 +75,38 @@ Find an attendee by email address. Once you have obtained the attendee's id you
 <div></div>
 
 ### Create
+> POST /api/v1/events/deliver-the-petition-to-the-wizard/attendees
 
-Creates a new attendee for the specified event. This API endpoint can be used to record externally collected RSVPs for
-a particular event within your instance of the ControlShift platform.
-
-All of the same post-RSVP actions that the platform usually supports including webhooks, CRM syncs, and other integrations
-will still be triggered, in the same way they are for normal RSVPs.
-
-For organisations that require email confirmation, a confirmation email will be sent to the action taker.
-
-<%= partial 'includes/create_action_fields.md.erb', locals: { action_name: 'attendee' } %>
-
-`POST /api/v1/events/deliver-the-petition-to-the-wizard/attendees/`
-
-<div></div>
-
-#### POST body
-
-`attendee[first_name]=Ada&attendee[last_name]=Lovelace&attendee[email][email protected]&attendee[postcode]=12345`
+```json
+{
+  "attendee": {
+    "attending_status": "attending",
+    "notification_level": "all_messages",
+    "first_name": "Ada",
+    "last_name": "Lovelace",
+    "email": "[email protected]",
+    "postcode": "12345",
+    "phone_number": "555-555-555",
+    "locale": "en-GB",
+    "country": "GB",
+    "email_opt_in_type_external_id": "canvass-signature-2022",
+    "join_organisation": true,
+    "partnership_opt_ins": {
+      "123": true,
+      "456": false
+    },
+    "eu_data_processing_consent": true,
+    "consent_content_version_external_id": "revised-terms-2022-february",
+    "utm_source": "facebook",
+    "utm_medium": "button",
+    "utm_campaign": "infrastructure-petition-delivery-2022",
+    "utm_term": null,
+    "utm_content": null
+  }
+}
+```
 
-> POST response body for create
+> Response body
 
 ```json
 {
@@ -152,6 +164,24 @@ For organisations that require email confirmation, a confirmation email will be
 }
 ```
 
+Creates a new attendee for the specified event. This API endpoint can be used to record externally collected RSVPs for
+a particular event within your instance of the ControlShift platform.
+
+`POST /api/v1/events/deliver-the-petition-to-the-wizard/attendees/`
+
+All of the same post-RSVP actions that the platform usually supports including webhooks, CRM syncs, and other integrations
+will still be triggered, in the same way they are for normal RSVPs.
+
+For organisations that require email confirmation, a confirmation email will be sent to the action taker.
+
+The request body should be a JSON block containing one `"attendee"` object, which can have the following properties:
+
+| Field                     |   Description                                                            | Required? |
+| ------------------------- | ------------------------------------------------------------------------ | --------- |
+| attending_status | Whether the member is attending the event. One of `attending`, `not_attending`, `attended`, `confirmed`, or `no_show`. | yes
+| notification_level | Email notification preference for the event forum. One of `all_messages` (an email for every post), `none` (no emails), or `pending` (preference will be determined during email confirmation). | yes
+<%= partial 'includes/authenticated_api/common_action_fields.md.erb'  %>
+
 <div></div>
 
 ### Update email opt in type

source/includes/authenticated_api/_common_action_fields.md.erb

@@ -0,0 +1,17 @@
+ first_name   | The first name of the member who took action                     | yes
+| last_name    | The last name of the member who took action                     | yes
+| email        | The email address of the member who took action                  | yes
+| postcode     | The postal or zip code of the member. Depending on your configuration, this may be validated for your country. | Depends on platform settings
+| phone_number | The phone number of the member who took action | Depends on platform settings
+| locale       | The language and localization setting of the member who has taken action. This is specified as an [ISO_639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) two-character language code combined with an optional [ISO 3166](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) two character country code. For eg `en-US` or `en`. | no; default is `en`
+| country      | The country specified as an [ISO 3166](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) two character country code. | Depends on platform settings
+| email_opt_in_type_external_id | The External ID for the ControlShift email opt in type to use for this action. The email opt in type must have "external" context. You can list available email opt in types with [this endpoint](https://developers.controlshiftlabs.com/#authenticated-rest-api-email-opt-in-types). | yes
+| join_organisation | Whether or not the member has opted in to email communications from this campaign and organisation. | yes, unless "defer opt-in to confirmation email" is enabled
+| partnership_opt_ins | For partnership campaigns, whether or not this member has opted into communication from each partnership. This should be a JSON object like `{"123": true, "456": false}`, mapping partnership IDs to the opt-in status. | no
+| eu_data_processing_consent      | Whether or not member has given consent for GDPR data processing. This field must be true if the organisation requires data processing consent for user actions with `use_eu_data_processing_consent = true`. | yes, if data processing consent is enabled
+| consent_content_version_external_id      | The External ID for the data processing consent content version the member has consented to on this action. The consent content version tracks what the privacy policy, terms of service, and checkbox label were at the time of this action. You can list available consent content versions via [this endpoint](https://developers.controlshiftlabs.com/#authenticated-rest-api-consent-content-versions). | yes, if data processing consent is enabled
+| utm_source   | UTM tracking field | no
+| utm_campaign | UTM tracking field | no
+| utm_content  | UTM tracking field | no
+| utm_medium | UTM tracking field | no
+| utm_term     | UTM tracking field | no

source/includes/authenticated_api/_signatures.md.erb

@@ -133,26 +133,7 @@ The JSON response has a single "signature" object, which may include the followi
 
 ### Create
 
-Creates a new signature for the specified petition. This API endpoint can be used to record externally collected signatures for
-a particular petition within your instance of the ControlShift platform.
-
-All of the same post-signature actions that the platform usually supports including webhooks, CRM syncs, and other integrations
-will still be triggered, in the same way they are for normal signatures.
-
-For organisations that require email confirmation, a confirmation email will be sent to the action taker.
-
-<%= partial 'includes/create_action_fields.md.erb', locals: { action_name: 'signature' } %>
-
-`POST /api/v1/petitions/no-taxes-on-tea/signatures/`
-
-<div></div>
-
-
-#### POST body
-
-`signature[first_name]=Ada&signature[last_name]=Lovelave&signature[email][email protected]&signature[postcode]=12345`
-
-> POST response body for create
+> Response body
 
 ```json
 {
@@ -208,6 +189,22 @@ For organisations that require email confirmation, a confirmation email will be
 }
 ```
 
+Creates a new signature for the specified petition. This API endpoint can be used to record externally collected signatures for
+a particular petition within your instance of the ControlShift platform.
+
+`POST /api/v1/petitions/no-taxes-on-tea/signatures/`
+
+All of the same post-signature actions that the platform usually supports including webhooks, CRM syncs, and other integrations
+will still be triggered, in the same way they are for normal signatures.
+
+For organisations that require email confirmation, a confirmation email will be sent to the action taker.
+
+The request body should be a JSON block containing one `"signature"` object, which can have the following properties:
+
+| Field                     |   Description                                                            | Required? |
+| ------------------------- | ------------------------------------------------------------------------ | --------- |
+<%= partial 'includes/authenticated_api/common_action_fields.md.erb'  %>
+
 <div></div>
 
 ### Update email opt in type