Creates a new referral connection request to another adviser using their referral code. Run in API Explorer

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": "95cc9f56-a43d-4fab-a473-cc829f2dcf24",
  "status": "pending",
  "direction": "sent",
  "created_at": "2026-01-20T17:51:29+00:00",
  "expires_at": "2026-02-19T17:51:29+00:00",
  "updated_at": "2026-01-20T17:51:29+00:00",
  "sender_firm": {
    "name": "Sender Firm Name",
    "uuid": "abc-123"
  },
  "recipient_firm": {
    "name": "Recipient Firm Name",
    "uuid": "def-456"
  },
  "sender_account": {
    "name": {
      "example": "Gareth Thompson",
      "collection": false,
      "description": "Name"
    },
    "role": {
      "example": "client",
      "collection": false,
      "description": "Account role"
    },
    "type": {
      "example": "client",
      "collection": false,
      "description": "Account type"
    },
    "uuid": {
      "example": "98578750-d499-4b44-9333-cc817483bfff",
      "collection": false,
      "description": "The UUID of the resource."
    },
    "email": {
      "example": "gareth@codepotato.co.uk",
      "collection": false,
      "description": "(Deprecated - Please use the primary email of the account instead). The email of the account."
    },
    "last_name": {
      "example": "Thompson",
      "collection": false,
      "description": "Last name"
    },
    "photo_url": {
      "example": "https://eu.ui-avatars.com/api/?name=Gareth+Thompson",
      "collection": false,
      "description": "The photo URL of the client"
    },
    "created_at": {
      "example": "2026-01-20T17:51:29+00:00",
      "collection": false,
      "description": "The timestamp of when the resource was created."
    },
    "first_name": {
      "example": "Gareth",
      "collection": false,
      "description": "First name"
    },
    "updated_at": {
      "example": "2026-01-20T17:51:29+00:00",
      "collection": false,
      "description": "The timestamp of when the resource was updated."
    },
    "external_references": {
      "example": "App\\Http\\Resources\\ExternalReferenceResource",
      "collection": true,
      "description": "The external references that have been added to the client."
    }
  },
  "recipient_account": {
    "name": {
      "example": "Gareth Thompson",
      "collection": false,
      "description": "Name"
    },
    "role": {
      "example": "client",
      "collection": false,
      "description": "Account role"
    },
    "type": {
      "example": "client",
      "collection": false,
      "description": "Account type"
    },
    "uuid": {
      "example": "86d1709d-5847-4e33-ac4c-0c21e110c60d",
      "collection": false,
      "description": "The UUID of the resource."
    },
    "email": {
      "example": "gareth@codepotato.co.uk",
      "collection": false,
      "description": "(Deprecated - Please use the primary email of the account instead). The email of the account."
    },
    "last_name": {
      "example": "Thompson",
      "collection": false,
      "description": "Last name"
    },
    "photo_url": {
      "example": "https://eu.ui-avatars.com/api/?name=Gareth+Thompson",
      "collection": false,
      "description": "The photo URL of the client"
    },
    "created_at": {
      "example": "2026-01-20T17:51:29+00:00",
      "collection": false,
      "description": "The timestamp of when the resource was created."
    },
    "first_name": {
      "example": "Gareth",
      "collection": false,
      "description": "First name"
    },
    "updated_at": {
      "example": "2026-01-20T17:51:29+00:00",
      "collection": false,
      "description": "The timestamp of when the resource was updated."
    },
    "external_references": {
      "example": "App\\Http\\Resources\\ExternalReferenceResource",
      "collection": true,
      "description": "The external references that have been added to the client."
    }
  }
}