From 5df3c6c46e3d87da7d78e119444eb1fb1ea44f21 Mon Sep 17 00:00:00 2001
From: Pavel Dohnal <pavel@mailpoet.com>
Date: Thu, 30 May 2019 10:14:19 +0200
Subject: [PATCH] Add documentationfor adding custom fields api

[MAILPOET-2041]
---
 doc/Readme.md                          |  1 +
 doc/api_methods/AddSubscriberField.md  | 65 ++++++++++++++++++++++++++
 doc/api_methods/GetSubscriberFields.md |  1 +
 3 files changed, 67 insertions(+)
 create mode 100644 doc/api_methods/AddSubscriberField.md

diff --git a/doc/Readme.md b/doc/Readme.md
index f6c18ad5ee..cfffc551ed 100644
--- a/doc/Readme.md
+++ b/doc/Readme.md
@@ -22,6 +22,7 @@ Class `\MailPoet\API\API` becomes available once MailPoet plugin is loaded by Wo
 ### Available API Methods
 * [Add List (addList)](api_methods/AddList.md)
 * [Add Subscriber (addSubscriber)](api_methods/AddSubscriber.md)
+* [Add Subscriber Field(addSubscriberField)](api_methods/AddSubscriberField.md)
 * [Get Lists (getLists)](api_methods/GetLists.md)
 * [Get Subscriber (getSubscriber)](api_methods/GetSubscriber.md)
 * [Get Subscriber Fields (getSubscriberFields)](api_methods/GetSubscriberFields.md)
diff --git a/doc/api_methods/AddSubscriberField.md b/doc/api_methods/AddSubscriberField.md
new file mode 100644
index 0000000000..10d5ff1ad0
--- /dev/null
+++ b/doc/api_methods/AddSubscriberField.md
@@ -0,0 +1,65 @@
+[back to list](../Readme.md)
+
+# Add Subscriber Field
+
+## `array addSubscriberField(array $data)`
+
+Using this method you can create custom properties that can be used for storing additional data for each subscriber.
+See [Subscriber Fields for more details](./GetSubscriberFields.md)
+
+## Arguments
+
+### `$data` (required)
+
+| Property | Type | Limits | Description |
+| --- | --- | --- | --- |
+| name (required) | string | 90 chars | Human readable name. Intended to be used, as an example, as a label for form input. |
+| type (required) | string | - | Type of the field. Possible values are: `text`, `date`, `textarea`, `radio`, `checkbox`, `select` |
+| params (optional) | array | - | Contains various information, see examples below. |
+
+### `$params`
+
+Params array differs for each type. 
+The common properties for all types: 
+
+| Property | Type | Description |
+| --- | --- | --- |
+| required | string | Indicates if the value must be provided for each subscriber. Possible values are: "1" or "" |
+| label | string | Label used for displaying the field to the end user. |
+
+#### `$params` for text, textarea types
+
+| Property | Type | Description |
+| --- | --- | --- |
+| validate | string | Can be used for validating input values. Possible values are: `number`, `alphanum`, `phone` |
+
+#### `$params` for checkbox types
+
+| Property | Type | Description |
+| --- | --- | --- |
+| values | array | Same array as for radio type. Must contain exactly 1 element |
+
+#### `$params` for radio, select types
+
+| Property | Type | Description |
+| --- | --- | --- |
+| values | array | Contains a list of options. Each element must contain a string `value` and can contain `is_checked` |
+
+#### `$params` for date type
+
+| Property | Type | Description |
+| --- | --- | --- |
+| date_type | string | Possible values are: Values: `year_month_day`, `year_month`, `month`, `day` |
+| date_format | string | Values: for year_month_day: 'MM/DD/YYYY', 'DD/MM/YYYY', 'YYYY/MM/DD', for year_month: 'YYYY/MM', 'MM/YY', for year: 'YYYY', for month: 'MM' |
+
+## Response
+
+| Property | Type | Limits | Description |
+| --- | --- | --- | --- |
+| id | string | 11 chars |Field Id |
+| name | string | 90 chars | Human readable name. Intended to be used, as an example, as a label for form input. |
+| type | string | - | Type of the field. Possible values are: `text`, `date`, `textarea`, `radio`, `checkbox`, `select` |
+| params | array | - | Contains various information, see examples below. |
+| created_at | string\|null | - | UTC time of creation in 'Y-m-d H:i:s' format |
+| updated_at | string | - | UTC time of last update in 'Y-m-d H:i:s' format |
+
diff --git a/doc/api_methods/GetSubscriberFields.md b/doc/api_methods/GetSubscriberFields.md
index e9bd2154df..ef6595b717 100644
--- a/doc/api_methods/GetSubscriberFields.md
+++ b/doc/api_methods/GetSubscriberFields.md
@@ -7,6 +7,7 @@
 Each subscriber has a set of default properties (`email`, `first_name`, `last_name`).
 MailPoet enables the extension of these properties by adding custom properties.
 This method returns list of all properties available for a subscriber (default + custom).
+See also [addSubscriberField function](./AddSubscriberField.md)
 
 ## Subscriber Field