Creates a new referral to share client data with a connected firm. Run in API Explorer

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL

https://apidocs.plannrcrm.com/mcp

Standard setup for AI tools providing an mcp.json file

mcp.json 
{
  "PlannrCRM MCP server": {
    "url": "https://apidocs.plannrcrm.com/mcp"
  }
}
Close
POST /api/v1/referrals
Personal access token & O auth2

The connection must be accepted before referrals can be sent.

Headers

  • X-PLANNR-ACCOUNT-UUID string
application/json

Body

  • connection_uuid string Required

    The UUID of an accepted referral connection.

  • client_uuids array Required

    Array of client account UUIDs to refer.

  • advice_type string Required

    The type of advice being referred. Options: investments, protection, mortgages, estate_planning, other, pensions and tax

    Value Description
    investments Investments
    protection Protection
    mortgages Mortgages
    estate_planning Estate Planning
    other Other
    pensions Pensions
    tax Tax

    Values are investments, protection, mortgages, estate_planning, other, pensions, or tax.

  • duration_months integer

    Duration in months for the referral. Options: 1, 2, 3, 6. Null for lifetime.

  • shared_data array Required

    Data categories to share. Options: basic_details, contact_details, income, expenditure, dependants, investments_and_plans, pensions, liabilities, protection, cash_accounts, goals and notes

  • sla_deadline string(date)

    SLA deadline for the recipient to respond.

  • note string

    Additional notes about the referral.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • uuid string

      The UUID of the resource.

    • direction string

      The direction of the referral relative to the current firm. Possible values: sent, received

    • connection object

      The referral connection this referral belongs to

      Hide connection attribute Show connection attribute object
      • uuid string
    • clients array[object]

      The original client accounts being referred

      Hide clients attributes Show clients attributes object
      • uuid string
      • name string
    • cloned_clients array[object]

      The cloned client accounts in the recipient firm

      Hide cloned_clients attributes Show cloned_clients attributes object
      • uuid string
      • name string
    • advice_type string

      The type of advice. Possible values: investments, protection, mortgages, estate_planning, other, pensions and tax

    • duration_months integer

      Duration in months (1, 2, 3, or 6). Null for lifetime.

    • shared_data array[string]

      Data categories being shared. Possible values: basic_details, contact_details, income, expenditure, dependants, investments_and_plans, pensions, liabilities, protection, cash_accounts, goals and notes

    • note string

      Additional notes about the referral

    • sla_deadline string

      SLA deadline for recipient to respond

    • status string

      The status of the referral. Possible values: pending, accepted, rejected and expired

    • rejection_reason string

      Reason for rejection (only present if rejected)

    • sender_firm object

      The firm that sent the referral

      Hide sender_firm attributes Show sender_firm attributes object
      • uuid string
      • name string
    • recipient_firm object

      The firm that received the referral

      Hide recipient_firm attributes Show recipient_firm attributes object
      • uuid string
      • name string
    • sender_account object

      The account that sent the referral

      Hide sender_account attributes Show sender_account attributes object
      • uuid string
      • created_at string
      • updated_at string
      • type string
      • role string
      • first_name string
      • last_name string
      • name string
      • email string
      • photo_url string
      • external_references object
        Hide external_references attributes Show external_references attributes object
        • uuid

          The UUID of the resource.

        • created_at

          The timestamp of when the resource was created.

        • updated_at

          The timestamp of when the resource was updated.

        • third_party

          The third party provider with the reference.

        • reference

          The third party reference.

    • recipient_account object

      The account that received the referral

      Hide recipient_account attributes Show recipient_account attributes object
      • uuid string
      • created_at string
      • updated_at string
      • type string
      • role string
      • first_name string
      • last_name string
      • name string
      • email string
      • photo_url string
      • external_references object
        Hide external_references attributes Show external_references attributes object
        • uuid

          The UUID of the resource.

        • created_at

          The timestamp of when the resource was created.

        • updated_at

          The timestamp of when the resource was updated.

        • third_party

          The third party provider with the reference.

        • reference

          The third party reference.

    • created_at string

      The timestamp of when the resource was created.

    • updated_at string

      The timestamp of when the resource was updated.

    • expires_at string

      The datetime when the referral expires
  • 422 application/json

    Validation error

    Hide response attributes Show response attributes object
    • message string Required

      A human-readable description of the error.

    • errors object

      Validation messages keyed by the field that failed.

      Hide errors attribute Show errors attribute object
      • * array[string] Additional properties
POST /api/v1/referrals 
curl \
 --request POST 'https://api.plannrcrm.com/api/v1/referrals' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --header "X-PLANNR-ACCOUNT-UUID: {YOUR_PLANNR_ACCOUNT_UUID}" \
 --data '{
  "connection_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "client_uuids": [
    "550e8400-e29b-41d4-a716-446655440001",
    "550e8400-e29b-41d4-a716-446655440002"
  ],
  "advice_type": "investments",
  "duration_months": 3,
  "shared_data": [
    "basic_details",
    "contact_details",
    "notes"
  ],
  "sla_deadline": "2026-02-28",
  "note": "Client needs help with retirement planning."
}'
Request examples 
# Headers
X-PLANNR-ACCOUNT-UUID: {YOUR_PLANNR_ACCOUNT_UUID}

# Payload
{
  "connection_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "client_uuids": [
    "550e8400-e29b-41d4-a716-446655440001",
    "550e8400-e29b-41d4-a716-446655440002"
  ],
  "advice_type": "investments",
  "duration_months": 3,
  "shared_data": [
    "basic_details",
    "contact_details",
    "notes"
  ],
  "sla_deadline": "2026-02-28",
  "note": "Client needs help with retirement planning."
}
Response examples (200) 
{
  "uuid": "35a41770-8fa7-4933-b145-2b2d41b37676",
  "direction": "sent",
  "connection": {
    "uuid": "abc-123"
  },
  "clients": [
    {
      "uuid": "client-uuid-1",
      "name": "John Doe"
    }
  ],
  "cloned_clients": [
    {
      "uuid": "cloned-uuid-1",
      "name": "John Doe"
    }
  ],
  "advice_type": "investments",
  "duration_months": 3,
  "shared_data": [
    "basic_details",
    "contact_details"
  ],
  "note": "Client needs help with retirement planning.",
  "sla_deadline": "2026-02-28",
  "status": "pending",
  "rejection_reason": "Unable to take on new clients.",
  "sender_firm": {
    "uuid": "abc-123",
    "name": "Sender Firm Name"
  },
  "recipient_firm": {
    "uuid": "def-456",
    "name": "Recipient Firm Name"
  },
  "sender_account": {
    "uuid": "5a9bd996-aca4-4f19-9427-2c16a98a73d5",
    "created_at": "2026-10-09T13:38:24+01:00",
    "updated_at": "2026-10-09T13:38:24+01:00",
    "type": "client",
    "role": "client",
    "first_name": "Gareth",
    "last_name": "Thompson",
    "name": "Gareth Thompson",
    "email": "gareth@codepotato.co.uk",
    "photo_url": "https://eu.ui-avatars.com/api/?name=Gareth+Thompson",
    "external_references": {
      "uuid": "8293507c-76c3-4d3a-9ad1-991f2d2f4031",
      "created_at": "2026-10-09T13:38:28+01:00",
      "updated_at": "2026-10-09T13:38:28+01:00",
      "third_party": "nucleus",
      "reference": "AB123456"
    }
  },
  "recipient_account": {
    "uuid": "64f4da7a-ae1b-4aa9-a3d2-81561d58fcb7",
    "created_at": "2026-10-09T13:38:24+01:00",
    "updated_at": "2026-10-09T13:38:24+01:00",
    "type": "client",
    "role": "client",
    "first_name": "Gareth",
    "last_name": "Thompson",
    "name": "Gareth Thompson",
    "email": "gareth@codepotato.co.uk",
    "photo_url": "https://eu.ui-avatars.com/api/?name=Gareth+Thompson",
    "external_references": {
      "uuid": "8293507c-76c3-4d3a-9ad1-991f2d2f4031",
      "created_at": "2026-10-09T13:38:28+01:00",
      "updated_at": "2026-10-09T13:38:28+01:00",
      "third_party": "nucleus",
      "reference": "AB123456"
    }
  },
  "created_at": "2026-10-09T13:38:24+01:00",
  "updated_at": "2026-10-09T13:38:24+01:00",
  "expires_at": "2027-01-09T13:38:24+00:00"
}
Response examples (422) 
{
  "message": "The given data was invalid.",
  "errors": {
    "field": [
      "The field is invalid."
    ]
  }
}