diff --git a/docs/rest_api/companies.rst b/docs/rest_api/companies.rst
new file mode 100644
index 00000000..a9a6b995
--- /dev/null
+++ b/docs/rest_api/companies.rst
@@ -0,0 +1,678 @@
+Companies
+#########
+
+Use this endpoint to manipulate and obtain details on Mautic's Companies.
+
+**Using Mautic's API Library**
+
+You can interact with this API through the :xref:`Mautic API Library` as follows, or use the various http endpoints as described in this document.
+
+.. code-block:: php
+
+ newAuth($settings);
+ $apiUrl = "https://example.com";
+ $api = new MauticApi();
+ $companyApi = $api->newApi("companies", $auth, $apiUrl);
+
+.. vale off
+
+Get Company
+***********
+
+.. vale on
+
+.. code-block:: php
+
+ get($id);
+
+Get an individual Company by ID.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``GET /companies/ID``
+
+**Response**
+
+``Expected Response Code: 200``
+
+.. code-block:: json
+
+ {
+ "company": {
+ "isPublished": true,
+ "dateAdded": "2017-02-03T16:51:06+00:00",
+ "dateModified": "2017-02-03T19:11:54+00:00",
+ "createdBy": 1,
+ "createdByUser": "John Doe",
+ "modifiedBy": 1,
+ "modifiedByUser": "John Doe",
+ "id": 1,
+ "fields": {
+ "all": {
+ "companyname": "Acme Corporation",
+ "companyemail": "info@acme.com",
+ "companyaddress1": "123 Main St",
+ "companyaddress2": "Suite 100",
+ "companycity": "Anytown",
+ "companystate": "NY",
+ "companyzipcode": "12345",
+ "companycountry": "United States",
+ "companyphone": "+1-555-123-4567",
+ "companywebsite": "https://acme.com",
+ "companyindustry": "Technology",
+ "companydescription": "Leading software company"
+ }
+ },
+ "score": 150,
+ "owner": {
+ "id": 1,
+ "username": "admin",
+ "firstName": "John",
+ "lastName": "Doe"
+ }
+ }
+ }
+
+**Company Properties**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Type
+ - Description
+ * - id
+ - int
+ - ID of the company
+ * - isPublished
+ - bool
+ - Published state
+ * - dateAdded
+ - datetime
+ - Date/time company was created
+ * - dateModified
+ - datetime
+ - Date/time company was last modified
+ * - createdBy
+ - int
+ - ID of the user that created the company
+ * - createdByUser
+ - string
+ - Name of the user that created the company
+ * - modifiedBy
+ - int
+ - ID of the user that last modified the company
+ * - modifiedByUser
+ - string
+ - Name of the user that last modified the company
+ * - fields
+ - array
+ - Custom fields and values for the company
+ * - score
+ - int
+ - Company score
+ * - owner
+ - object
+ - User object for the company owner
+
+**Company Field Properties**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Type
+ - Description
+ * - companyname
+ - string
+ - Company name
+ * - companyemail
+ - string
+ - Company email address
+ * - companyaddress1
+ - string
+ - Company address line 1
+ * - companyaddress2
+ - string
+ - Company address line 2
+ * - companycity
+ - string
+ - Company city
+ * - companystate
+ - string
+ - Company state/province
+ * - companyzipcode
+ - string
+ - Company zip/postal code
+ * - companycountry
+ - string
+ - Company country
+ * - companyphone
+ - string
+ - Company phone number
+ * - companywebsite
+ - string
+ - Company website URL
+ * - companyindustry
+ - string
+ - Company industry
+ * - companydescription
+ - string
+ - Company description
+
+.. vale off
+
+List Companies
+**************
+
+.. vale on
+
+.. code-block:: php
+
+ getList($searchFilter, $start, $limit, $orderBy, $orderByDir, $publishedOnly, $minimal);
+
+.. note::
+
+ The ``$companies`` array will be an array of individual Company arrays like the above example.
+
+**HTTP Request**
+
+``GET /companies``
+
+**Query Parameters**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Description
+ * - search
+ - String or search command to filter entities by.
+ * - start
+ - Starting row for the entities returned. Defaults to 0.
+ * - limit
+ - Limit number of entities to return. Defaults to the system configuration for pagination (30).
+ * - orderBy
+ - Column to sort by. Can use any column listed in the response.
+ * - orderByDir
+ - Sort direction: asc or desc.
+ * - publishedOnly
+ - Only return currently published entities.
+ * - minimal
+ - Return only array of entities without additional lists in it.
+
+**Response**
+
+``Expected Response Code: 200``
+
+.. code-block:: json
+
+ {
+ "total": 25,
+ "companies": [
+ {
+ "isPublished": true,
+ "dateAdded": "2017-02-03T16:51:06+00:00",
+ "dateModified": "2017-02-03T19:11:54+00:00",
+ "createdBy": 1,
+ "createdByUser": "John Doe",
+ "modifiedBy": 1,
+ "modifiedByUser": "John Doe",
+ "id": 1,
+ "fields": {
+ "all": {
+ "companyname": "Acme Corporation",
+ "companyemail": "info@acme.com"
+ }
+ },
+ "score": 150
+ }
+ ]
+ }
+
+.. vale off
+
+Create Company
+**************
+
+.. vale on
+
+.. code-block:: php
+
+ 'Acme Corporation',
+ 'companyemail' => 'info@acme.com',
+ 'companywebsite' => 'https://acme.com',
+ );
+
+ $company = $companyApi->create($data);
+
+Create a new Company.
+
+**HTTP Request**
+
+``POST /companies/new``
+
+**Post Parameters**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Type
+ - Description
+ * - companyname
+ - string
+ - Company name (required)
+ * - companyemail
+ - string
+ - Company email address
+ * - companyaddress1
+ - string
+ - Company address line 1
+ * - companyaddress2
+ - string
+ - Company address line 2
+ * - companycity
+ - string
+ - Company city
+ * - companystate
+ - string
+ - Company state/province
+ * - companyzipcode
+ - string
+ - Company zip/postal code
+ * - companycountry
+ - string
+ - Company country
+ * - companyphone
+ - string
+ - Company phone number
+ * - companywebsite
+ - string
+ - Company website URL
+ * - companyindustry
+ - string
+ - Company industry
+ * - companydescription
+ - string
+ - Company description
+ * - isPublished
+ - boolean
+ - Published state (default: 1)
+ * - owner
+ - int
+ - ID of a Mautic user to assign this company to
+
+**Response**
+
+``Expected Response Code: 201``
+
+**Properties**
+
+Same as `Get Company`_.
+
+.. vale off
+
+Edit Company
+************
+
+.. vale on
+
+.. code-block:: php
+
+ 'Updated Company Name',
+ 'companyemail' => 'updated@acme.com',
+ );
+
+ // Create new a company of ID 1 is not found?
+ $createIfNotFound = true;
+
+ $company = $companyApi->edit($id, $data, $createIfNotFound);
+
+Edit a new Company. Note that this supports PUT or PATCH depending on the desired behavior.
+
+**PUT** creates a Company if the given ID does not exist and clears all the Company information, adds the information from the request.
+**PATCH** fails if the Company with the given ID does not exist and updates the Company field values with the values from the request.
+
+**HTTP Request**
+
+To edit a Company and return a 404 if the Company is not found:
+
+``PATCH /companies/ID/edit``
+
+To edit a Company and create a new one if the Company is not found:
+
+``PUT /companies/ID/edit``
+
+**Post Parameters**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Type
+ - Description
+ * - companyname
+ - string
+ - Company name
+ * - companyemail
+ - string
+ - Company email address
+ * - companyaddress1
+ - string
+ - Company address line 1
+ * - companyaddress2
+ - string
+ - Company address line 2
+ * - companycity
+ - string
+ - Company city
+ * - companystate
+ - string
+ - Company state/province
+ * - companyzipcode
+ - string
+ - Company zip/postal code
+ * - companycountry
+ - string
+ - Company country
+ * - companyphone
+ - string
+ - Company phone number
+ * - companywebsite
+ - string
+ - Company website URL
+ * - companyindustry
+ - string
+ - Company industry
+ * - companydescription
+ - string
+ - Company description
+ * - isPublished
+ - boolean
+ - Published state
+ * - owner
+ - int
+ - ID of a Mautic user to assign this company to
+
+**Response**
+
+If ``PUT``: ``Expected Response Code: 200`` or ``201`` if created
+
+If ``PATCH``: ``Expected Response Code: 200``
+
+**Properties**
+
+Same as `Get Company`_.
+
+.. vale off
+
+Delete Company
+**************
+
+.. vale on
+
+.. code-block:: php
+
+ delete($id);
+
+Delete a Company.
+
+**HTTP Request**
+
+``DELETE /companies/ID/delete``
+
+**Response**
+
+``Expected Response Code: 200``
+
+**Properties**
+
+Same as `Get Company`_.
+
+.. vale off
+
+Batch Create Companies
+**********************
+
+.. vale on
+
+.. code-block:: php
+
+ 'Acme Corporation',
+ 'companyemail' => 'info@acme.com',
+ ),
+ array(
+ 'companyname' => 'Beta LLC',
+ 'companyemail' => 'info@beta.com',
+ ),
+ );
+
+ $companies = $companyApi->createBatch($data);
+
+Create multiple Companies in a single request.
+
+.. note::
+
+ If an existing company is found with the same unique identifier fields (as configured in Mautic), the existing company will be updated instead of creating a new one.
+
+**HTTP Request**
+
+``POST /companies/batch/new``
+
+**Post Parameters**
+
+An array of Company arrays. Each Company array should contain the same fields as described in `Create Company`_.
+
+**Response**
+
+``Expected Response Code: 201``
+
+.. code-block:: json
+
+ {
+ "statusCodes": [201, 201],
+ "companies": [
+ {
+ "isPublished": true,
+ "dateAdded": "2017-02-03T16:51:06+00:00",
+ "dateModified": "2017-02-03T19:11:54+00:00",
+ "createdBy": 1,
+ "createdByUser": "John Doe",
+ "modifiedBy": 1,
+ "modifiedByUser": "John Doe",
+ "id": 1,
+ "fields": {
+ "all": {
+ "companyname": "Acme Corporation",
+ "companyemail": "info@acme.com"
+ }
+ },
+ "score": 0
+ },
+ {
+ "isPublished": true,
+ "dateAdded": "2017-02-03T16:51:06+00:00",
+ "dateModified": "2017-02-03T19:11:54+00:00",
+ "createdBy": 1,
+ "createdByUser": "John Doe",
+ "modifiedBy": 1,
+ "modifiedByUser": "John Doe",
+ "id": 2,
+ "fields": {
+ "all": {
+ "companyname": "Beta LLC",
+ "companyemail": "info@beta.com"
+ }
+ },
+ "score": 0
+ }
+ ]
+ }
+
+.. vale off
+
+Batch Edit Companies
+********************
+
+.. vale on
+
+.. code-block:: php
+
+ 1,
+ 'companyname' => 'Updated Acme Corporation',
+ ),
+ array(
+ 'id' => 2,
+ 'companyname' => 'Updated Beta LLC',
+ ),
+ );
+
+ $companies = $companyApi->editBatch($data);
+
+Edit multiple Companies in a single request. Each Company in the array must include an ``id`` field.
+
+**HTTP Request**
+
+``PATCH /companies/batch/edit``
+
+**Post Parameters**
+
+An array of Company arrays. Each Company array should contain an ``id`` field and the fields to update as described in `Edit Company`_.
+
+**Response**
+
+``Expected Response Code: 200``
+
+**Properties**
+
+Similar to `Batch Create Companies`_ but with ``statusCodes`` indicating whether each company was successfully updated (200) or if there was an error.
+
+.. vale off
+
+Batch Delete Companies
+**********************
+
+.. vale on
+
+.. code-block:: php
+
+ deleteBatch($ids);
+
+Delete multiple Companies in a single request.
+
+**HTTP Request**
+
+``DELETE /companies/batch/delete?ids=1,2,3``
+
+**Query Parameters**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Description
+ * - ids
+ - Comma-separated list of Company IDs to delete
+
+**Response**
+
+``Expected Response Code: 200``
+
+**Properties**
+
+Similar to `Batch Create Companies`_ but with the companies that were deleted.
+
+.. vale off
+
+Add Contact to Company
+**********************
+
+.. vale on
+
+.. code-block:: php
+
+ addContact($companyId, $contactId);
+
+Add a Contact to a Company.
+
+**HTTP Request**
+
+``POST /companies/COMPANY_ID/contact/CONTACT_ID/add``
+
+**Response**
+
+``Expected Response Code: 200``
+
+.. code-block:: json
+
+ {
+ "success": 1
+ }
+
+.. vale off
+
+Remove Contact from Company
+***************************
+
+.. vale on
+
+.. code-block:: php
+
+ removeContact($companyId, $contactId);
+
+Remove a Contact from a Company.
+
+**HTTP Request**
+
+``POST /companies/COMPANY_ID/contact/CONTACT_ID/remove``
+
+**Response**
+
+``Expected Response Code: 200``
+
+.. code-block:: json
+
+ {
+ "success": 1
+ }
\ No newline at end of file
diff --git a/docs/rest_api/emails.rst b/docs/rest_api/emails.rst
new file mode 100644
index 00000000..7610ab53
--- /dev/null
+++ b/docs/rest_api/emails.rst
@@ -0,0 +1,916 @@
+Emails
+######
+
+Use this endpoint to manipulate and obtain details on Mautic's Emails.
+
+**Using Mautic's API Library**
+
+You can interact with this API through the :xref:`Mautic API Library` as follows, or use the various http endpoints as described in this document.
+
+.. code-block:: php
+
+ newAuth($settings);
+ $apiUrl = "https://example.com";
+ $api = new MauticApi();
+ $emailApi = $api->newApi("emails", $auth, $apiUrl);
+
+.. vale off
+
+Get Email
+*********
+
+.. vale on
+
+.. code-block:: php
+
+ get($id);
+
+Get an individual Email by ID.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``GET /emails/ID``
+
+**Response**
+
+``Expected Response Code: 200``
+
+.. code-block:: json
+
+ {
+ "email": {
+ "isPublished": true,
+ "dateAdded": "2017-02-03T16:51:06+00:00",
+ "dateModified": "2017-02-03T19:11:54+00:00",
+ "createdBy": 1,
+ "createdByUser": "John Doe",
+ "modifiedBy": 1,
+ "modifiedByUser": "John Doe",
+ "id": 1,
+ "name": "API Test Email",
+ "subject": "Email created via API",
+ "fromAddress": "test@example.com",
+ "fromName": "Test From Name",
+ "replyToAddress": "reply@example.com",
+ "bccAddress": "bcc@example.com",
+ "useOwnerAsMailer": false,
+ "template": "blank",
+ "content": [],
+ "utmTags": [],
+ "plainText": "Plain text content here",
+ "customHtml": "Custom HTML content
",
+ "emailType": "list",
+ "translationChildren": [],
+ "translationParent": null,
+ "variantChildren": [],
+ "variantParent": null,
+ "variantSettings": [],
+ "variantStartDate": null,
+ "publishUp": null,
+ "publishDown": null,
+ "readCount": 0,
+ "sentCount": 0,
+ "revision": 1,
+ "category": null,
+ "lists": [
+ {
+ "createdByUser": "John Doe",
+ "modifiedByUser": "John Doe",
+ "id": 2,
+ "name": "Test Segment",
+ "alias": "test-segment",
+ "description": "Description for test segment"
+ }
+ ],
+ "language": "en",
+ "publicPreview": false,
+ "assetAttachments": [],
+ "unsubscribeForm": null,
+ "preferenceCenter": null,
+ "dynamicContent": [],
+ "variantSentCount": 0,
+ "variantReadCount": 0,
+ "headers": []
+ }
+ }
+
+**Email Properties**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Type
+ - Description
+ * - ``id``
+ - int
+ - ID of the Email
+ * - ``name``
+ - string
+ - Name of the Email
+ * - ``subject``
+ - string
+ - Subject of the Email
+ * - ``fromAddress``
+ - string
+ - From email address
+ * - ``fromName``
+ - string
+ - From name
+ * - ``replyToAddress``
+ - string
+ - Reply-to email address
+ * - ``bccAddress``
+ - string
+ - BCC email address
+ * - ``useOwnerAsMailer``
+ - boolean
+ - Whether to use the Contact owner as the mailer
+ * - ``template``
+ - string
+ - Template used for the Email
+ * - ``content``
+ - array
+ - Array of content for the template
+ * - ``utmTags``
+ - array
+ - Array of UTM tags for tracking
+ * - ``plainText``
+ - string
+ - Plain text version of the Email
+ * - ``customHtml``
+ - string
+ - Custom HTML content of the Email
+ * - ``emailType``
+ - string
+ - Type of the Email (``list``, ``template``)
+ * - ``publishUp``
+ - datetime/null
+ - Date/time when the Email should be published
+ * - ``publishDown``
+ - datetime/null
+ - Date/time when the Email should be unpublished
+ * - ``readCount``
+ - int
+ - Number of times the Email was read
+ * - ``sentCount``
+ - int
+ - Number of times the Email was sent
+ * - ``revision``
+ - int
+ - Revision number of the Email
+ * - ``category``
+ - object/null
+ - Category the Email belongs to
+ * - ``lists``
+ - array
+ - Array of Segments/Lists the Email is assigned to
+ * - ``language``
+ - string
+ - Language of the Email
+ * - ``publicPreview``
+ - boolean
+ - Whether the Email has public preview enabled
+ * - ``assetAttachments``
+ - array
+ - Array of assets attached to the Email
+ * - ``unsubscribeForm``
+ - object/null
+ - Unsubscribe form associated with the Email
+ * - ``preferenceCenter``
+ - object/null
+ - Preference center page associated with the Email
+ * - ``dynamicContent``
+ - array
+ - Array of dynamic content variants
+ * - ``variantSentCount``
+ - int
+ - Number of times Email variants were sent
+ * - ``variantReadCount``
+ - int
+ - Number of times Email variants were read
+ * - ``headers``
+ - array
+ - Array of custom headers
+ * - ``isPublished``
+ - boolean
+ - Published state
+ * - ``dateAdded``
+ - datetime
+ - Date/time Email was created
+ * - ``createdBy``
+ - int
+ - ID of the User that created the Email
+ * - ``createdByUser``
+ - string
+ - Name of the User that created the Email
+ * - ``dateModified``
+ - datetime/null
+ - Date/time Email was last modified
+ * - ``modifiedBy``
+ - int
+ - ID of the User that last modified the Email
+ * - ``modifiedByUser``
+ - string
+ - Name of the User that last modified the Email
+
+.. vale off
+
+List Emails
+***********
+
+.. vale on
+
+.. code-block:: php
+
+ getList($searchFilter, $start, $limit, $orderBy, $orderByDir, $publishedOnly, $minimal);
+
+Returns a list of contact Emails available to the User. This list is filterable and sortable.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``GET /emails``
+
+**Query Parameters**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Description
+ * - ``search``
+ - String or search command to filter entities by.
+ * - ``start``
+ - Starting row for the entities returned. Defaults to 0.
+ * - ``limit``
+ - Limit number of entities to return. Defaults to the system configuration for pagination, which is 30 by default.
+ * - ``orderBy``
+ - Column to sort by. Can use any column listed in the response. However, you need to change all properties in the response written in ``camelCase`` a bit. Before every capital, add an underscore ``_`` and then change the capital letters to non-capital letters. So ``dateAdded`` becomes ``date_added``, ``modifiedBy`` becomes ``modified_by``, etc.
+ * - ``orderByDir``
+ - Sort direction: ``asc`` or ``desc``.
+ * - ``publishedOnly``
+ - Only return currently published entities.
+ * - ``minimal``
+ - Return only array of entities without additional lists in it.
+
+**Response**
+
+``Expected Response Code: 200``
+
+.. code-block:: json
+
+ {
+ "total": 1,
+ "emails": {
+ "1": {
+ "isPublished": true,
+ "dateAdded": "2017-02-03T16:51:06+00:00",
+ "dateModified": "2017-02-03T19:11:54+00:00",
+ "createdBy": 1,
+ "createdByUser": "John Doe",
+ "modifiedBy": 1,
+ "modifiedByUser": "John Doe",
+ "id": 1,
+ "name": "API Test Email",
+ "subject": "Email created via API",
+ "fromAddress": "test@example.com",
+ "fromName": "Test From Name",
+ "replyToAddress": "reply@example.com",
+ "bccAddress": "bcc@example.com",
+ "useOwnerAsMailer": false,
+ "template": "blank",
+ "content": [],
+ "utmTags": [],
+ "plainText": "Plain text content here",
+ "customHtml": "Custom HTML content
",
+ "emailType": "list",
+ "publishUp": null,
+ "publishDown": null,
+ "readCount": 0,
+ "sentCount": 0,
+ "revision": 1,
+ "category": null,
+ "lists": [
+ {
+ "id": 2,
+ "name": "Test Segment",
+ "alias": "test-segment",
+ "description": "Description for test segment"
+ }
+ ],
+ "language": "en",
+ "publicPreview": false,
+ "assetAttachments": [],
+ "unsubscribeForm": null,
+ "preferenceCenter": null,
+ "dynamicContent": [],
+ "variantSentCount": 0,
+ "variantReadCount": 0,
+ "headers": []
+ }
+ }
+ }
+
+**Properties**
+
+Same as :ref:`rest_api/emails:Get Email`.
+
+.. vale off
+
+Create Email
+************
+
+.. vale on
+
+.. code-block:: php
+
+ 'Email created via API',
+ 'subject' => 'Hello World!',
+ 'emailType' => 'list',
+ 'customHtml' => 'Hello from API!
',
+ 'lists' => array(1, 2),
+ );
+
+ $email = $emailApi->create($data);
+
+Create a new Email.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``POST /emails/new``
+
+**POST Parameters**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Type
+ - Description
+ * - ``name``
+ - string
+ - Email name is the only required field
+ * - ``subject``
+ - string
+ - Email subject
+ * - ``fromAddress``
+ - string
+ - From email address
+ * - ``fromName``
+ - string
+ - From name
+ * - ``replyToAddress``
+ - string
+ - Reply-to email address
+ * - ``bccAddress``
+ - string
+ - BCC email address
+ * - ``useOwnerAsMailer``
+ - boolean
+ - Whether to use the Contact owner as the mailer
+ * - ``template``
+ - string
+ - Template to use for the Email
+ * - ``content``
+ - array
+ - Array of content for the template
+ * - ``utmTags``
+ - array
+ - Array of UTM tags for tracking
+ * - ``plainText``
+ - string
+ - Plain text version of the Email
+ * - ``customHtml``
+ - string
+ - Custom HTML content of the Email
+ * - ``emailType``
+ - string
+ - Type of the Email (``list`` or ``template``)
+ * - ``publishUp``
+ - datetime
+ - Date/time when the Email should be published
+ * - ``publishDown``
+ - datetime
+ - Date/time when the Email should be unpublished
+ * - ``category``
+ - int
+ - ID of the category to assign the Email to
+ * - ``lists``
+ - array
+ - Array of Segment/List IDs to assign the Email to
+ * - ``language``
+ - string
+ - Language of the Email
+ * - ``publicPreview``
+ - boolean
+ - Whether to enable public preview for the Email
+ * - ``assetAttachments``
+ - array
+ - Array of asset IDs to attach to the Email
+ * - ``unsubscribeForm``
+ - int
+ - ID of the unsubscribe form to use
+ * - ``preferenceCenter``
+ - int
+ - ID of the preference center page to use
+ * - ``dynamicContent``
+ - array
+ - Array of dynamic content variants
+ * - ``headers``
+ - array
+ - Array of custom headers
+ * - ``isPublished``
+ - boolean
+ - Published state
+
+**Response**
+
+``Expected Response Code: 201``
+
+**Properties**
+
+Same as :ref:`rest_api/emails:Get Email`.
+
+.. vale off
+
+Edit Email
+**********
+
+.. vale on
+
+.. code-block:: php
+
+ 'New email name',
+ 'subject' => 'New subject line',
+ );
+
+ // Create new a Email of ID 1 isn't found?
+ $createIfNotFound = true;
+
+ $email = $emailApi->edit($id, $data, $createIfNotFound);
+
+Edit a new Email. Note that this supports PUT or PATCH depending on the desired behavior.
+
+**PUT** creates an Email if the given ID doesn't exist and clears all the Email information, adds the information from the request.
+**PATCH** fails if the Email with the given ID doesn't exist and updates the Email field values with the values from the request.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+To edit an Email and return a 404 if the Email isn't found:
+
+``PATCH /emails/ID/edit``
+
+To edit an Email and create a new one if the Email isn't found:
+
+``PUT /emails/ID/edit``
+
+**POST Parameters**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Type
+ - Description
+ * - ``name``
+ - string
+ - Email name
+ * - ``subject``
+ - string
+ - Email subject
+ * - ``fromAddress``
+ - string
+ - From email address
+ * - ``fromName``
+ - string
+ - From name
+ * - ``replyToAddress``
+ - string
+ - Reply-to email address
+ * - ``bccAddress``
+ - string
+ - BCC email address
+ * - ``useOwnerAsMailer``
+ - boolean
+ - Whether to use the Contact owner as the mailer
+ * - ``template``
+ - string
+ - Template to use for the Email
+ * - ``content``
+ - array
+ - Array of content for the template
+ * - ``utmTags``
+ - array
+ - Array of UTM tags for tracking
+ * - ``plainText``
+ - string
+ - Plain text version of the Email
+ * - ``customHtml``
+ - string
+ - Custom HTML content of the Email
+ * - ``emailType``
+ - string
+ - Type of the Email (``list`` or ``template``)
+ * - ``publishUp``
+ - datetime
+ - Date/time when the Email should be published
+ * - ``publishDown``
+ - datetime
+ - Date/time when the Email should be unpublished
+ * - ``category``
+ - int
+ - ID of the category to assign the Email to
+ * - ``lists``
+ - array
+ - Array of Segment/List IDs to assign the Email to
+ * - ``language``
+ - string
+ - Language of the Email
+ * - ``publicPreview``
+ - boolean
+ - Whether to enable public preview for the Email
+ * - ``assetAttachments``
+ - array
+ - Array of asset IDs to attach to the Email
+ * - ``unsubscribeForm``
+ - int
+ - ID of the unsubscribe form to use
+ * - ``preferenceCenter``
+ - int
+ - ID of the preference center page to use
+ * - ``dynamicContent``
+ - array
+ - Array of dynamic content variants
+ * - ``headers``
+ - array
+ - Array of custom headers
+ * - ``isPublished``
+ - boolean
+ - Published state
+
+**Response**
+
+If ``PUT``, the expected response code is ``200`` if the Email was edited or ``201`` if created.
+If ``PATCH``, the expected response code is ``200``.
+
+**Properties**
+
+Same as :ref:`rest_api/emails:Get Email`.
+
+.. vale off
+
+Delete Email
+************
+
+.. vale on
+
+.. code-block:: php
+
+ delete($id);
+
+Delete an Email.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``DELETE /emails/ID/delete``
+
+**Response**
+
+``Expected Response Code: 200``
+
+**Properties**
+
+Same as :ref:`rest_api/emails:Get Email`.
+
+.. vale off
+
+Create Batch Emails
+*******************
+
+.. vale on
+
+.. code-block:: php
+
+ 'Email A created via API',
+ 'subject' => 'Hello from Email A!',
+ 'emailType' => 'list',
+ 'customHtml' => 'Hello from Email A!
',
+ 'lists' => array(1),
+ ),
+ array(
+ 'name' => 'Email B created via API',
+ 'subject' => 'Hello from Email B!',
+ 'emailType' => 'list',
+ 'customHtml' => 'Hello from Email B!
',
+ 'lists' => array(2),
+ )
+ );
+
+ $emails = $emailApi->createBatch($data);
+
+Create a batch of new Emails.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``POST /emails/batch/new``
+
+**POST Parameters**
+
+Array of Email data objects. Each object should contain the same parameters as for creating a single Email.
+
+**Response**
+
+``Expected Response Code: 201``
+
+**Properties**
+
+Array of Emails. Each record is the same as :ref:`rest_api/emails:Get Email`.
+
+.. vale off
+
+Edit Batch Emails
+*****************
+
+.. vale on
+
+.. code-block:: php
+
+ 1,
+ 'name' => 'Updated Email A name',
+ 'subject' => 'Updated Email A subject',
+ ),
+ array(
+ 'id' => 2,
+ 'name' => 'Updated Email B name',
+ 'subject' => 'Updated Email B subject',
+ )
+ );
+
+ $emails = $emailApi->editBatch($data);
+
+Edit multiple Emails in one request. Note that this supports PUT or PATCH depending on the desired behavior.
+
+**PUT** creates an Email if the given ID doesn't exist and clears all the Email information, adds the information from the request.
+**PATCH** fails if the Email with the given ID doesn't exist and updates the Email field values with the values from the request.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+To edit Emails and return a 404 if an Email isn't found:
+
+``PATCH /emails/batch/edit``
+
+To edit Emails and create new ones if an Email isn't found:
+
+``PUT /emails/batch/edit``
+
+**POST Parameters**
+
+Array of Email data objects. Each object should contain an ``id`` field and the fields to be updated.
+
+**Response**
+
+If ``PUT``, the expected response code is ``200`` if Emails were edited or ``201`` if created.
+If ``PATCH``, the expected response code is ``200``.
+
+**Properties**
+
+Array of Emails. Each record is the same as :ref:`rest_api/emails:Get Email`.
+
+.. vale off
+
+Delete Batch Emails
+*******************
+
+.. vale on
+
+.. code-block:: php
+
+ deleteBatch($ids);
+
+Delete multiple Emails.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``DELETE /emails/batch/delete``
+
+If you aren't using PHP, here is a URL example:
+
+``DELETE https://[example.com]/api/emails/batch/delete?ids=1,2``
+
+**Response**
+
+``Expected Response Code: 200``
+
+**Properties**
+
+Array of Emails. Each record is the same as :ref:`rest_api/emails:Get Email`.
+
+.. vale off
+
+Send Email to Segment
+*********************
+
+.. vale on
+
+.. code-block:: php
+
+ send($id);
+
+ // Send to specific list(s)
+ $response = $emailApi->sendToLists($id, $listIds);
+
+Send an Email to the Contacts in the Email's assigned lists or to provided list IDs.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``POST /emails/ID/send``
+
+**POST Parameters**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Description
+ * - ``lists``
+ - Array of list IDs to send to. If not provided, will use the Email's assigned lists.
+ * - ``limit``
+ - Maximum number of Contacts to send to. If not provided, will send to all Contacts.
+ * - ``batch``
+ - Batch size for sending. If not provided, will send all at once.
+
+**Response**
+
+``Expected Response Code: 200``
+
+.. code-block:: json
+
+ {
+ "success": 1,
+ "sentCount": 1,
+ "failedRecipients": 0
+ }
+
+.. vale off
+
+Send Email to Contact
+*********************
+
+.. vale on
+
+.. code-block:: php
+
+ sendToContact($emailId, $contactId, $options);
+
+Send an Email to a specific Contact.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``POST /emails/ID/contact/CONTACT_ID/send``
+
+**POST Parameters**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Description
+ * - ``tokens``
+ - Array of tokens to replace in the Email content
+ * - ``assetAttachments``
+ - Array of asset IDs to attach to the Email
+
+**Response**
+
+``Expected Response Code: 200``
+
+.. code-block:: json
+
+ {
+ "success": true
+ }
+
+**Tokens**
+
+You can send custom tokens to the Email via the ``tokens`` parameter. Tokens should be in the format ``{token_name}`` and can be used in the Email content.
+
+.. code-block:: php
+
+ 'John',
+ '{last_name}' => 'Doe',
+ '{custom_token}' => 'Custom Value'
+ );
+
+ $response = $emailApi->sendToContact($emailId, $contactId, array('tokens' => $tokens));
+
+.. vale off
+
+Create Email Reply
+******************
+
+.. vale on
+
+.. code-block:: php
+
+ reply($trackingHash);
+
+Create a reply to an Email using the tracking hash from the Email statistics.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``POST /emails/reply/TRACKING_HASH``
+
+**Response**
+
+``Expected Response Code: 201``
+
+.. code-block:: json
+
+ {
+ "success": true
+ }
\ No newline at end of file
diff --git a/docs/rest_api/forms.rst b/docs/rest_api/forms.rst
new file mode 100644
index 00000000..2862dc19
--- /dev/null
+++ b/docs/rest_api/forms.rst
@@ -0,0 +1,1315 @@
+Forms
+#####
+
+Use this endpoint to manipulate and obtain details on Mautic's Forms.
+
+**Using Mautic's API Library**
+
+You can interact with this API through the :xref:`Mautic API Library` as follows, or use the various http endpoints as described in this document.
+
+.. code-block:: php
+
+ newAuth($settings);
+ $apiUrl = "https://example.com";
+ $api = new MauticApi();
+ $formApi = $api->newApi("forms", $auth, $apiUrl);
+
+.. vale off
+
+Get Form
+********
+
+.. vale on
+
+.. code-block:: php
+
+ get($id);
+
+Get an individual Form by ID.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``GET /forms/ID``
+
+**Response**
+
+``Expected Response Code: 200``
+
+.. code-block:: json
+
+ {
+ "form": {
+ "isPublished": true,
+ "dateAdded": "2017-02-03T16:51:06+00:00",
+ "dateModified": "2017-02-03T19:11:54+00:00",
+ "createdBy": 1,
+ "createdByUser": "John Doe",
+ "modifiedBy": 1,
+ "modifiedByUser": "John Doe",
+ "id": 1,
+ "name": "API Test Form",
+ "description": "Form created via API",
+ "alias": "api-test-form",
+ "formType": "standalone",
+ "cachedHtml": "",
+ "template": null,
+ "inKioskMode": false,
+ "renderStyle": false,
+ "formAttributes": null,
+ "noIndex": false,
+ "progressiveProfilingLimit": null,
+ "postAction": "return",
+ "postActionProperty": null,
+ "publishUp": null,
+ "publishDown": null,
+ "language": "en",
+ "category": {
+ "createdByUser": "John Doe",
+ "modifiedByUser": "John Doe",
+ "id": 1,
+ "title": "Test Category",
+ "alias": "test-category",
+ "description": "Test category description",
+ "color": "ab5959",
+ "bundle": "form"
+ },
+ "fields": [
+ {
+ "id": 1,
+ "label": "Email",
+ "alias": "email",
+ "type": "text",
+ "defaultValue": null,
+ "isRequired": true,
+ "validationMessage": null,
+ "helpMessage": null,
+ "order": 1,
+ "properties": {
+ "placeholder": "Enter your email"
+ },
+ "labelAttributes": null,
+ "inputAttributes": null,
+ "containerAttributes": null,
+ "leadField": "email",
+ "saveResult": true,
+ "isAutoFill": false,
+ "showWhenValueExists": false,
+ "showAfterXSubmissions": 0,
+ "isConditionallyHidden": false,
+ "parent": null,
+ "conditions": null,
+ "mappedField": "email",
+ "mappedObject": "contact"
+ }
+ ],
+ "actions": [
+ {
+ "id": 1,
+ "type": "email",
+ "name": "Send notification",
+ "description": "Send email notification",
+ "order": 1,
+ "properties": {
+ "subject": "New form submission",
+ "message": "A new form submission has been received.",
+ "email": "admin@example.com"
+ }
+ }
+ ]
+ }
+ }
+
+**Form Properties**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Type
+ - Description
+ * - ``id``
+ - int
+ - ID of the Form
+ * - ``name``
+ - string
+ - Name of the Form
+ * - ``description``
+ - string
+ - Description of the Form
+ * - ``alias``
+ - string
+ - Alias/slug of the Form
+ * - ``formType``
+ - string
+ - Type of the Form (``standalone`` or ``campaign``)
+ * - ``cachedHtml``
+ - string
+ - Cached HTML of the Form
+ * - ``template``
+ - string/null
+ - Template used for the Form
+ * - ``inKioskMode``
+ - boolean
+ - Whether the Form is in kiosk mode
+ * - ``renderStyle``
+ - boolean
+ - Whether to render form with style
+ * - ``formAttributes``
+ - string/null
+ - Custom form attributes
+ * - ``noIndex``
+ - boolean
+ - Whether the Form should not be indexed by search engines
+ * - ``progressiveProfilingLimit``
+ - int/null
+ - Progressive profiling limit
+ * - ``postAction``
+ - string
+ - Action to take after form submission (``return``, ``redirect``, ``message``)
+ * - ``postActionProperty``
+ - string/null
+ - Additional property for post action (URL for redirect, message for message)
+ * - ``publishUp``
+ - datetime/null
+ - Date/time when the Form should be published
+ * - ``publishDown``
+ - datetime/null
+ - Date/time when the Form should be unpublished
+ * - ``language``
+ - string
+ - Language of the Form
+ * - ``category``
+ - object/null
+ - Category the Form belongs to
+ * - ``fields``
+ - array
+ - Array of Form fields
+ * - ``actions``
+ - array
+ - Array of Form actions/submit actions
+ * - ``isPublished``
+ - boolean
+ - Published state
+ * - ``dateAdded``
+ - datetime
+ - Date/time Form was created
+ * - ``createdBy``
+ - int
+ - ID of the User that created the Form
+ * - ``createdByUser``
+ - string
+ - Name of the User that created the Form
+ * - ``dateModified``
+ - datetime/null
+ - Date/time Form was last modified
+ * - ``modifiedBy``
+ - int
+ - ID of the User that last modified the Form
+ * - ``modifiedByUser``
+ - string
+ - Name of the User that last modified the Form
+
+**Form Field Properties**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Type
+ - Description
+ * - ``id``
+ - int
+ - ID of the Field
+ * - ``label``
+ - string
+ - Label of the Field
+ * - ``alias``
+ - string
+ - Alias/name of the Field
+ * - ``type``
+ - string
+ - Type of the Field (``text``, ``email``, ``select``, ``textarea``, etc.)
+ * - ``defaultValue``
+ - string/null
+ - Default value of the Field
+ * - ``isRequired``
+ - boolean
+ - Whether the Field is required
+ * - ``validationMessage``
+ - string/null
+ - Custom validation message
+ * - ``helpMessage``
+ - string/null
+ - Help message for the Field
+ * - ``order``
+ - int
+ - Order of the Field in the Form
+ * - ``properties``
+ - object
+ - Additional properties specific to the Field type
+ * - ``labelAttributes``
+ - string/null
+ - Custom attributes for the Field label
+ * - ``inputAttributes``
+ - string/null
+ - Custom attributes for the Field input
+ * - ``containerAttributes``
+ - string/null
+ - Custom attributes for the Field container
+ * - ``leadField``
+ - string
+ - Contact field the Form field maps to (deprecated, use mappedField/mappedObject)
+ * - ``saveResult``
+ - boolean
+ - Whether to save the Field result
+ * - ``isAutoFill``
+ - boolean
+ - Whether to auto-fill the Field
+ * - ``showWhenValueExists``
+ - boolean
+ - Whether to show field when value exists
+ * - ``showAfterXSubmissions``
+ - int
+ - Show field after X submissions
+ * - ``isConditionallyHidden``
+ - boolean
+ - Whether the Field is conditionally hidden
+ * - ``parent``
+ - int/null
+ - ID of the parent Field for conditional fields
+ * - ``conditions``
+ - object/null
+ - Conditions for showing the Field
+ * - ``mappedField``
+ - string
+ - Contact/Company field the Form field maps to
+ * - ``mappedObject``
+ - string
+ - Object the Field maps to (``contact`` or ``company``)
+
+**Form Action Properties**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Type
+ - Description
+ * - ``id``
+ - int
+ - ID of the Action
+ * - ``type``
+ - string
+ - Type of the Action (``email``, ``lead.changetags``, ``lead.pointschange``, etc.)
+ * - ``name``
+ - string
+ - Name of the Action
+ * - ``description``
+ - string
+ - Description of the Action
+ * - ``order``
+ - int
+ - Order of the Action execution
+ * - ``properties``
+ - object
+ - Properties specific to the Action type
+
+.. vale off
+
+List Forms
+**********
+
+.. vale on
+
+.. code-block:: php
+
+ getList($searchFilter, $start, $limit, $orderBy, $orderByDir, $publishedOnly, $minimal);
+
+Returns a list of Forms available to the User. This list is filterable and sortable.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``GET /forms``
+
+**Query Parameters**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Description
+ * - ``search``
+ - String or search command to filter entities by.
+ * - ``start``
+ - Starting row for the entities returned. Defaults to 0.
+ * - ``limit``
+ - Limit number of entities to return. Defaults to the system configuration for pagination, which is 30 by default.
+ * - ``orderBy``
+ - Column to sort by. Can use any column listed in the response. However, you need to change all properties in the response written in ``camelCase`` a bit. Before every capital, add an underscore ``_`` and then change the capital letters to non-capital letters. So ``dateAdded`` becomes ``date_added``, ``modifiedBy`` becomes ``modified_by``, etc.
+ * - ``orderByDir``
+ - Sort direction: ``asc`` or ``desc``.
+ * - ``publishedOnly``
+ - Only return currently published entities.
+ * - ``minimal``
+ - Return only array of entities without additional lists in it.
+
+**Response**
+
+``Expected Response Code: 200``
+
+.. code-block:: json
+
+ {
+ "total": 1,
+ "forms": {
+ "1": {
+ "isPublished": true,
+ "dateAdded": "2017-02-03T16:51:06+00:00",
+ "dateModified": "2017-02-03T19:11:54+00:00",
+ "createdBy": 1,
+ "createdByUser": "John Doe",
+ "modifiedBy": 1,
+ "modifiedByUser": "John Doe",
+ "id": 1,
+ "name": "API Test Form",
+ "description": "Form created via API",
+ "alias": "api-test-form",
+ "formType": "standalone",
+ "cachedHtml": "",
+ "template": null,
+ "inKioskMode": false,
+ "renderStyle": false,
+ "postAction": "return",
+ "postActionProperty": null,
+ "publishUp": null,
+ "publishDown": null,
+ "language": "en",
+ "category": null,
+ "fields": [],
+ "actions": []
+ }
+ }
+ }
+
+**Properties**
+
+Same as :ref:`rest_api/forms:Get Form`.
+
+.. vale off
+
+Create Form
+***********
+
+.. vale on
+
+.. code-block:: php
+
+ 'Form created via API',
+ 'formType' => 'standalone',
+ 'description' => 'This is a test form created via API',
+ 'fields' => array(
+ array(
+ 'label' => 'Email',
+ 'type' => 'text',
+ 'alias' => 'email',
+ 'mappedObject' => 'contact',
+ 'mappedField' => 'email',
+ 'isRequired' => true,
+ ),
+ array(
+ 'label' => 'Submit',
+ 'type' => 'button',
+ ),
+ ),
+ 'actions' => array(
+ array(
+ 'name' => 'Send notification',
+ 'type' => 'email',
+ 'description' => 'Send email notification',
+ 'properties' => array(
+ 'subject' => 'New form submission',
+ 'message' => 'A new form submission has been received.',
+ 'email' => 'admin@example.com'
+ ),
+ ),
+ ),
+ 'postAction' => 'return',
+ );
+
+ $form = $formApi->create($data);
+
+Create a new Form.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``POST /forms/new``
+
+**POST Parameters**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Type
+ - Description
+ * - ``name``
+ - string
+ - Form name is the only required field
+ * - ``description``
+ - string
+ - Description of the Form
+ * - ``alias``
+ - string
+ - Alias/slug of the Form (auto-generated if not provided)
+ * - ``formType``
+ - string
+ - Type of the Form (``standalone`` or ``campaign``)
+ * - ``template``
+ - string
+ - Template to use for the Form
+ * - ``inKioskMode``
+ - boolean
+ - Whether the Form should be in kiosk mode
+ * - ``renderStyle``
+ - boolean
+ - Whether to render form with style
+ * - ``formAttributes``
+ - string
+ - Custom form attributes
+ * - ``noIndex``
+ - boolean
+ - Whether the Form should not be indexed by search engines
+ * - ``progressiveProfilingLimit``
+ - int
+ - Progressive profiling limit
+ * - ``postAction``
+ - string
+ - Action after form submission (``return``, ``redirect``, ``message``)
+ * - ``postActionProperty``
+ - string
+ - Additional property for post action
+ * - ``publishUp``
+ - datetime
+ - Date/time when the Form should be published
+ * - ``publishDown``
+ - datetime
+ - Date/time when the Form should be unpublished
+ * - ``language``
+ - string
+ - Language of the Form
+ * - ``category``
+ - int
+ - ID of the category to assign the Form to
+ * - ``fields``
+ - array
+ - Array of Form fields to create
+ * - ``actions``
+ - array
+ - Array of Form actions to create
+ * - ``isPublished``
+ - boolean
+ - Published state
+
+**Response**
+
+``Expected Response Code: 201``
+
+**Properties**
+
+Same as :ref:`rest_api/forms:Get Form`.
+
+.. vale off
+
+Edit Form
+*********
+
+.. vale on
+
+.. code-block:: php
+
+ 'Updated form name',
+ 'description' => 'Updated description',
+ 'fields' => array(
+ array(
+ 'id' => 1, // Existing field
+ 'label' => 'Updated Email Label',
+ 'type' => 'text',
+ 'alias' => 'email',
+ 'mappedObject' => 'contact',
+ 'mappedField' => 'email',
+ 'isRequired' => true,
+ ),
+ array(
+ 'label' => 'First Name', // New field
+ 'type' => 'text',
+ 'alias' => 'first_name',
+ 'mappedObject' => 'contact',
+ 'mappedField' => 'firstname',
+ ),
+ ),
+ );
+
+ // Create new a Form of ID 1 isn't found?
+ $createIfNotFound = true;
+
+ $form = $formApi->edit($id, $data, $createIfNotFound);
+
+Edit a Form. Note that this supports PUT or PATCH depending on the desired behavior.
+
+**PUT** creates a Form if the given ID doesn't exist and clears all the Form information, adds the information from the request.
+**PATCH** fails if the Form with the given ID doesn't exist and updates the Form field values with the values from the request.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+To edit a Form and return a 404 if the Form isn't found:
+
+``PATCH /forms/ID/edit``
+
+To edit a Form and create a new one if the Form isn't found:
+
+``PUT /forms/ID/edit``
+
+**POST Parameters**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Type
+ - Description
+ * - ``name``
+ - string
+ - Form name
+ * - ``description``
+ - string
+ - Description of the Form
+ * - ``alias``
+ - string
+ - Alias/slug of the Form
+ * - ``formType``
+ - string
+ - Type of the Form (``standalone`` or ``campaign``)
+ * - ``template``
+ - string
+ - Template to use for the Form
+ * - ``inKioskMode``
+ - boolean
+ - Whether the Form should be in kiosk mode
+ * - ``renderStyle``
+ - boolean
+ - Whether to render form with style
+ * - ``formAttributes``
+ - string
+ - Custom form attributes
+ * - ``noIndex``
+ - boolean
+ - Whether the Form should not be indexed by search engines
+ * - ``progressiveProfilingLimit``
+ - int
+ - Progressive profiling limit
+ * - ``postAction``
+ - string
+ - Action after form submission (``return``, ``redirect``, ``message``)
+ * - ``postActionProperty``
+ - string
+ - Additional property for post action
+ * - ``publishUp``
+ - datetime
+ - Date/time when the Form should be published
+ * - ``publishDown``
+ - datetime
+ - Date/time when the Form should be unpublished
+ * - ``language``
+ - string
+ - Language of the Form
+ * - ``category``
+ - int
+ - ID of the category to assign the Form to
+ * - ``fields``
+ - array
+ - Array of Form fields (include ``id`` for existing fields to update them)
+ * - ``actions``
+ - array
+ - Array of Form actions (include ``id`` for existing actions to update them)
+ * - ``isPublished``
+ - boolean
+ - Published state
+
+**Response**
+
+If ``PUT``, the expected response code is ``200`` if the Form was edited or ``201`` if created.
+If ``PATCH``, the expected response code is ``200``.
+
+**Properties**
+
+Same as :ref:`rest_api/forms:Get Form`.
+
+.. vale off
+
+Delete Form
+***********
+
+.. vale on
+
+.. code-block:: php
+
+ delete($id);
+
+Delete a Form.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``DELETE /forms/ID/delete``
+
+**Response**
+
+``Expected Response Code: 200``
+
+**Properties**
+
+Same as :ref:`rest_api/forms:Get Form`.
+
+.. vale off
+
+Delete Form Fields
+******************
+
+.. vale on
+
+.. code-block:: php
+
+ deleteFields($formId, array(1, 2, 3));
+
+Delete specific fields from a Form.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``DELETE /forms/ID/fields/delete``
+
+**POST Parameters**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Type
+ - Description
+ * - ``fields``
+ - array
+ - Array of field IDs to delete
+
+**Response**
+
+``Expected Response Code: 200``
+
+**Properties**
+
+Same as :ref:`rest_api/forms:Get Form`.
+
+.. vale off
+
+Delete Form Actions
+*******************
+
+.. vale on
+
+.. code-block:: php
+
+ deleteActions($formId, array(1, 2));
+
+Delete specific actions from a Form.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``DELETE /forms/ID/actions/delete``
+
+**POST Parameters**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Type
+ - Description
+ * - ``actions``
+ - array
+ - Array of action IDs to delete
+
+**Response**
+
+``Expected Response Code: 200``
+
+**Properties**
+
+Same as :ref:`rest_api/forms:Get Form`.
+
+.. vale off
+
+Create Batch Forms
+******************
+
+.. vale on
+
+.. code-block:: php
+
+ 'Form A created via API',
+ 'formType' => 'standalone',
+ 'description' => 'This is Form A',
+ 'fields' => array(
+ array(
+ 'label' => 'Email',
+ 'type' => 'text',
+ 'alias' => 'email',
+ 'mappedObject' => 'contact',
+ 'mappedField' => 'email',
+ 'isRequired' => true,
+ ),
+ ),
+ ),
+ array(
+ 'name' => 'Form B created via API',
+ 'formType' => 'standalone',
+ 'description' => 'This is Form B',
+ 'fields' => array(
+ array(
+ 'label' => 'First Name',
+ 'type' => 'text',
+ 'alias' => 'firstname',
+ 'mappedObject' => 'contact',
+ 'mappedField' => 'firstname',
+ ),
+ ),
+ )
+ );
+
+ $forms = $formApi->createBatch($data);
+
+Create a batch of new Forms.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``POST /forms/batch/new``
+
+**POST Parameters**
+
+Array of Form data objects. Each object should contain the same parameters as for creating a single Form.
+
+**Response**
+
+``Expected Response Code: 201``
+
+**Properties**
+
+Array of Forms. Each record is the same as :ref:`rest_api/forms:Get Form`.
+
+.. vale off
+
+Edit Batch Forms
+****************
+
+.. vale on
+
+.. code-block:: php
+
+ 1,
+ 'name' => 'Updated Form A name',
+ 'description' => 'Updated Form A description',
+ ),
+ array(
+ 'id' => 2,
+ 'name' => 'Updated Form B name',
+ 'description' => 'Updated Form B description',
+ )
+ );
+
+ $forms = $formApi->editBatch($data);
+
+Edit multiple Forms in one request. Note that this supports PUT or PATCH depending on the desired behavior.
+
+**PUT** creates a Form if the given ID doesn't exist and clears all the Form information, adds the information from the request.
+**PATCH** fails if the Form with the given ID doesn't exist and updates the Form field values with the values from the request.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+To edit Forms and return a 404 if a Form isn't found:
+
+``PATCH /forms/batch/edit``
+
+To edit Forms and create new ones if a Form isn't found:
+
+``PUT /forms/batch/edit``
+
+**POST Parameters**
+
+Array of Form data objects. Each object should contain an ``id`` field and the fields to be updated.
+
+**Response**
+
+If ``PUT``, the expected response code is ``200`` if Forms were edited or ``201`` if created.
+If ``PATCH``, the expected response code is ``200``.
+
+**Properties**
+
+Array of Forms. Each record is the same as :ref:`rest_api/forms:Get Form`.
+
+.. vale off
+
+Delete Batch Forms
+******************
+
+.. vale on
+
+.. code-block:: php
+
+ deleteBatch($ids);
+
+Delete multiple Forms.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``DELETE /forms/batch/delete``
+
+If you aren't using PHP, here is a URL example:
+
+``DELETE https://[example.com]/api/forms/batch/delete?ids=1,2``
+
+**Response**
+
+``Expected Response Code: 200``
+
+**Properties**
+
+Array of Forms. Each record is the same as :ref:`rest_api/forms:Get Form`.
+
+.. vale off
+
+Get Form Submissions
+********************
+
+.. vale on
+
+.. code-block:: php
+
+ getSubmissions($formId, $searchFilter, $start, $limit, $orderBy, $orderByDir);
+
+Get a list of submissions for a specific Form.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``GET /forms/ID/submissions``
+
+**Query Parameters**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Description
+ * - ``search``
+ - String or search command to filter entities by.
+ * - ``start``
+ - Starting row for the entities returned. Defaults to 0.
+ * - ``limit``
+ - Limit number of entities to return. Defaults to the system configuration for pagination, which is 30 by default.
+ * - ``orderBy``
+ - Column to sort by. Can use any column listed in the response.
+ * - ``orderByDir``
+ - Sort direction: ``asc`` or ``desc``.
+
+**Response**
+
+``Expected Response Code: 200``
+
+.. code-block:: json
+
+ {
+ "total": 1,
+ "submissions": [
+ {
+ "id": 1,
+ "ipAddress": {
+ "id": 1,
+ "ipAddress": "127.0.0.1"
+ },
+ "form": {
+ "id": 1,
+ "name": "API Test Form",
+ "alias": "api-test-form"
+ },
+ "lead": {
+ "id": 1,
+ "points": 0,
+ "color": null,
+ "fields": {
+ "core": {
+ "firstname": {
+ "id": "1",
+ "label": "First Name",
+ "alias": "firstname",
+ "type": "text",
+ "group": "core",
+ "value": "John"
+ },
+ "lastname": {
+ "id": "2",
+ "label": "Last Name",
+ "alias": "lastname",
+ "type": "text",
+ "group": "core",
+ "value": "Doe"
+ },
+ "email": {
+ "id": "3",
+ "label": "Email",
+ "alias": "email",
+ "type": "email",
+ "group": "core",
+ "value": "john@doe.com"
+ }
+ }
+ }
+ },
+ "trackingId": "abc123def456",
+ "dateSubmitted": "2017-02-03T16:51:06+00:00",
+ "referer": "https://example.com/form/1",
+ "page": null,
+ "results": {
+ "email": "john@doe.com",
+ "firstname": "John",
+ "lastname": "Doe"
+ }
+ }
+ ]
+ }
+
+.. vale off
+
+Get Form Submission
+*******************
+
+.. vale on
+
+.. code-block:: php
+
+ getSubmission($formId, $submissionId);
+
+Get an individual submission for a specific Form.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``GET /forms/FORM_ID/submissions/SUBMISSION_ID``
+
+**Response**
+
+``Expected Response Code: 200``
+
+.. code-block:: json
+
+ {
+ "submission": {
+ "id": 1,
+ "ipAddress": {
+ "id": 1,
+ "ipAddress": "127.0.0.1"
+ },
+ "form": {
+ "id": 1,
+ "name": "API Test Form",
+ "alias": "api-test-form"
+ },
+ "lead": {
+ "id": 1,
+ "points": 0,
+ "color": null,
+ "fields": {
+ "core": {
+ "firstname": {
+ "id": "1",
+ "label": "First Name",
+ "alias": "firstname",
+ "type": "text",
+ "group": "core",
+ "value": "John"
+ },
+ "email": {
+ "id": "3",
+ "label": "Email",
+ "alias": "email",
+ "type": "email",
+ "group": "core",
+ "value": "john@doe.com"
+ }
+ }
+ }
+ },
+ "trackingId": "abc123def456",
+ "dateSubmitted": "2017-02-03T16:51:06+00:00",
+ "referer": "https://example.com/form/1",
+ "page": null,
+ "results": {
+ "email": "john@doe.com",
+ "firstname": "John"
+ }
+ }
+ }
+
+.. vale off
+
+Get Contact Form Submissions
+****************************
+
+.. vale on
+
+.. code-block:: php
+
+ getContactSubmissions($formId, $contactId, $searchFilter, $start, $limit, $orderBy, $orderByDir);
+
+Get submissions for a specific Form and Contact.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``GET /forms/FORM_ID/submissions/contact/CONTACT_ID``
+
+**Query Parameters**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Description
+ * - ``search``
+ - String or search command to filter entities by.
+ * - ``start``
+ - Starting row for the entities returned. Defaults to 0.
+ * - ``limit``
+ - Limit number of entities to return. Defaults to the system configuration for pagination, which is 30 by default.
+ * - ``orderBy``
+ - Column to sort by. Can use any column listed in the response.
+ * - ``orderByDir``
+ - Sort direction: ``asc`` or ``desc``.
+
+**Response**
+
+``Expected Response Code: 200``
+
+Same format as :ref:`rest_api/forms:Get Form Submissions`.
+
+**Form Field Types**
+
+Mautic supports various field types for Forms. Here are the most common types:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Type
+ - Description
+ - Properties
+ * - ``text``
+ - Single line text input
+ - ``placeholder``, ``maxlength``
+ * - ``textarea``
+ - Multi-line text input
+ - ``placeholder``, ``rows``, ``maxlength``
+ * - ``email``
+ - Email input with validation
+ - ``placeholder``
+ * - ``number``
+ - Number input
+ - ``placeholder``, ``min``, ``max``, ``step``
+ * - ``tel``
+ - Telephone input
+ - ``placeholder``
+ * - ``url``
+ - URL input with validation
+ - ``placeholder``
+ * - ``select``
+ - Dropdown selection
+ - ``list`` (options), ``multiple``, ``syncList``
+ * - ``radio``
+ - Radio button group
+ - ``list`` (options)
+ * - ``checkbox``
+ - Checkbox input
+ - ``list`` (options)
+ * - ``checkboxgrp``
+ - Checkbox group
+ - ``list`` (options)
+ * - ``country``
+ - Country selection dropdown
+ - None
+ * - ``date``
+ - Date picker
+ - ``format``
+ * - ``datetime``
+ - Date and time picker
+ - ``format``
+ * - ``time``
+ - Time picker
+ - ``format``
+ * - ``button``
+ - Submit button
+ - None
+ * - ``hidden``
+ - Hidden field
+ - None
+ * - ``file``
+ - File upload
+ - ``allowed_file_size``, ``allowed_file_extensions``
+ * - ``captcha``
+ - CAPTCHA field
+ - None
+ * - ``pagebreak``
+ - Page break for multi-page forms
+ - None
+
+**Form Action Types**
+
+Forms can have various actions that are executed when the form is submitted:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Type
+ - Description
+ - Properties
+ * - ``email``
+ - Send email notification
+ - ``subject``, ``message``, ``email``, ``copy_lead``
+ * - ``lead.changetags``
+ - Add/remove tags from contact
+ - ``add_tags``, ``remove_tags``
+ * - ``lead.pointschange``
+ - Change contact points
+ - ``points``, ``operator``
+ * - ``lead.changeowner``
+ - Change contact owner
+ - ``owner``
+ * - ``lead.addtocompany``
+ - Add contact to company
+ - ``company``
+ * - ``asset.download``
+ - Trigger asset download
+ - ``asset``
+ * - ``form.submit.redirect``
+ - Redirect to URL
+ - ``redirect_url``
+ * - ``form.submit.message``
+ - Show message
+ - ``message``
+
+**Progressive Profiling**
+
+Progressive profiling allows you to collect more information from contacts over time by showing different fields based on previous submissions. To enable progressive profiling:
+
+1. Set ``progressiveProfilingLimit`` on the form
+2. Configure fields with ``showAfterXSubmissions`` property
+3. Use ``showWhenValueExists`` to hide fields when contact already has a value
+
+**Conditional Fields**
+
+Fields can be conditionally shown based on other field values:
+
+1. Set the ``parent`` field ID
+2. Configure ``conditions`` with expression type (``eq``, ``neq``, ``in``, ``!in``)
+3. Set ``isConditionallyHidden`` to true
+
+**Mapped Fields**
+
+Form fields can be mapped to Contact or Company fields:
+
+- Use ``mappedObject`` to specify ``contact`` or ``company``
+- Use ``mappedField`` to specify the target field name
+- The deprecated ``leadField`` property is still supported for backward compatibility
\ No newline at end of file
diff --git a/docs/rest_api/segments.rst b/docs/rest_api/segments.rst
new file mode 100644
index 00000000..134b7767
--- /dev/null
+++ b/docs/rest_api/segments.rst
@@ -0,0 +1,764 @@
+Segments
+########
+
+Use this endpoint to manipulate and obtain details on Mautic's Segments (also known as Lists).
+
+**Using Mautic's API Library**
+
+You can interact with this API through the :xref:`Mautic API Library` as follows, or use the various http endpoints as described in this document.
+
+.. code-block:: php
+
+ newAuth($settings);
+ $apiUrl = "https://example.com";
+ $api = new MauticApi();
+ $segmentApi = $api->newApi("segments", $auth, $apiUrl);
+
+.. vale off
+
+Get Segment
+***********
+
+.. vale on
+
+.. code-block:: php
+
+ get($id);
+
+Get an individual Segment by ID.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``GET /segments/ID``
+
+**Response**
+
+``Expected Response Code: 200``
+
+.. code-block:: json
+
+ {
+ "list": {
+ "id": 1,
+ "isPublished": true,
+ "dateAdded": "2015-07-15T15:06:02-05:00",
+ "createdBy": 1,
+ "createdByUser": "Joe Smith",
+ "dateModified": "2015-07-20T13:11:56-05:00",
+ "modifiedBy": 1,
+ "modifiedByUser": "Joe Smith",
+ "name": "VIP Customers",
+ "alias": "vip-customers",
+ "description": "High-value customers",
+ "publicName": "VIP List",
+ "filters": [
+ {
+ "glue": "and",
+ "field": "points",
+ "object": "lead",
+ "type": "number",
+ "operator": "gte",
+ "properties": {
+ "filter": "100"
+ }
+ }
+ ],
+ "isGlobal": true,
+ "isPreferenceCenter": false,
+ "category": {
+ "id": 1,
+ "title": "Customer Segments",
+ "alias": "customer-segments",
+ "color": "4e5d9d",
+ "bundle": "lead"
+ }
+ }
+ }
+
+**Segment Properties**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Type
+ - Description
+ * - ``id``
+ - int
+ - ID of the Segment
+ * - ``isPublished``
+ - boolean
+ - ``true`` if the Segment is published
+ * - ``dateAdded``
+ - ``datetime``
+ - Date/time Segment was created
+ * - ``createdBy``
+ - int
+ - ID of the User that created the Segment
+ * - ``createdByUser``
+ - string
+ - Name of the User that created the Segment
+ * - ``dateModified``
+ - datetime/null
+ - Date/time Segment was last modified
+ * - ``modifiedBy``
+ - int
+ - ID of the User that last modified the Segment
+ * - ``modifiedByUser``
+ - string
+ - Name of the User that last modified the Segment
+ * - ``name``
+ - string
+ - Name of the Segment
+ * - ``alias``
+ - string
+ - Alias of the Segment used for searches and URLs
+ * - ``description``
+ - string/null
+ - Description of the Segment
+ * - ``publicName``
+ - string/null
+ - Public name of the Segment (displayed to contacts)
+ * - ``filters``
+ - array
+ - Array of filter criteria that define the Segment
+ * - ``isGlobal``
+ - boolean
+ - ``true`` if the Segment is global (visible to all users)
+ * - ``isPreferenceCenter``
+ - boolean
+ - ``true`` if the Segment can be used in preference centers
+ * - ``category``
+ - object/null
+ - Category object that contains the Segment
+
+.. vale off
+
+List Segments
+*************
+
+.. vale on
+
+.. code-block:: php
+
+ getList($searchFilter, $start, $limit, $orderBy, $orderByDir, $publishedOnly, $minimal);
+
+Get a list of Segments.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``GET /segments``
+
+**Query Parameters**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Description
+ * - ``search``
+ - String or search command to filter entities by.
+ * - ``start``
+ - Starting row for the entities returned. Defaults to 0.
+ * - ``limit``
+ - Limit number of entities to return. Defaults to the system configuration for pagination, which is 30 by default.
+ * - ``orderBy``
+ - Column to sort by. Can use any column listed in the response. However, you need to change all properties in the response written in ``camelCase`` a bit. Before every capital, add an underscore ``_`` and then change the capital letters to non-capital letters. So ``dateAdded`` becomes ``date_added``, ``modifiedByUser`` becomes ``modified_by_user``, etc.
+ * - ``orderByDir``
+ - Sort direction: ``asc`` or ``desc``.
+ * - ``publishedOnly``
+ - Only return currently published entities.
+ * - ``minimal``
+ - Return only array of entities without additional lists in it.
+ * - ``where``
+ - An array of advanced where conditions
+ * - ``order``
+ - An array of advanced order statements
+
+**Response**
+
+``Expected Response Code: 200``
+
+.. code-block:: json
+
+ {
+ "total": 1,
+ "lists": {
+ "1": {
+ "id": 1,
+ "isPublished": true,
+ "dateAdded": "2015-07-15T15:06:02-05:00",
+ "createdBy": 1,
+ "createdByUser": "Joe Smith",
+ "dateModified": "2015-07-20T13:11:56-05:00",
+ "modifiedBy": 1,
+ "modifiedByUser": "Joe Smith",
+ "name": "VIP Customers",
+ "alias": "vip-customers",
+ "description": "High-value customers",
+ "publicName": "VIP List",
+ "filters": [
+ {
+ "glue": "and",
+ "field": "points",
+ "object": "lead",
+ "type": "number",
+ "operator": "gte",
+ "properties": {
+ "filter": "100"
+ }
+ }
+ ],
+ "isGlobal": true,
+ "isPreferenceCenter": false,
+ "category": {
+ "id": 1,
+ "title": "Customer Segments",
+ "alias": "customer-segments",
+ "color": "4e5d9d",
+ "bundle": "lead"
+ }
+ }
+ }
+ }
+
+**Properties**
+
+Same as :ref:`rest_api/segments:Get Segment`.
+
+.. vale off
+
+Create Segment
+**************
+
+.. vale on
+
+.. code-block:: php
+
+ 'VIP Customers',
+ 'alias' => 'vip-customers',
+ 'description' => 'High-value customers',
+ 'isPublished' => true,
+ 'isGlobal' => true,
+ 'filters' => array(
+ array(
+ 'glue' => 'and',
+ 'field' => 'points',
+ 'object' => 'lead',
+ 'type' => 'number',
+ 'operator' => 'gte',
+ 'properties' => array(
+ 'filter' => '100'
+ )
+ )
+ )
+ );
+
+ $segment = $segmentApi->create($data);
+
+Create a new Segment.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``POST /segments/new``
+
+**POST Parameters**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Type
+ - Description
+ * - ``name``
+ - string
+ - Segment name (required)
+ * - ``alias``
+ - string
+ - Segment alias used for URLs and searches
+ * - ``description``
+ - string
+ - Segment description
+ * - ``publicName``
+ - string
+ - Public name displayed to contacts
+ * - ``isPublished``
+ - boolean
+ - Whether the Segment is published (defaults to ``false``)
+ * - ``isGlobal``
+ - boolean
+ - Whether the Segment is global (defaults to ``true``)
+ * - ``isPreferenceCenter``
+ - boolean
+ - Whether the Segment can be used in preference centers (defaults to ``false``)
+ * - ``filters``
+ - array
+ - Array of filter criteria that define the Segment
+ * - ``category``
+ - int
+ - ID of the Category to assign to the Segment
+
+**Response**
+
+``Expected Response Code: 201``
+
+**Properties**
+
+Same as :ref:`rest_api/segments:Get Segment`.
+
+.. vale off
+
+Edit Segment
+************
+
+.. vale on
+
+.. code-block:: php
+
+ 'Updated VIP Customers',
+ 'description' => 'Updated high-value customers segment',
+ );
+
+ // Create new a Segment of ID 1 isn't found?
+ $createIfNotFound = true;
+
+ $segment = $segmentApi->edit($id, $data, $createIfNotFound);
+
+Edit a new Segment. Note that this supports PUT or PATCH depending on the desired behavior.
+
+**PUT** creates a Segment if the given ID doesn't exist and clears all the Segment information, adds the information from the request.
+**PATCH** fails if the Segment with the given ID doesn't exist and updates the Segment field values with the values from the request.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+To edit a Segment and return a 404 if the Segment isn't found:
+
+``PATCH /segments/ID/edit``
+
+To edit a Segment and create a new one if the Segment isn't found:
+
+``PUT /segments/ID/edit``
+
+**POST Parameters**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Type
+ - Description
+ * - ``name``
+ - string
+ - Segment name
+ * - ``alias``
+ - string
+ - Segment alias used for URLs and searches
+ * - ``description``
+ - string
+ - Segment description
+ * - ``publicName``
+ - string
+ - Public name displayed to contacts
+ * - ``isPublished``
+ - boolean
+ - Whether the Segment is published
+ * - ``isGlobal``
+ - boolean
+ - Whether the Segment is global
+ * - ``isPreferenceCenter``
+ - boolean
+ - Whether the Segment can be used in preference centers
+ * - ``filters``
+ - array
+ - Array of filter criteria that define the Segment
+ * - ``category``
+ - int
+ - ID of the Category to assign to the Segment
+
+**Response**
+
+If ``PUT``, the expected response code is ``200`` if the Segment was edited or ``201`` if created.
+If ``PATCH``, the expected response code is ``200``.
+
+**Properties**
+
+Same as :ref:`rest_api/segments:Get Segment`.
+
+.. vale off
+
+Delete Segment
+**************
+
+.. vale on
+
+.. code-block:: php
+
+ delete($id);
+
+Delete a Segment.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``DELETE /segments/ID/delete``
+
+**Response**
+
+``Expected Response Code: 200``
+
+**Properties**
+
+Same as :ref:`rest_api/segments:Get Segment`.
+
+.. vale off
+
+Add Contact to Segment
+**********************
+
+.. vale on
+
+.. code-block:: php
+
+ addContact($segmentId, $contactId);
+
+Add a Contact to a Segment.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``POST /segments/SEGMENT_ID/contact/CONTACT_ID/add``
+
+**Response**
+
+``Expected Response Code: 200``
+
+.. code-block:: json
+
+ {
+ "success": 1
+ }
+
+.. vale off
+
+Add Contacts to Segment
+***********************
+
+.. vale on
+
+.. code-block:: php
+
+ addContacts($segmentId, $contactIds);
+
+Add multiple Contacts to a Segment.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``POST /segments/SEGMENT_ID/contacts/add``
+
+**POST Parameters**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Type
+ - Description
+ * - ``ids``
+ - array
+ - Array of Contact IDs to add to the Segment
+
+**Response**
+
+``Expected Response Code: 200``
+
+.. code-block:: json
+
+ {
+ "success": 1,
+ "details": {
+ "1": {
+ "success": true
+ },
+ "2": {
+ "success": true
+ },
+ "3": {
+ "success": false
+ }
+ }
+ }
+
+.. vale off
+
+Remove Contact from Segment
+***************************
+
+.. vale on
+
+.. code-block:: php
+
+ removeContact($segmentId, $contactId);
+
+Remove a Contact from a Segment.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``POST /segments/SEGMENT_ID/contact/CONTACT_ID/remove``
+
+**Response**
+
+``Expected Response Code: 200``
+
+.. code-block:: json
+
+ {
+ "success": 1
+ }
+
+.. vale off
+
+Get User Segments
+*****************
+
+.. vale on
+
+.. code-block:: php
+
+ getUserSegments();
+
+Get a list of Segments available to the current user.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``GET /segments/lists``
+
+**Response**
+
+``Expected Response Code: 200``
+
+.. code-block:: json
+
+ {
+ "1": {
+ "id": 1,
+ "name": "VIP Customers",
+ "alias": "vip-customers"
+ },
+ "2": {
+ "id": 2,
+ "name": "Newsletter Subscribers",
+ "alias": "newsletter-subscribers"
+ }
+ }
+
+**Segment Properties**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Type
+ - Description
+ * - ``id``
+ - int
+ - ID of the Segment
+ * - ``name``
+ - string
+ - Name of the Segment
+ * - ``alias``
+ - string
+ - Alias of the Segment
+
+.. vale off
+
+Segment Filters
+***************
+
+.. vale on
+
+Segments use filters to define which Contacts should be included. Filters support various field types and operators.
+
+**Filter Structure**
+
+.. code-block:: json
+
+ {
+ "glue": "and",
+ "field": "email",
+ "object": "lead",
+ "type": "email",
+ "operator": "like",
+ "properties": {
+ "filter": "%@gmail.com"
+ }
+ }
+
+**Filter Properties**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Type
+ - Description
+ * - ``glue``
+ - string
+ - Logic operator to connect with previous filter: ``and`` or ``or``
+ * - ``field``
+ - string
+ - Contact field to filter on (e.g., ``email``, ``firstname``, ``points``)
+ * - ``object``
+ - string
+ - Object type, typically ``lead`` for Contact fields
+ * - ``type``
+ - string
+ - Field type (e.g., ``text``, ``number``, ``email``, ``date``, ``select``)
+ * - ``operator``
+ - string
+ - Comparison operator (e.g., ``=``, ``!=``, ``like``, ``!like``, ``gt``, ``gte``, ``lt``, ``lte``, ``in``, ``!in``)
+ * - ``properties``
+ - object
+ - Additional filter properties including the ``filter`` value
+
+**Common Operators by Field Type**
+
+Text Fields:
+- ``=`` (equals)
+- ``!=`` (not equals)
+- ``like`` (contains)
+- ``!like`` (does not contain)
+- ``empty`` (is empty)
+- ``!empty`` (is not empty)
+
+Number Fields:
+- ``=`` (equals)
+- ``!=`` (not equals)
+- ``gt`` (greater than)
+- ``gte`` (greater than or equal)
+- ``lt`` (less than)
+- ``lte`` (less than or equal)
+
+Date Fields:
+- ``=`` (equals)
+- ``!=`` (not equals)
+- ``gt`` (after)
+- ``gte`` (on or after)
+- ``lt`` (before)
+- ``lte`` (on or before)
+
+Select/Multi-Select Fields:
+- ``=`` (equals)
+- ``!=`` (not equals)
+- ``in`` (in list)
+- ``!in`` (not in list)
+
+**Example Filters**
+
+Email domain filter:
+
+.. code-block:: json
+
+ {
+ "glue": "and",
+ "field": "email",
+ "object": "lead",
+ "type": "email",
+ "operator": "like",
+ "properties": {
+ "filter": "%@company.com"
+ }
+ }
+
+Points range filter:
+
+.. code-block:: json
+
+ {
+ "glue": "and",
+ "field": "points",
+ "object": "lead",
+ "type": "number",
+ "operator": "gte",
+ "properties": {
+ "filter": "100"
+ }
+ }
+
+Date range filter:
+
+.. code-block:: json
+
+ {
+ "glue": "and",
+ "field": "date_added",
+ "object": "lead",
+ "type": "datetime",
+ "operator": "gte",
+ "properties": {
+ "filter": "2023-01-01 00:00:00"
+ }
+ }
\ No newline at end of file
diff --git a/docs/rest_api/users.rst b/docs/rest_api/users.rst
new file mode 100644
index 00000000..b7d3e8d2
--- /dev/null
+++ b/docs/rest_api/users.rst
@@ -0,0 +1,799 @@
+Users
+#####
+
+Use this endpoint to manipulate and obtain details on Mautic's Users.
+
+**Using Mautic's API Library**
+
+You can interact with this API through the :xref:`Mautic API Library` as follows, or use the various http endpoints as described in this document.
+
+.. code-block:: php
+
+ newAuth($settings);
+ $apiUrl = "https://example.com";
+ $api = new MauticApi();
+ $userApi = $api->newApi("users", $auth, $apiUrl);
+
+.. vale off
+
+Get User
+********
+
+.. vale on
+
+.. code-block:: php
+
+ get($id);
+
+Get an individual User by ID.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``GET /users/ID``
+
+**Response**
+
+``Expected Response Code: 200``
+
+.. code-block:: json
+
+ {
+ "user": {
+ "id": 1,
+ "dateAdded": "2024-01-15T10:30:00+00:00",
+ "dateModified": "2024-02-20T14:45:00+00:00",
+ "createdBy": 1,
+ "createdByUser": "System Administrator",
+ "modifiedBy": 1,
+ "modifiedByUser": "System Administrator",
+ "username": "admin",
+ "firstName": "John",
+ "lastName": "Doe",
+ "email": "john.doe@example.com",
+ "position": "System Administrator",
+ "timezone": "America/New_York",
+ "locale": "en_US",
+ "lastLogin": "2024-02-20T09:15:00+00:00",
+ "lastActive": "2024-02-20T14:45:00+00:00",
+ "role": {
+ "id": 1,
+ "name": "Administrator",
+ "description": "Full system access",
+ "isAdmin": true
+ },
+ "preferences": {
+ "theme": "default",
+ "language": "en_US"
+ },
+ "signature": "Best regards,
John Doe
"
+ }
+ }
+
+**User Properties**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Type
+ - Description
+ * - ``id``
+ - int
+ - ID of the User
+ * - ``username``
+ - string
+ - Username for login (unique)
+ * - ``firstName``
+ - string
+ - User's first name
+ * - ``lastName``
+ - string
+ - User's last name
+ * - ``email``
+ - string
+ - User's email address (unique)
+ * - ``position``
+ - string
+ - User's job position/title
+ * - ``timezone``
+ - string
+ - User's timezone preference
+ * - ``locale``
+ - string
+ - User's language/locale preference
+ * - ``lastLogin``
+ - datetime
+ - Timestamp of user's last login
+ * - ``lastActive``
+ - datetime
+ - Timestamp of user's last activity
+ * - ``role``
+ - object
+ - User's assigned role with permissions
+ * - ``preferences``
+ - array
+ - User's system preferences
+ * - ``signature``
+ - string
+ - User's email signature (HTML)
+ * - ``dateAdded``
+ - datetime
+ - Date/time when the User was created
+ * - ``dateModified``
+ - datetime
+ - Date/time when the User was last modified
+ * - ``createdBy``
+ - int
+ - ID of the User who created this User
+ * - ``modifiedBy``
+ - int
+ - ID of the User who last modified this User
+
+.. vale off
+
+List Users
+**********
+
+.. vale on
+
+.. code-block:: php
+
+ getList($searchFilter, $start, $limit, $orderBy, $orderByDir, $publishedOnly, $minimal);
+
+Get a list of Users.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``GET /users``
+
+**Query Parameters**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Description
+ * - ``search``
+ - String or search command to filter entities by.
+ * - ``start``
+ - Starting row for the entities returned. Defaults to 0.
+ * - ``limit``
+ - Limit number of entities to return. Defaults to the system configuration for pagination (30).
+ * - ``orderBy``
+ - Column to sort by. Can use any column listed in the response.
+ * - ``orderByDir``
+ - Sort direction: ``asc`` or ``desc``.
+ * - ``publishedOnly``
+ - Only return currently published entities.
+ * - ``minimal``
+ - Return only array of entities without additional lists in it.
+
+**Response**
+
+``Expected Response Code: 200``
+
+.. code-block:: json
+
+ {
+ "total": 2,
+ "users": [
+ {
+ "id": 1,
+ "username": "admin",
+ "firstName": "John",
+ "lastName": "Doe",
+ "email": "john.doe@example.com",
+ "position": "System Administrator",
+ "role": {
+ "id": 1,
+ "name": "Administrator"
+ }
+ },
+ {
+ "id": 2,
+ "username": "manager",
+ "firstName": "Jane",
+ "lastName": "Smith",
+ "email": "jane.smith@example.com",
+ "position": "Marketing Manager",
+ "role": {
+ "id": 2,
+ "name": "Manager"
+ }
+ }
+ ]
+ }
+
+.. vale off
+
+Create User
+***********
+
+.. vale on
+
+.. code-block:: php
+
+ 'newuser',
+ 'firstName' => 'John',
+ 'lastName' => 'Doe',
+ 'email' => 'john.doe@example.com',
+ 'plainPassword' => array(
+ 'password' => 'SecurePassword123!',
+ 'confirm' => 'SecurePassword123!'
+ ),
+ 'role' => 1,
+ 'position' => 'Marketing Specialist',
+ 'timezone' => 'America/New_York',
+ 'locale' => 'en_US'
+ );
+
+ $user = $userApi->create($data);
+
+Create a new User.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``POST /users/new``
+
+**Post Parameters**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Type
+ - Description
+ * - ``username``
+ - string
+ - **Required.** Username for login (must be unique)
+ * - ``firstName``
+ - string
+ - **Required.** User's first name
+ * - ``lastName``
+ - string
+ - **Required.** User's last name
+ * - ``email``
+ - string
+ - **Required.** User's email address (must be unique)
+ * - ``plainPassword``
+ - array
+ - **Required.** Array with 'password' and 'confirm' keys
+ * - ``role``
+ - int
+ - **Required.** ID of the role to assign to the user
+ * - ``position``
+ - string
+ - User's job position/title
+ * - ``timezone``
+ - string
+ - User's timezone preference
+ * - ``locale``
+ - string
+ - User's language/locale preference
+ * - ``signature``
+ - string
+ - User's email signature (HTML)
+
+**Response**
+
+``Expected Response Code: 201``
+
+.. code-block:: json
+
+ {
+ "user": {
+ "id": 3,
+ "username": "newuser",
+ "firstName": "John",
+ "lastName": "Doe",
+ "email": "john.doe@example.com",
+ "position": "Marketing Specialist",
+ "timezone": "America/New_York",
+ "locale": "en_US",
+ "role": {
+ "id": 1,
+ "name": "Administrator"
+ },
+ "dateAdded": "2024-02-20T15:30:00+00:00",
+ "createdBy": 1,
+ "createdByUser": "System Administrator"
+ }
+ }
+
+.. vale off
+
+Edit User
+*********
+
+.. vale on
+
+.. code-block:: php
+
+ 'John Updated',
+ 'position' => 'Senior Marketing Specialist',
+ 'timezone' => 'Europe/London'
+ );
+
+ // Create new a User if one isn't found with the given ID
+ $createIfNotFound = true;
+
+ $user = $userApi->edit($id, $data, $createIfNotFound);
+
+Edit a new User. Note that this supports PUT or PATCH depending on the desired behavior.
+
+- **PUT** creates a User if the given ID does not exist and clears all the User information, adds the information from the request. User username and password cannot be changed via PUT.
+- **PATCH** fails if the User with the given ID does not exist and updates the User field values with the values from the request. User username and password cannot be changed via PATCH.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+To edit a User and return a 404 if the User is not found:
+
+``PATCH /users/ID/edit``
+
+To edit a User and create a new one if the User is not found:
+
+``PUT /users/ID/edit``
+
+**Post Parameters**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Type
+ - Description
+ * - ``firstName``
+ - string
+ - User's first name
+ * - ``lastName``
+ - string
+ - User's last name
+ * - ``email``
+ - string
+ - User's email address (must be unique)
+ * - ``role``
+ - int
+ - ID of the role to assign to the user
+ * - ``position``
+ - string
+ - User's job position/title
+ * - ``timezone``
+ - string
+ - User's timezone preference
+ * - ``locale``
+ - string
+ - User's language/locale preference
+ * - ``signature``
+ - string
+ - User's email signature (HTML)
+
+**Response**
+
+If ``PUT``: ``Expected Response Code: 200`` (if the User was edited) or ``201`` (if the User was created).
+
+If ``PATCH``: ``Expected Response Code: 200``
+
+.. code-block:: json
+
+ {
+ "user": {
+ "id": 1,
+ "username": "admin",
+ "firstName": "John Updated",
+ "lastName": "Doe",
+ "email": "john.doe@example.com",
+ "position": "Senior Marketing Specialist",
+ "timezone": "Europe/London",
+ "role": {
+ "id": 1,
+ "name": "Administrator"
+ },
+ "dateModified": "2024-02-20T16:00:00+00:00",
+ "modifiedBy": 1,
+ "modifiedByUser": "System Administrator"
+ }
+ }
+
+.. vale off
+
+Delete User
+***********
+
+.. vale on
+
+.. code-block:: php
+
+ delete($id);
+
+Delete a User.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``DELETE /users/ID``
+
+**Response**
+
+``Expected Response Code: 200``
+
+.. code-block:: json
+
+ {
+ "user": {
+ "id": 3,
+ "username": "deleteduser",
+ "firstName": "John",
+ "lastName": "Doe",
+ "email": "john.doe@example.com"
+ }
+ }
+
+.. vale off
+
+Get Current User
+****************
+
+.. vale on
+
+.. code-block:: php
+
+ getSelf();
+
+Get the currently authenticated User's information.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``GET /users/self``
+
+**Response**
+
+``Expected Response Code: 200``
+
+.. code-block:: json
+
+ {
+ "id": 1,
+ "username": "admin",
+ "firstName": "John",
+ "lastName": "Doe",
+ "email": "john.doe@example.com",
+ "position": "System Administrator",
+ "timezone": "America/New_York",
+ "locale": "en_US",
+ "lastLogin": "2024-02-20T09:15:00+00:00",
+ "lastActive": "2024-02-20T14:45:00+00:00",
+ "role": {
+ "id": 1,
+ "name": "Administrator",
+ "isAdmin": true
+ }
+ }
+
+.. vale off
+
+Check User Permissions
+**********************
+
+.. vale on
+
+.. code-block:: php
+
+ checkPermission($userId, $permissions);
+
+Check if a User has specific permissions.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``POST /users/ID/permissioncheck``
+
+**Post Parameters**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Type
+ - Description
+ * - ``permissions``
+ - array
+ - **Required.** Array of permission strings to check
+
+**Response**
+
+``Expected Response Code: 200``
+
+.. code-block:: json
+
+ {
+ "user:users:view": true,
+ "user:users:edit": true
+ }
+
+.. vale off
+
+Get User Roles
+**************
+
+.. vale on
+
+.. code-block:: php
+
+ getRoles();
+
+Get a list of available User roles for user creation/editing.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``GET /users/list/roles``
+
+**Query Parameters**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Description
+ * - ``filter``
+ - String to filter roles by name
+ * - ``limit``
+ - Limit number of roles to return
+
+**Response**
+
+``Expected Response Code: 200``
+
+.. code-block:: json
+
+ [
+ {
+ "id": 1,
+ "name": "Administrator",
+ "description": "Full system access",
+ "isAdmin": true
+ },
+ {
+ "id": 2,
+ "name": "Manager",
+ "description": "Limited administrative access",
+ "isAdmin": false
+ },
+ {
+ "id": 3,
+ "name": "User",
+ "description": "Basic user access",
+ "isAdmin": false
+ }
+ ]
+
+.. vale off
+
+Batch Operations
+****************
+
+.. vale on
+
+**Batch Delete Users**
+
+.. code-block:: php
+
+ deleteBatch($userIds);
+
+Delete multiple Users in a single request.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``DELETE /users/batch/delete?ids=1,2,3``
+
+**Response**
+
+``Expected Response Code: 200``
+
+.. code-block:: json
+
+ {
+ "users": [
+ {
+ "id": 1,
+ "username": "user1"
+ },
+ {
+ "id": 2,
+ "username": "user2"
+ }
+ ]
+ }
+
+**Batch Edit Users**
+
+.. code-block:: php
+
+ 1,
+ 'position' => 'Senior Developer'
+ ),
+ array(
+ 'id' => 2,
+ 'timezone' => 'Europe/London'
+ )
+ );
+
+ $result = $userApi->editBatch($data);
+
+Edit multiple Users in a single request.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``PATCH /users/batch/edit``
+
+**Post Parameters**
+
+Send an array of User data with each item containing the User ID and the fields to update.
+
+**Response**
+
+``Expected Response Code: 200``
+
+.. code-block:: json
+
+ {
+ "users": [
+ {
+ "id": 1,
+ "username": "user1",
+ "position": "Senior Developer"
+ },
+ {
+ "id": 2,
+ "username": "user2",
+ "timezone": "Europe/London"
+ }
+ ]
+ }
+
+.. vale off
+
+Error Responses
+***************
+
+.. vale on
+
+**Common Error Responses**
+
+.. list-table::
+ :header-rows: 1
+
+ * - HTTP Code
+ - Error
+ - Description
+ * - ``400``
+ - Bad Request
+ - Invalid data provided (e.g., weak password, duplicate username/email)
+ * - ``401``
+ - Unauthorized
+ - Authentication required or weak password detected
+ * - ``403``
+ - Forbidden
+ - User doesn't have permission to perform this action
+ * - ``404``
+ - Not Found
+ - User with the specified ID was not found
+ * - ``422``
+ - Unprocessable Entity
+ - Validation errors in the submitted data
+
+**Password Policy Errors**
+
+When creating or updating users, password validation errors may occur:
+
+.. code-block:: json
+
+ {
+ "error": {
+ "code": 400,
+ "message": "Validation Failed",
+ "details": {
+ "plainPassword": [
+ "The password is too weak. It must be at least 6 characters long and contain a mix of letters, numbers, and special characters."
+ ]
+ }
+ }
+ }
+
+**Permission Errors**
+
+When checking permissions on non-existent users:
+
+.. code-block:: json
+
+ {
+ "error": {
+ "code": 404,
+ "message": "Item was not found."
+ }
+ }
+
+**Role Assignment Errors**
+
+When assigning invalid roles:
+
+.. code-block:: json
+
+ {
+ "error": {
+ "code": 400,
+ "message": "role: The selected choice is invalid."
+ }
+ }
\ No newline at end of file
diff --git a/docs/rest_api/webhooks.rst b/docs/rest_api/webhooks.rst
new file mode 100644
index 00000000..7e022af1
--- /dev/null
+++ b/docs/rest_api/webhooks.rst
@@ -0,0 +1,531 @@
+Webhooks
+########
+
+Use this endpoint to obtain details on Mautic's Webhooks.
+
+**Using Mautic's API Library**
+
+You can interact with this API through the :xref:`Mautic API Library` as follows, or use the various http endpoints as described in this document.
+
+.. code-block:: php
+
+ newAuth($settings);
+ $apiUrl = "https://example.com";
+ $api = new MauticApi();
+ $webhookApi = $api->newApi("hooks", $auth, $apiUrl);
+
+.. vale off
+
+Get Webhook
+***********
+
+.. vale on
+
+.. code-block:: php
+
+ get($id);
+
+Get an individual Webhook by ID.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``GET /hooks/ID``
+
+**Response**
+
+``Expected Response Code: 200``
+
+.. code-block:: json
+
+ {
+ "hook": {
+ "id": 31,
+ "name": "Lead Created Webhook",
+ "description": "Webhook to notify when a new lead is created",
+ "webhookUrl": "https://mysite.com/webhook/lead-created",
+ "secret": "mySecret",
+ "eventsOrderbyDir": null,
+ "isPublished": true,
+ "publishUp": null,
+ "publishDown": null,
+ "dateAdded": "2017-06-02T08:54:46+00:00",
+ "createdBy": 1,
+ "createdByUser": "John Doe",
+ "dateModified": "2017-06-02T09:28:56+00:00",
+ "modifiedBy": 1,
+ "modifiedByUser": "John Doe",
+ "category": {
+ "id": 1,
+ "title": "Important",
+ "alias": "important",
+ "description": null,
+ "color": null,
+ "bundle": "webhook"
+ },
+ "triggers": [
+ "mautic.lead_post_save_new",
+ "mautic.lead_post_save_update"
+ ]
+ }
+ }
+
+**Webhook Properties**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Type
+ - Description
+ * - ``id``
+ - int
+ - ID of the Webhook
+ * - ``name``
+ - string
+ - Title/name of the Webhook
+ * - ``description``
+ - string/null
+ - Description of the Webhook
+ * - ``webhookUrl``
+ - string
+ - The URL that will receive the webhook payload
+ * - ``secret``
+ - string/null
+ - Secret used for webhook authentication/verification
+ * - ``eventsOrderbyDir``
+ - string/null
+ - Order direction for events (ASC or DESC), null means use global default
+ * - ``isPublished``
+ - boolean
+ - Published state
+ * - ``publishUp``
+ - datetime/null
+ - Webhook publish date/time
+ * - ``publishDown``
+ - datetime/null
+ - Webhook unpublish date/time
+ * - ``dateAdded``
+ - datetime
+ - Webhook creation date/time
+ * - ``createdBy``
+ - int
+ - ID of the User that created the Webhook
+ * - ``createdByUser``
+ - string
+ - Name of the User that created the Webhook
+ * - ``dateModified``
+ - datetime/null
+ - Webhook modified date/time
+ * - ``modifiedBy``
+ - int
+ - ID of the User that last modified the Webhook
+ * - ``modifiedByUser``
+ - string
+ - Name of the User that last modified the Webhook
+ * - ``category``
+ - object/null
+ - Object with the Category details
+ * - ``triggers``
+ - array
+ - Array of event types that trigger this webhook
+
+.. vale off
+
+List Webhooks
+*************
+
+.. vale on
+
+.. code-block:: php
+
+ getList($searchFilter, $start, $limit, $orderBy, $orderByDir, $publishedOnly, $minimal);
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``GET /hooks``
+
+**Query Parameters**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Description
+ * - ``search``
+ - String or search command to filter entities by
+ * - ``start``
+ - Starting row for the entities returned, defaults to 0
+ * - ``limit``
+ - Limit number of entities to return, defaults to the system configuration for pagination - default of 30
+ * - ``orderBy``
+ - Column to sort by, can use any column listed in the response
+ * - ``orderByDir``
+ - Sort direction: ``asc`` or ``desc``
+ * - ``publishedOnly``
+ - Only return currently published entities
+ * - ``minimal``
+ - Return only array of entities without additional lists in it
+
+**Response**
+
+``Expected Response Code: 200``
+
+.. code-block:: json
+
+ {
+ "total": 4,
+ "hooks": [
+ {
+ "id": 31,
+ "name": "Lead Created Webhook",
+ "description": "Webhook to notify when a new lead is created",
+ "webhookUrl": "https://mysite.com/webhook/lead-created",
+ "secret": "mySecret",
+ "eventsOrderbyDir": null,
+ "isPublished": true,
+ "publishUp": null,
+ "publishDown": null,
+ "dateAdded": "2017-06-02T08:54:46+00:00",
+ "createdBy": 1,
+ "createdByUser": "John Doe",
+ "dateModified": "2017-06-02T09:28:56+00:00",
+ "modifiedBy": 1,
+ "modifiedByUser": "John Doe",
+ "category": null,
+ "triggers": [
+ "mautic.lead_post_save_new"
+ ]
+ }
+ ]
+ }
+
+**Properties**
+
+Same as `Get Webhook <#get-webhook>`_.
+
+.. vale off
+
+Create Webhook
+**************
+
+.. vale on
+
+.. code-block:: php
+
+ 'test',
+ 'description' => 'Created via API',
+ 'webhookUrl' => 'http://mysite.com/webhook/test',
+ 'secret' => 'mySecret',
+ 'triggers' => array(
+ 'mautic.lead_post_save_new',
+ 'mautic.lead_post_save_update'
+ )
+ );
+
+ $webhook = $webhookApi->create($data);
+
+Create a new Webhook.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``POST /hooks/new``
+
+**POST Parameters**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Type
+ - Description
+ * - ``name``
+ - string
+ - Webhook name
+ * - ``description``
+ - string
+ - Webhook description
+ * - ``webhookUrl``
+ - string
+ - URL to send webhook payload to
+ * - ``secret``
+ - string
+ - Secret for webhook authentication
+ * - ``triggers``
+ - array
+ - Array of event types that should trigger this webhook
+ * - ``isPublished``
+ - boolean
+ - Whether the webhook is published
+ * - ``publishUp``
+ - datetime
+ - Date/time when the webhook should be published
+ * - ``publishDown``
+ - datetime
+ - Date/time when the webhook should be unpublished
+ * - ``eventsOrderbyDir``
+ - string
+ - Order direction for events (ASC or DESC)
+ * - ``category``
+ - int
+ - ID of the category to assign the webhook to
+
+**Response**
+
+``Expected Response Code: 201``
+
+**Properties**
+
+Same as `Get Webhook <#get-webhook>`_.
+
+.. vale off
+
+Edit Webhook
+************
+
+.. vale on
+
+.. code-block:: php
+
+ 'test',
+ 'description' => 'Created via API',
+ 'webhookUrl' => 'http://mysite.com/webhook/test',
+ 'secret' => 'mySecret',
+ 'triggers' => array(
+ 'mautic.lead_post_save_new',
+ 'mautic.lead_post_save_update'
+ )
+ );
+
+ // Create new a Webhook if ID 1 isn't found?
+ $createIfNotFound = true;
+
+ $webhook = $webhookApi->edit($id, $data, $createIfNotFound);
+
+Edit a new Webhook. This supports PUT or PATCH depending on the desired behavior.
+
+**PUT** creates a Webhook if the given ID doesn't exist and clears all the Webhook information, adding the information from the request.
+**PATCH** fails if the Webhook with the given ID doesn't exist and updates the Webhook field values with the values from the request.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+To edit a Webhook and return a 404 if the Webhook isn't found:
+
+``PATCH /hooks/ID/edit``
+
+To edit a Webhook and create a new one if the Webhook isn't found:
+
+``PUT /hooks/ID/edit``
+
+**POST Parameters**
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Type
+ - Description
+ * - ``name``
+ - string
+ - Webhook name
+ * - ``description``
+ - string
+ - Webhook description
+ * - ``webhookUrl``
+ - string
+ - URL to send webhook payload to
+ * - ``secret``
+ - string
+ - Secret for webhook authentication
+ * - ``triggers``
+ - array
+ - Array of event types that should trigger this webhook
+ * - ``isPublished``
+ - boolean
+ - Whether the webhook is published
+ * - ``publishUp``
+ - datetime
+ - Date/time when the webhook should be published
+ * - ``publishDown``
+ - datetime
+ - Date/time when the webhook should be unpublished
+ * - ``eventsOrderbyDir``
+ - string
+ - Order direction for events (ASC or DESC)
+ * - ``category``
+ - int
+ - ID of the category to assign the webhook to
+
+**Response**
+
+If ``PUT``\ , the expected response code if editing the Webhook is ``200`` or ``201`` if created.
+
+If using ``PATCH``\ , the expected response code is ``200``.
+
+**Properties**
+
+Same as `Get Webhook <#get-webhook>`_.
+
+.. vale off
+
+Delete Webhook
+**************
+
+.. vale on
+
+.. code-block:: php
+
+ delete($id);
+
+Delete a Webhook.
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``DELETE /hooks/ID/delete``
+
+**Response**
+
+``Expected Response Code: 200``
+
+**Properties**
+
+Same as `Get Webhook <#get-webhook>`_.
+
+.. vale off
+
+Get Webhook Triggers
+********************
+
+.. vale on
+
+.. code-block:: php
+
+ getTriggers();
+
+Get a list of available webhook triggers (event types).
+
+.. vale off
+
+**HTTP Request**
+
+.. vale on
+
+``GET /hooks/triggers``
+
+**Response**
+
+``Expected Response Code: 200``
+
+.. code-block:: json
+
+ {
+ "triggers": {
+ "mautic.lead_post_save_new": {
+ "label": "Contact created",
+ "description": "Triggered when a new contact is created"
+ },
+ "mautic.lead_post_save_update": {
+ "label": "Contact updated",
+ "description": "Triggered when an existing contact is updated"
+ },
+ "mautic.lead_post_delete": {
+ "label": "Contact deleted",
+ "description": "Triggered when a contact is deleted"
+ },
+ "mautic.lead_points_change": {
+ "label": "Contact's points changed",
+ "description": "Triggered when a contact's point total changes"
+ },
+ "mautic.lead_channel_subscription_changed": {
+ "label": "Contact's channel subscription changed",
+ "description": "Triggered when a contact's channel subscription changes"
+ },
+ "mautic.lead_company_change": {
+ "label": "Contact's company changed",
+ "description": "Triggered when a contact's company association changes"
+ },
+ "mautic.company_post_save": {
+ "label": "Company created/updated",
+ "description": "Triggered when a company is created or updated"
+ },
+ "mautic.company_post_delete": {
+ "label": "Company deleted",
+ "description": "Triggered when a company is deleted"
+ },
+ "mautic.form_on_submit": {
+ "label": "Form submitted",
+ "description": "Triggered when a form is submitted"
+ },
+ "mautic.page_on_hit": {
+ "label": "Page hit",
+ "description": "Triggered when a page is hit/visited"
+ },
+ "mautic.email_on_send": {
+ "label": "Email sent",
+ "description": "Triggered when an email is sent"
+ },
+ "mautic.email_on_open": {
+ "label": "Email opened",
+ "description": "Triggered when an email is opened"
+ }
+ }
+ }
+
+**Response Properties**
+
+The response contains a ``triggers`` object where each key is a trigger event type, and the value contains:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Type
+ - Description
+ * - ``label``
+ - string
+ - Human-readable label for the trigger
+ * - ``description``
+ - string
+ - Description of when this trigger fires
\ No newline at end of file