Skip to main content
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

FieldTypeDescription
first_namestringFirst name of the advisor.
last_namestringLast name of the advisor.
emailstringEmail address of the advisor.
crmstringCRM source (e.g., curo, xplan, plannr, intelliflo).
idstringUnique 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

FieldTypeDescription
crmstringCRM source (e.g., curo, xplan, plannr, intelliflo).
advisor_idstringLast name of the advisor.
assign_toarrayList 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

ParameterTypeRequiredDescription
emailstringNo*Email address of the advisor to retrieve. Cannot be used together with id parameter.
idstringNo*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."
}