Create a fact-find request [DEPRECATED: Use the v2 fact-find session routes] Deprecated 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/fact-find/request
Personal access token & O auth2

Headers

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

Body

  • fact_find_schema_uuid string(uuid) Required

    The UUID of the fact find schema that you would like the client to use.

  • client_uuid string(uuid) Required

    The UUID of the client account to send the fact find request. This must only be individual clients. Cannot be used with circle_uuid.

  • circle_uuid string(uuid) Required

    The UUID of the circle to send the fact find request to. Cannot be used with client_uuid.

  • send_invitation_email boolean

    This controls if an email to the client is sent to invite them to complete a fact find. Set this to false if you are going to send your own invitation.

  • invitation_text string

    The text that will appear in the invitation email sent to the client (if enabled)

Responses

  • 201 application/json
    Hide response attributes Show response attributes object
    • uuid string
    • created_at string
    • updated_at string
    • status string
    • completed_at string
    • invitation_text string
    • schema object
      Hide schema attributes Show schema attributes object
      • uuid string
      • created_at string
      • updated_at string
      • archived_at string
      • is_archived boolean
      • name string
      • introduction_html string
      • sections_count integer
      • public_url string
    • latest_file object
      Hide latest_file attributes Show latest_file attributes object
      • uuid string
      • created_at string
      • original_created_at string
      • updated_at string
      • uploaded_at string
      • status string
      • filename string
      • name string
      • extension string
      • type string
      • size string
      • path string
      • last_modified string
      • progress string
      • download_url string
      • folder_name string
      • folder object
        Hide folder attributes Show folder 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.

        • name

          Folder name

        • slug

          Slug of the folder name

        • path

          Folder path

        • clients_read

          Denotes whether clients can access this folder and files

        • clients_write

          Denotes whether clients can upload files to this folder

        • show_client_permissions

          Denotes whether the option to change client permissions is enabled which depends on the firm show pseudo folders in client portal setting

        • is_system_folder

          Denotes if this folder is a system folder

        • is_pseudo_folder

          Denotes if this folder is a pseudo folder

        • is_root_folder

          Denotes if this folder is a root folder of a documentable item

        • documentable_type

          The documentable type such as account/plan/case/etc the file was uploaded to

        • documentable_uuid

          The UUID of the documentable resource

        • documentable

          The documentable the file was uploaded to

        • participants_count

          Number of accounts this folder has been directly shared with

        • folders_count

          Number of subfolders within the folder

        • files_count

          Number of files stored in the folder

        • depth

          How many levels deep there are to this folder hierarchy structure

        • owned

          Is true if the authenticated account in the request has created this folder

      • documentable_type string
      • documentable string
      • navigator object
        Hide navigator attributes Show navigator attributes object
        • model_type string
        • model_uuid string
      • firm object
        Hide firm attributes Show firm 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.

        • name

          Name of the firm

        • slug

          Slug of the firm

        • address_1

          First line of the address

        • address_2

          Second line of the address

        • town_city

          Town/City

        • county

          County

        • postcode

          Postcode

        • country

          Country

        • regulatory_text

          Regulatory text of the firm.

        • logo_icon

          URL of your firm logo icon.

        • brand_colours

          Firm branding colours.

        • is_subscribed

          Subscription status.

        • keep_deleted_files_for

          Number of days to keep deleted files for

        • tax

          Tax percent

        • month_end

          Date of the month for the monthly income reconciliation statements to end

        • statement_frequency

          The frequency of the income reconciliation statements

        • billing

          Firm invoice details for billing

        • ip_whitelist

          A list of IP Addresses a firm is allowed to log in from.

        • welcome_paragraph_html

          Custom welcome paragraph html for the branded auth welcome page

        • email_welcome_paragraph_html

          Custom welcome paragraph for the welcome/new user email

        • show_fact_find_illustrations

          Determines if the illustrations/graphics are displayed on the fact find.

        • cc_email_addresses

          Array of email cc addresses.

        • bcc_email_addresses

          Array of email bcc addresses.

        • reply_to_email_address

          Firm reply to email address.

        • mobile_app_support_number

          Firm mobile app support number.

        • mobile_app_support_email

          Firm mobile app support email address.

      • account object
        Hide account attributes Show account 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.

        • type

          Account type

        • role

          Account role

        • first_name

          First name

        • last_name

          Last name

        • name

          Name

        • email

          (Deprecated - Please use the primary email of the account instead). The email of the account.

        • photo_url

          The photo URL of the client

      • tags object
        Hide tags attributes Show tags attributes object
        • uuid

          UUID of the tag

        • created_at

          The timestamp of when the resource was created.

        • updated_at

          The timestamp of when the resource was updated.

        • name

          The name of the tag

        • slug

          The slug of the tag

        • colour

          The colour of the tag

    • account object
      Hide account attributes Show 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.

    • invitation_url string
    • fact_find_passes object
      Hide fact_find_passes attributes Show fact_find_passes attributes object
      • uuid string
      • created_at string
      • updated_at string
      • firm object
        Hide firm attributes Show firm attributes object
        • uuid string
        • name string
      • account object
        Hide account attributes Show account 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.

        • type

          Account type

        • role

          Account role

        • first_name

          First name

        • last_name

          Last name

        • name

          Name

        • email

          (Deprecated - Please use the primary email of the account instead). The email of the account.

        • photo_url

          The photo URL of the client

      • circle object
        Hide circle attributes Show circle attributes object
        • uuid string
        • name string
      • expires_at string
      • progress integer
      • is_complete boolean
      • completed_sections integer
  • 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/fact-find/request 
curl \
 --request POST 'https://api.plannrcrm.com/api/v1/fact-find/request' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --header "X-PLANNR-ACCOUNT-UUID: {YOUR_PLANNR_ACCOUNT_UUID}" \
 --data '{"fact_find_schema_uuid":"f48157e5-5e83-4f81-ba05-91f4e90a181a","client_uuid":"f29ab41f-7a77-46a9-b9d8-b495089339c9","circle_uuid":"57674990-b8f0-4b8f-b4de-56c8fe2eb3cf","send_invitation_email":true,"invitation_text":"Please complete this fact find."}'
Request examples 
# Headers
X-PLANNR-ACCOUNT-UUID: {YOUR_PLANNR_ACCOUNT_UUID}

# Payload
{
  "fact_find_schema_uuid": "f48157e5-5e83-4f81-ba05-91f4e90a181a",
  "client_uuid": "f29ab41f-7a77-46a9-b9d8-b495089339c9",
  "circle_uuid": "57674990-b8f0-4b8f-b4de-56c8fe2eb3cf",
  "send_invitation_email": true,
  "invitation_text": "Please complete this fact find."
}
Response examples (201) 
{
  "uuid": "b347659c-81f3-4545-b504-05e0d9c26255",
  "created_at": "2026-08-07T15:29:24+01:00",
  "updated_at": "2026-08-07T15:29:24+01:00",
  "status": "complete",
  "completed_at": "2026-08-02T15:29:24+01:00",
  "invitation_text": "Please complete this fact find!",
  "schema": {
    "uuid": "b001f076-989e-4fb9-ae13-9868ba438490",
    "created_at": "2026-08-07T15:29:24+01:00",
    "updated_at": "2026-08-07T15:29:24+01:00",
    "archived_at": "2026-08-06T15:29:24+01:00",
    "is_archived": false,
    "name": "Default fact find",
    "introduction_html": "Welcome to our fact find! <b>You can use some HTML too.</b>",
    "sections_count": 5,
    "public_url": "https://api.plannrcrm.com/fact-find/2470424f-f45e-431a-8462-18509cd351fb"
  },
  "latest_file": {
    "uuid": "e838eef7-701e-4785-a942-9d381753bc7e",
    "created_at": "2026-08-07T15:29:24+01:00",
    "original_created_at": "2026-08-07T15:29:24+01:00",
    "updated_at": "2026-08-07T15:29:24+01:00",
    "uploaded_at": "2026-08-07T15:29:24+01:00",
    "status": "uploaded",
    "filename": "Welcome to Plannr.pdf",
    "name": "Welcome to Plannr",
    "extension": "pdf",
    "type": "type",
    "size": "21691783",
    "path": "Gareth Thompson/Subfolder/Welcome to Plannr.pdf",
    "last_modified": "2026-08-07T15:29:24+01:00",
    "progress": "100",
    "download_url": "https://api.plannrcrm.com/file/a807631c-b162-4bf5-96f0-4cabe2c51300/download",
    "folder_name": "folder 2",
    "folder": {
      "uuid": "bde45d1d-e84a-43e3-9fd9-b3c41ba5ce4d",
      "created_at": "2026-08-07T15:29:31+01:00",
      "updated_at": "2026-08-07T15:29:31+01:00",
      "name": "Important Documents",
      "slug": "important-documents",
      "path": "Codepotato/Important Documents",
      "clients_read": true,
      "clients_write": true,
      "show_client_permissions": true,
      "is_system_folder": true,
      "is_pseudo_folder": true,
      "is_root_folder": true,
      "documentable_type": "account",
      "documentable_uuid": "account",
      "documentable": "Object",
      "participants_count": 3,
      "folders_count": 5,
      "files_count": 8,
      "depth": 5,
      "owned": false
    },
    "documentable_type": "account",
    "documentable": "Object",
    "navigator": {
      "model_type": "account",
      "model_uuid": "94f394d0-fb94-433b-9e23-02088eed7599"
    },
    "firm": {
      "uuid": "b0e957af-03d9-4072-9cbe-9b59d7d5e8da",
      "created_at": "2026-08-07T15:29:31+01:00",
      "updated_at": "2026-08-07T15:29:31+01:00",
      "name": "Codepotato",
      "slug": "codepotato",
      "address_1": "Suite E, 5 The Briars",
      "address_2": "Waterberry Drive",
      "town_city": "Waterlooville",
      "county": "Hampshire",
      "postcode": "PO7 7YH",
      "country": "United Kingdom",
      "regulatory_text": "Regulatory text",
      "logo": "https://api.plannrcrm.com/images/plannr.jpg",
      "logo_icon": "https://api.plannrcrm.com/images/plannr-icon.jpg",
      "brand_colours": {
        "sidebar_background": "#0E0E56",
        "sidebar_accent": "#36367E",
        "sidebar_text": "#FFFFFF",
        "sidebar_hover": "#0A0A42",
        "sidebar_active": "#53DBB8",
        "sidebar_title_background": "#36367E",
        "sidebar_title_primary": "#FFC634",
        "sidebar_title_secondary": "#FFFFFF",
        "sidebar_title_secondary_hover": "#FFFFFF",
        "email_background": "#0E0E56",
        "email_logo_background_panel": "#36367E",
        "email_sub_text": "#FFFFFF",
        "email_button_background": "#36367E",
        "email_button_text": "#FFFFFF",
        "portal_sidebar_button_background": "#F6F6F6",
        "portal_sidebar_button_hover": "#FFFFFF",
        "portal_sidebar_button_active": "#FFFFFF",
        "portal_brand_title": "#323B4B",
        "portal_brand_sub_title": "#828994",
        "portal_sidebar_title": "#11151D",
        "portal_sidebar_text": "#323B4B",
        "portal_sidebar_text_hover": "#323B4B",
        "portal_sidebar_text_active": "#323B4B",
        "portal_sidebar_icon": "#828994",
        "portal_sidebar_icon_hover": "#828994",
        "portal_sidebar_icon_active": "#828994",
        "portal_background": "#F6F6F6",
        "portal_sidebar_account_title": "#11151D",
        "portal_sidebar_account_email": "#828994",
        "portal_sidebar_divider": "#E3E5E9",
        "portal_dashboard_bg_one": "#EF4583",
        "portal_dashboard_bg_two": "#FFC634",
        "portal_sidebar_collapse_button": "#828994",
        "portal_sidebar_collapse_button_hover": "#B3B9C4",
        "portal_sidebar_user_select_background": "#F6F6F6",
        "portal_sidebar_user_select_hover": "#F6F6F6",
        "portal_sidebar_user_select_text": "#323B4B",
        "portal_sidebar_user_select_text_hover": "#323B4B",
        "portal_sidebar_user_select_border": "#EEEEEE",
        "portal_sidebar_user_select_border_hover": "#828994"
      },
      "is_subscribed": true,
      "keep_deleted_files_for": 30,
      "tax": 17.5,
      "month_end": 25,
      "statement_frequency": "monthly",
      "billing": {
        "invoice_address_1": "Suite E, 5 The Briars",
        "invoice_address_2": "Waterberry Drive",
        "invoice_town_city": "Waterlooville",
        "invoice_county": "Hampshire",
        "invoice_postcode": "PO7 7YH",
        "invoice_country": "United Kingdom",
        "invoice_email": "gareth@codepotato.co.uk"
      },
      "ip_whitelist": [
        "192.168.0.1",
        "127.0.0.1"
      ],
      "welcome_paragraph_html": "<h1>Welcome.</h1>",
      "email_welcome_paragraph_html": "Welcome to Plannr!",
      "show_fact_find_illustrations": true,
      "cc_email_addresses": [
        "jack@example.com",
        "jill@example.com"
      ],
      "bcc_email_addresses": [
        "jack@example.com",
        "jill@example.com"
      ],
      "reply_to_email_address": "jack@example.com",
      "mobile_app_support_number": "01234 567890",
      "mobile_app_support_email": "support@example.com"
    },
    "account": {
      "uuid": "15dfe039-893e-4ddc-b0fd-8309bd154547",
      "created_at": "2026-08-07T15:29:31+01:00",
      "updated_at": "2026-08-07T15:29:31+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"
    },
    "tags": {
      "uuid": "765192aa-418f-4802-a430-62513b927bcd",
      "created_at": "2026-08-07T15:29:31+01:00",
      "updated_at": "2026-08-07T15:29:31+01:00",
      "name": "Mortgage",
      "slug": "mortgage",
      "colour": "#ef4582"
    }
  },
  "account": {
    "uuid": "12ba9059-3494-4b32-abff-cc77d7a9b9b6",
    "created_at": "2026-08-07T15:29:24+01:00",
    "updated_at": "2026-08-07T15:29: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": "2244294c-23fd-429a-b952-64a6fc469ad4",
      "created_at": "2026-08-07T15:29:31+01:00",
      "updated_at": "2026-08-07T15:29:31+01:00",
      "third_party": "nucleus",
      "reference": "AB123456"
    }
  },
  "invitation_url": "https://api.plannrcrm.com/fact-find/9edf017f-3560-4871-b025-c4c466933b86/cd392f09-e12d-48c5-8ea9-0ef254ec4282",
  "fact_find_passes": {
    "uuid": "d4beb4e0-06a9-4c56-93ea-c8bc903d49c9",
    "created_at": "2026-08-07T15:29:24+01:00",
    "updated_at": "2026-08-07T15:29:24+01:00",
    "firm": {
      "uuid": "bf467935-ae95-419c-aed1-2342e43010c4",
      "name": "Codepotato Ltd"
    },
    "account": {
      "uuid": "15dfe039-893e-4ddc-b0fd-8309bd154547",
      "created_at": "2026-08-07T15:29:31+01:00",
      "updated_at": "2026-08-07T15:29:31+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"
    },
    "circle": {
      "uuid": "878c13ab-5ffb-477e-bc49-cfdbf08fd5cc",
      "name": "The Codepotato Gang"
    },
    "expires_at": "2026-08-07T15:29:24+01:00",
    "progress": 50,
    "is_complete": false,
    "completed_sections": 2
  }
}
Response examples (422) 
{
  "message": "The given data was invalid.",
  "errors": {
    "field": [
      "The field is invalid."
    ]
  }
}