### Step-by-Step Example: Course Enrolled Trigger

Source: https://fluentcrm.com/docs/custom-automation-trigger

A practical example demonstrating how to create a custom trigger that fires when a user enrolls in a course.

```APIDOC
## Example: Course Enrolled Trigger

### 1. Constructor
Initialize trigger properties and call the parent constructor.

```php
<?php

namespace YourPlugin\Automation;

use FluentCrm\App\Services\Funnel\BaseTrigger;

class CourseEnrolledTrigger extends BaseTrigger
{
    public function __construct()
    {
        $this->triggerName = 'your_plugin_course_enrolled';
        $this->priority = 20;
        $this->actionArgNum = 2;
        parent::__construct();
    }
}
```

### 2. `getTrigger()` Method
Define metadata for the trigger's appearance in the UI.

```php
public function getTrigger()
{
    return [
        'category'    => __('My Plugin', 'your-plugin'),
        'label'       => __('User Enrolled in Course', 'your-plugin'),
        'description' => __('This automation will start when a student enrolls in a course', 'your-plugin'),
        'icon'        => 'fc-icon-wp_new_user_signup', // Use FluentCRM icon classes
    ];
}
```

### 3. `getFunnelSettingsDefaults()` and `getSettingsFields()` Methods
Configure user-configurable settings for the trigger.

```php
public function getFunnelSettingsDefaults()
{
    return [
        'subscription_status' => 'subscribed',
    ];
}

public function getSettingsFields($funnel)
{
    return [
        'title'     => __('User Enrolled in Course', 'your-plugin'),
        'sub_title' => __('This automation will start when a student enrolls in a course', 'your-plugin'),
        'fields'    => [
            'subscription_status' => [
                'type'        => 'option_selectors',
                'option_key'  => 'editable_statuses',
                'is_multiple' => false,
                'label'       => __('Subscription Status', 'your-plugin'),
                'placeholder' => __('Select Status', 'your-plugin'),
            ],
        ],
    ];
}
```
```

--------------------------------

### Testing API Endpoints

Source: https://fluentcrm.com/docs/global-rest-api-settings

Guides on how to test FluentCRM REST API endpoints using Postman, including authentication and example requests.

```APIDOC
## Testing API

### Description
This section provides guidance on testing the FluentCRM REST API using Postman, covering authentication and demonstrating how to list and add contacts.

### Authentication
1. Open Postman.
2. Set the authorization type to **Basic Auth**.
3. Use the generated **API Username** and **API Password** for authentication.

### API Base URL
`https://yourdomain.com/wp-json/fluent-crm/v2`

### Endpoint: List All Contacts

#### Method
GET

#### Endpoint
`/subscribers`

#### Description
Retrieves a list of all contacts within FluentCRM.

#### Request Example
```
GET https://yourdomain.com/wp-json/fluent-crm/v2/subscribers
```

#### Response Example (Success - 200 OK)
```json
{
  "data": [
    {
      "id": 1,
      "email": "test@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "status": "subscribed",
      "created_at": "2023-10-27T10:00:00+00:00"
    }
    // ... more contacts
  ],
  "meta": {
    "current_page": 1,
    "per_page": 15,
    "total_items": 100
  }
}
```

### Endpoint: Add a New Contact

#### Method
POST

#### Endpoint
`/subscribers`

#### Description
Adds a new contact to FluentCRM with the provided details.

#### Query Parameters
- **first_name** (string) - Optional - The first name of the contact.
- **last_name** (string) - Optional - The last name of the contact.
- **email** (string) - Required - The email address of the contact.
- **status** (string) - Optional - The status of the contact (e.g., 'subscribed', 'unsubscribed').

#### Request Example
```
https://yourdomain.com/wp-json/fluent-crm/v2/subscribers?first_name=Ibrahim&last_name=Sharif&email=ibrahim@gmail.com&status=subscribed
```

#### Response Example (Success - 200 OK)
```json
{
  "message": "Subscriber successfully added."
}
```

### Note on Updating Tags
When updating tags for an existing contact, use the `attach_tags` parameter instead of `tags`.
```

--------------------------------

### Access Lists Model and Query Methods

Source: https://fluentcrm.com/docs/lists-and-tags-php-api

Demonstrates how to retrieve the underlying Eloquent model for advanced queries and use proxied methods like all(), find(), and paginate() for standard list retrieval.

```php
$listApi = FluentCrmApi('lists');

// Get all lists
$allLists = $listApi->all();

// Find by ID
$list = $listApi->find(5);

// Find multiple
$lists = $listApi->find([1, 2, 3]);

// Custom query via getInstance()
$recentLists = $listApi->getInstance()
    ->orderBy('created_at', 'desc')
    ->get();
```

--------------------------------

### WP-CLI: License Management

Source: https://fluentcrm.com/docs/wp-cli-commands

Commands to activate and check the status of FluentCRM Pro licenses.

```APIDOC
## WP-CLI: License Management

### Description
Manage FluentCRM Pro license keys via CLI.

### Methods
- `activate_license`: Activates a FluentCRM Pro license key.
- `license_status`: Displays current license status and expiration date.

### Usage Examples
- Activate: `wp fluent_crm activate_license --key=<license_key>`
- Status: `wp fluent_crm license_status`
```

--------------------------------

### Get Contact Custom Fields

Source: https://fluentcrm.com/docs/contact-php-api

Retrieve custom field definitions for contacts. You can filter by field types or get a simplified output format.

```php
$fields = $contactApi->getCustomFields($types = [], $byOptions = false);
```

--------------------------------

### Triggering and Registering Benchmarks

Source: https://fluentcrm.com/docs/custom-automation-benchmark-goal

Instructions on how to fire the custom action and register the benchmark class with FluentCRM.

```APIDOC
## Triggering the Benchmark

### Description
Fire the custom action in your plugin when the specific tag event occurs.

### Code Example
```php
do_action('your_plugin_tag_applied', $tagIds, $subscriber);
```

## Registering the Benchmark

### Description
Register your custom benchmark class during the `fluent_crm/after_init` hook.

### Code Example
```php
add_action('fluent_crm/after_init', function () {
    new YourPlugin\Automation\TagAppliedBenchmark();
});
```
```

--------------------------------

### GET /subscribers

Source: https://fluentcrm.com/docs/global-rest-api-settings?replytocom=5219

Retrieves a list of all subscribers (contacts) from the FluentCRM system.

```APIDOC
## GET /subscribers

### Description
Fetches a list of all contacts currently stored in FluentCRM.

### Method
GET

### Endpoint
https://yourdomain.com/wp-json/fluent-crm/v2/subscribers

### Parameters
None

### Request Example
GET /wp-json/fluent-crm/v2/subscribers

### Response
#### Success Response (200)
- **data** (array) - List of subscriber objects.

#### Response Example
{
  "subscribers": [
    {
      "id": 1,
      "first_name": "John",
      "email": "john@example.com"
    }
  ]
}
```

--------------------------------

### Get Unsubscribe Reason and Date

Source: https://fluentcrm.com/docs/contact-php-api

Retrieve the reason and date if a subscriber has unsubscribed.

```php
$reason = $subscriber->unsubscribeReason(); // string
$date = $subscriber->unsubscribeReasonDate(); // string or empty
```

--------------------------------

### Incoming Webhook Configuration

Source: https://fluentcrm.com/docs/global-incoming-webhooks?replytocom=4810

This section describes how to create and configure an incoming webhook in FluentCRM.

```APIDOC
## Incoming Webhook Configuration

### Description
Configure incoming webhooks to receive data from external services and automatically subscribe users to lists and tags within FluentCRM.

### Method
POST

### Endpoint
/api/webhooks/incoming

### Parameters
#### Query Parameters
- **name** (string) - Required - A name to identify the webhook.
- **list_id** (integer) - Required - The ID of the list to subscribe users to.
- **tag_id** (integer) - Required - The ID of the tag to apply to users.
- **status** (string) - Optional - The subscription status for the user (e.g., 'subscribed', 'unsubscribed'). Defaults to 'subscribed'.

#### Request Body
Key-value pairs representing contact fields to be sent. Standard fields include:
- **email** (string) - Required - The email address of the contact.
- **first_name** (string) - Optional - The first name of the contact.
- **last_name** (string) - Optional - The last name of the contact.

Custom contact fields can also be used by mapping their respective keys.

### Request Example
```json
{
  "name": "My External Service Webhook",
  "list_id": 1,
  "tag_id": 5,
  "status": "subscribed"
}
```

### Response
#### Success Response (200)
- **message** (string) - A success message indicating the webhook was created.
- **webhook_url** (string) - The URL to send incoming data to.
- **keys** (object) - An object containing the available keys for mapping contact fields.

#### Response Example
```json
{
  "message": "Webhook created successfully.",
  "webhook_url": "https://yourdomain.com/fluentcrm/webhooks/your-unique-id",
  "keys": {
    "email": "email",
    "first_name": "first_name",
    "last_name": "last_name",
    "custom_field_1": "cf_12345"
  }
}
```
```

--------------------------------

### Get Contact by WordPress User ID

Source: https://fluentcrm.com/docs/contact-php-api

Finds a contact strictly by their WordPress user ID.

```APIDOC
## getContactByUserId()

Find a contact by WordPress user ID only (no email fallback).

php
```php
$contact = $contactApi->getContactByUserId($userId);
```

**Parameters**
  * `$userId` `int` — WordPress user ID

**Returns** `false` | Subscriber
```