> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heysaturn.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Advisor Endpoints

The advisor endpoints allow you to create advisors and assign them to accounts or clients in Saturn's platform.

## Full Endpoint URL

```
https://secure.heysaturn.com/api/external/v1/advisor/
```

## Create Advisor

### `POST /create/`

This endpoint creates a new advisor in the Saturn platform. Create an advisor by providing their details, including the CRM source and a unique advisor ID from that CRM.

### Mandatory Fields

| Field        | Type   | Description                                                 |
| ------------ | ------ | ----------------------------------------------------------- |
| `first_name` | string | First name of the advisor.                                  |
| `last_name`  | string | Last name of the advisor.                                   |
| `email`      | string | Email address of the advisor.                               |
| `crm`        | string | CRM source (e.g., `curo`, `xplan`, `plannr`, `intelliflo`). |
| `id`         | string | Unique advisor UUID from the CRM source.                    |

### Request Example

```json theme={null}
{
    “first_name”: “James”,
    “last_name”: “Parker”,
    “email”: “james@parker-advisors.com”,
    “crm”: “curo”,
    “id”: “sample-advisor-curo-id”
}
```

### Response Example `Status Code: 201`

```json theme={null}
{
    “message”: “Advisor created successfully”,
    “advisor”: {
        “first_name”: “James”,
        “last_name”: “Parker”,
        “role”: “Advisor”,
        “email”: null,
        “id”: 22
    }
}
```

### Error Responses

* **409 Conflict**: Advisor with the same `id` already exists.

```json theme={null}
{
    “error”: “Advisor already exists”,
    “details”: “Advisor with ID ‘sample-advisor-curo-id’ already exists.”
}
```

* **400 Bad Request**: Missing mandatory fields

```json theme={null}
{
    “error”: “Validation error”,
    “details”: {
        “first_name”: [“This field is required.”],
        “last_name”: [“This field is required.”],
        “crm”: [“This field is required.”]
    }
}
```

## Assign Advisor

### `POST /assign/`

This endpoint assigns an advisor to an account or clients in the Saturn platform. The assignment links the advisor to specific accounts or clients based on their CRM IDs.

### Mandatory Fields

| Field        | Type   | Description                                                 |
| ------------ | ------ | ----------------------------------------------------------- |
| `crm`        | string | CRM source (e.g., `curo`, `xplan`, `plannr`, `intelliflo`). |
| `advisor_id` | string | Last name of the advisor.                                   |
| `assign_to`  | array  | List of objects specifying the type (account) and the ID.   |

### Request Example

```json theme={null}
{
    "crm": "curo",
    "advisor_id": "sample-advisor-curo-id",
    "assign_to": [
        {"type": "account", "id": "sample-account-uuid-curo"}
    ]
}
```

### Response Example `Status Code: 201`

```json theme={null}
{
    "message": "Advisor sample-advisor-curo-id assigned successfully.",
    "assigned_clients": [
        2405,
        2403,
        2404
    ]
}
```

### Error Responses

* **404 Not Found**: Advisor not found.

```json theme={null}
{
    “error”: “Advisor already exists”,
    “details”: “Advisor with ID ‘sample-advisor-curo-id’ already exists.”
}
```

* **400 Bad Request**: Missing mandatory fields

```json theme={null}
{
    "error": "Validation error",
    "details": {
        "advisor_id": ["This field is required."],
        "assign_to": ["This field is required."]
    }
}
```

## Retrieve Advisor

### `GET /`

This endpoint retrieves an advisor by either their email address or CRM-specific ID.

### Query Parameters

| Parameter | Type   | Required | Description                                                                                 |
| --------- | ------ | -------- | ------------------------------------------------------------------------------------------- |
| `email`   | string | No\*     | Email address of the advisor to retrieve. Cannot be used together with `id` parameter.      |
| `id`      | string | No\*     | CRM-specific ID of the advisor to retrieve. Cannot be used together with `email` parameter. |

\*At least one of `email` or `id` must be provided.

### Request Example with Email

```http theme={null}
GET /api/external/v1/advisor/?email=james@parker-advisors.com
X-CRM: curo
Authorization: Api-Key <your_api_key>
```

### Request Example with ID

```http theme={null}
GET /api/external/v1/advisor/?id=sample-advisor-curo-id
X-CRM: curo
Authorization: Api-Key <your_api_key>
```

### Response Example `Status Code: 200`

```json theme={null}
{
    "advisor": {
        "id": "22",
        "first_name": "James",
        "last_name": "Parker",
        "role": "Advisor",
        "email": "james@parker-advisors.com",
        "curo_advisor_id": "sample-advisor-curo-id"
    }
}
```

### Error Responses

* **400 Bad Request**: Missing CRM header or both email and id parameters

```json theme={null}
{
    "error": "Either email or id must be provided"
}
```

* **404 Not Found**: Advisor not found with the provided email or ID

```json theme={null}
{
    "error": "Advisor with email james@parker-advisors.com not found."
}
```

```json theme={null}
{
    "error": "Advisor from curo with ID sample-advisor-curo-id not found."
}
```