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

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

Response Example `Status Code: 201`

{
    “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.

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

400 Bad Request: Missing mandatory fields

{
    “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

{
    "crm": "curo",
    "advisor_id": "sample-advisor-curo-id",
    "assign_to": [
        {"type": "account", "id": "sample-account-uuid-curo"}
    ]
}

Response Example `Status Code: 201`

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

Error Responses

404 Not Found: Advisor not found.

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

400 Bad Request: Missing mandatory fields

{
    "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

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

Request Example with ID

GET /api/external/v1/advisor/?id=sample-advisor-curo-id
X-CRM: curo
Authorization: Api-Key <your_api_key>

Response Example `Status Code: 200`

{
    "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

{
    "error": "Either email or id must be provided"
}

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

{
    "error": "Advisor with email james@parker-advisors.com not found."
}

{
    "error": "Advisor from curo with ID sample-advisor-curo-id not found."
}

Getting Started

OpenAPI

API Reference

Advisor Endpoints

Full Endpoint URL

Create Advisor

`POST /create/`

Mandatory Fields

Request Example

Response Example `Status Code: 201`

Error Responses

Assign Advisor

`POST /assign/`

Mandatory Fields

Request Example

Response Example `Status Code: 201`

Error Responses

Retrieve Advisor

`GET /`

Query Parameters

Request Example with Email

Request Example with ID

Response Example `Status Code: 200`

Error Responses

​Full Endpoint URL

​Create Advisor

​POST /create/

​Mandatory Fields

​Request Example

​Response Example Status Code: 201

​Error Responses

​Assign Advisor

​POST /assign/

​Mandatory Fields

​Request Example

​Response Example Status Code: 201

​Error Responses

​Retrieve Advisor

​GET /

​Query Parameters

​Request Example with Email

​Request Example with ID

​Response Example Status Code: 200

​Error Responses

Full Endpoint URL

Create Advisor

`POST /create/`

Mandatory Fields

Request Example

Response Example `Status Code: 201`

Error Responses

Assign Advisor

`POST /assign/`

Mandatory Fields

Request Example

Response Example `Status Code: 201`

Error Responses

Retrieve Advisor

`GET /`

Query Parameters

Request Example with Email

Request Example with ID

Response Example `Status Code: 200`

Error Responses