Creates a new referral connection request to another adviser using their referral code. 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/referral-connections
Personal access token & O auth2

An email notification will be sent to the recipient with accept/deny links.

Headers

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

Body Required

  • adviser_key string Required

    The 8-character referral code of the adviser you want to connect with.

Responses

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

      The UUID of the resource.

    • direction string

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

    • status string

      The status of the referral connection. Possible values: pending, accepted, denied, expired

    • sender_firm object

      The firm that sent the referral connection request

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

      The firm that received the referral connection request

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

      The account that sent the referral connection request

      Hide sender_account attributes Show sender_account attributes object
      • uuid object
        Hide uuid attributes Show uuid attributes object
        • example string
        • description string
        • collection boolean
      • created_at object
        Hide created_at attributes Show created_at attributes object
        • example string
        • description string
        • collection boolean
      • updated_at object
        Hide updated_at attributes Show updated_at attributes object
        • example string
        • description string
        • collection boolean
      • type object
        Hide type attributes Show type attributes object
        • example string
        • description string
        • collection boolean
      • role object
        Hide role attributes Show role attributes object
        • example string
        • description string
        • collection boolean
      • first_name object
        Hide first_name attributes Show first_name attributes object
        • example string
        • description string
        • collection boolean
      • last_name object
        Hide last_name attributes Show last_name attributes object
        • example string
        • description string
        • collection boolean
      • name object
        Hide name attributes Show name attributes object
        • example string
        • description string
        • collection boolean
      • email object
        Hide email attributes Show email attributes object
        • example string
        • description string
        • collection boolean
      • photo_url object
        Hide photo_url attributes Show photo_url attributes object
        • example string
        • description string
        • collection boolean
      • external_references object
        Hide external_references attributes Show external_references attributes object
        • example string
        • description string
        • collection boolean
    • recipient_account object

      The account that received the referral connection request

      Hide recipient_account attributes Show recipient_account attributes object
      • uuid object
        Hide uuid attributes Show uuid attributes object
        • example string
        • description string
        • collection boolean
      • created_at object
        Hide created_at attributes Show created_at attributes object
        • example string
        • description string
        • collection boolean
      • updated_at object
        Hide updated_at attributes Show updated_at attributes object
        • example string
        • description string
        • collection boolean
      • type object
        Hide type attributes Show type attributes object
        • example string
        • description string
        • collection boolean
      • role object
        Hide role attributes Show role attributes object
        • example string
        • description string
        • collection boolean
      • first_name object
        Hide first_name attributes Show first_name attributes object
        • example string
        • description string
        • collection boolean
      • last_name object
        Hide last_name attributes Show last_name attributes object
        • example string
        • description string
        • collection boolean
      • name object
        Hide name attributes Show name attributes object
        • example string
        • description string
        • collection boolean
      • email object
        Hide email attributes Show email attributes object
        • example string
        • description string
        • collection boolean
      • photo_url object
        Hide photo_url attributes Show photo_url attributes object
        • example string
        • description string
        • collection boolean
      • external_references object
        Hide external_references attributes Show external_references attributes object
        • example string
        • description string
        • collection boolean
    • 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 connection request expires
POST /api/v1/referral-connections 
curl \
 --request POST 'https://api.plannrcrm.com/api/v1/referral-connections' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --header "X-PLANNR-ACCOUNT-UUID: {YOUR_PLANNR_ACCOUNT_UUID}" \
 --data '{"adviser_key":"ABC12345"}'
Request examples 
# Headers
X-PLANNR-ACCOUNT-UUID: {YOUR_PLANNR_ACCOUNT_UUID}

# Payload
{
  "adviser_key": "ABC12345"
}
Response examples (200) 
{
  "uuid": "b7d472bf-7529-4eb9-9afd-f7e2f81eb2b8",
  "direction": "sent",
  "status": "pending",
  "sender_firm": {
    "uuid": "abc-123",
    "name": "Sender Firm Name"
  },
  "recipient_firm": {
    "uuid": "def-456",
    "name": "Recipient Firm Name"
  },
  "sender_account": {
    "uuid": {
      "example": "d87c8aab-a95e-4fe9-9bac-45d941909a04",
      "description": "The UUID of the resource.",
      "collection": false
    },
    "created_at": {
      "example": "2026-06-11T13:19:55+01:00",
      "description": "The timestamp of when the resource was created.",
      "collection": false
    },
    "updated_at": {
      "example": "2026-06-11T13:19:55+01:00",
      "description": "The timestamp of when the resource was updated.",
      "collection": false
    },
    "type": {
      "example": "client",
      "description": "Account type",
      "collection": false
    },
    "role": {
      "example": "client",
      "description": "Account role",
      "collection": false
    },
    "first_name": {
      "example": "Gareth",
      "description": "First name",
      "collection": false
    },
    "last_name": {
      "example": "Thompson",
      "description": "Last name",
      "collection": false
    },
    "name": {
      "example": "Gareth Thompson",
      "description": "Name",
      "collection": false
    },
    "email": {
      "example": "gareth@codepotato.co.uk",
      "description": "(Deprecated - Please use the primary email of the account instead). The email of the account.",
      "collection": false
    },
    "photo_url": {
      "example": "https://eu.ui-avatars.com/api/?name=Gareth+Thompson",
      "description": "The photo URL of the client",
      "collection": false
    },
    "external_references": {
      "example": "App\\Http\\Resources\\ExternalReferenceResource",
      "description": "The external references that have been added to the client.",
      "collection": true
    }
  },
  "recipient_account": {
    "uuid": {
      "example": "89ad7b86-9d55-455c-ba75-59365bd08d97",
      "description": "The UUID of the resource.",
      "collection": false
    },
    "created_at": {
      "example": "2026-06-11T13:19:55+01:00",
      "description": "The timestamp of when the resource was created.",
      "collection": false
    },
    "updated_at": {
      "example": "2026-06-11T13:19:55+01:00",
      "description": "The timestamp of when the resource was updated.",
      "collection": false
    },
    "type": {
      "example": "client",
      "description": "Account type",
      "collection": false
    },
    "role": {
      "example": "client",
      "description": "Account role",
      "collection": false
    },
    "first_name": {
      "example": "Gareth",
      "description": "First name",
      "collection": false
    },
    "last_name": {
      "example": "Thompson",
      "description": "Last name",
      "collection": false
    },
    "name": {
      "example": "Gareth Thompson",
      "description": "Name",
      "collection": false
    },
    "email": {
      "example": "gareth@codepotato.co.uk",
      "description": "(Deprecated - Please use the primary email of the account instead). The email of the account.",
      "collection": false
    },
    "photo_url": {
      "example": "https://eu.ui-avatars.com/api/?name=Gareth+Thompson",
      "description": "The photo URL of the client",
      "collection": false
    },
    "external_references": {
      "example": "App\\Http\\Resources\\ExternalReferenceResource",
      "description": "The external references that have been added to the client.",
      "collection": true
    }
  },
  "created_at": "2026-06-11T13:19:55+01:00",
  "updated_at": "2026-06-11T13:19:55+01:00",
  "expires_at": "2026-07-11T13:19:55+01:00"
}