Creates a new referral connection request to another adviser using their referral code.

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

{
  "PlannrCRM MCP server": {
    "url": "https://apidocs.plannrcrm.com/mcp"
  }
}

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 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 connection request
  
  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 connection request 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/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": "2769cc0d-7506-4b40-98f6-d5dd3249b381",
  "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": "858c0649-8fda-45b1-bbb0-723427a099e6",
    "created_at": "2026-10-30T16:30:04+00:00",
    "updated_at": "2026-10-30T16:30:04+00: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": "239840c7-476b-43a0-b194-d63787e8cb83",
      "created_at": "2026-10-30T16:30:12+00:00",
      "updated_at": "2026-10-30T16:30:12+00:00",
      "third_party": "nucleus",
      "reference": "AB123456"
    }
  },
  "recipient_account": {
    "uuid": "75ccf663-380b-4bd7-9f26-d641a4e0a61c",
    "created_at": "2026-10-30T16:30:04+00:00",
    "updated_at": "2026-10-30T16:30:04+00: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": "239840c7-476b-43a0-b194-d63787e8cb83",
      "created_at": "2026-10-30T16:30:12+00:00",
      "updated_at": "2026-10-30T16:30:12+00:00",
      "third_party": "nucleus",
      "reference": "AB123456"
    }
  },
  "created_at": "2026-10-30T16:30:04+00:00",
  "updated_at": "2026-10-30T16:30:04+00:00",
  "expires_at": "2026-11-29T16:30:04+00:00"
}

Response examples (422)

{
  "message": "The given data was invalid.",
  "errors": {
    "field": [
      "The field is invalid."
    ]
  }
}