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

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 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

      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 expires
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) 
{
  "note": "Client needs help with retirement planning.",
  "uuid": "ac6ac96d-cd94-4e1c-9374-da46b5b7728d",
  "status": "pending",
  "clients": [
    {
      "name": "John Doe",
      "uuid": "client-uuid-1"
    }
  ],
  "direction": "sent",
  "connection": {
    "uuid": "abc-123"
  },
  "created_at": "2026-01-20T17:51:29+00:00",
  "expires_at": "2026-04-20T17:51:29+01:00",
  "updated_at": "2026-01-20T17:51:29+00:00",
  "advice_type": "investments",
  "sender_firm": {
    "name": "Sender Firm Name",
    "uuid": "abc-123"
  },
  "shared_data": [
    "basic_details",
    "contact_details"
  ],
  "sla_deadline": "2026-02-28",
  "cloned_clients": [
    {
      "name": "John Doe",
      "uuid": "cloned-uuid-1"
    }
  ],
  "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": "a4890f86-e45b-498c-b1d5-b0d88eb0c6f3",
      "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."
    }
  },
  "duration_months": 3,
  "rejection_reason": "Unable to take on new clients.",
  "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": "66e3ec21-8ee5-4cb6-bebf-ef049bd76602",
      "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."
    }
  }
}