Create a fact-find request

POST /api/v1/fact-find/request

Personal access token & O auth2

Headers

X-PLANNR-ACCOUNT-UUID string

application/json

Body Required

fact_find_schema_uuid string Required

The UUID of the fact-find schema that you would like the client to use.
client_uuid string 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 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
  
  The UUID of the resource.
- created_at string
  
  The timestamp of when the resource was created.
- updated_at string
  
  The timestamp of when the resource was updated.
- status string
  
  The status of the fact-find request. Available options: in_progress,complete
- completed_at string
  
  The datetime when the fact-find request has been completed
- invitation_text string
  
  The text that is used in the notification/email sent out to the client.
- schema object
  
  The fact-find schema used for the fact-find request.
  
  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
  
  The latest file that has been generated for the fact-find request.
  
  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 string
  
  documentable_type string
  
  documentable string
  
  navigator object
  
  Hide navigator attributes Show navigator attributes object
  
  model_type string
  
  model_uuid string
  
  firm string
  
  account string
  
  tags string
- account object
  
  The account that the fact-find request was sent to. Only visible when listing fact-find requests for a circle.
  
  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 string
- invitation_url string
  
  The invitation URL sent to the client.
- fact_find_passes object
  
  The fact find passes added to the fact-find request.
  
  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 string
  
  circle object
  
  Hide circle attributes Show circle attributes object
  
  uuid string
  
  name string
  
  expires_at string
  
  progress integer
  
  is_complete boolean
  
  completed_sections integer

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":"7a6e8d32-13ec-4457-9217-0d047c3a07c7","client_uuid":"624c1d2e-e322-4049-ace6-ac33c1498e0f","circle_uuid":"85a2df4e-65ca-45b2-a5fb-6bac1911cb92","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": "7a6e8d32-13ec-4457-9217-0d047c3a07c7",
  "client_uuid": "624c1d2e-e322-4049-ace6-ac33c1498e0f",
  "circle_uuid": "85a2df4e-65ca-45b2-a5fb-6bac1911cb92",
  "send_invitation_email": true,
  "invitation_text": "Please complete this fact-find."
}

Response examples (201)

{
  "uuid": "9e2ad83d-941b-4961-8034-3ada0eadb838",
  "schema": {
    "name": "Default fact-find",
    "uuid": "d40aae11-7a8c-4eb1-9185-e136b0f14337",
    "created_at": "2025-08-27T17:31:27+01:00",
    "public_url": "https://api.plannrcrm.com/fact-find/e5f42728-008e-4426-a9ec-9b310849e027",
    "updated_at": "2025-08-27T17:31:27+01:00",
    "archived_at": "2025-08-26T17:31:27+01:00",
    "is_archived": false,
    "sections_count": 5,
    "introduction_html": "Welcome to our fact-find! <b>You can use some HTML too.</b>"
  },
  "status": "complete",
  "account": {
    "name": "Gareth Thompson",
    "role": "client",
    "type": "client",
    "uuid": "22f95cff-557a-45b5-9119-fcacacd6357c",
    "email": "gareth@codepotato.co.uk",
    "last_name": "Thompson",
    "photo_url": "https://eu.ui-avatars.com/api/?name=Gareth+Thompson",
    "created_at": "2025-08-27T17:31:27+01:00",
    "first_name": "Gareth",
    "updated_at": "2025-08-27T17:31:27+01:00",
    "external_references": "App\\Http\\Resources\\ExternalReferenceResource"
  },
  "created_at": "2025-08-27T17:31:27+01:00",
  "updated_at": "2025-08-27T17:31:27+01:00",
  "latest_file": {
    "firm": "App\\Http\\Resources\\FirmResource",
    "name": "Welcome to Plannr",
    "path": "Gareth Thompson/Subfolder/Welcome to Plannr.pdf",
    "size": "21691783",
    "tags": "App\\Http\\Resources\\TagResource",
    "type": "type",
    "uuid": "4fdb9206-a9a9-42f7-8ae5-8191fbe5d52c",
    "folder": "App\\Http\\Resources\\FolderResource",
    "status": "uploaded",
    "account": "App\\Http\\Resources\\MinimalAccountResource",
    "filename": "Welcome to Plannr.pdf",
    "progress": "100",
    "extension": "pdf",
    "navigator": {
      "model_type": "account",
      "model_uuid": "82f153e1-0615-41c6-b5f0-356ac53a9b41"
    },
    "created_at": "2025-08-27T17:31:27+01:00",
    "updated_at": "2025-08-27T17:31:27+01:00",
    "folder_name": "folder 2",
    "uploaded_at": "2025-08-27T17:31:27+01:00",
    "documentable": "Object",
    "download_url": "https://api.plannrcrm.com/file/ce801da6-5f13-410e-848b-ca7000ec2518/download",
    "last_modified": "2025-08-27T17:31:27+01:00",
    "documentable_type": "account",
    "original_created_at": "2025-08-27T17:31:27+01:00"
  },
  "completed_at": "2025-08-22T17:31:27+01:00",
  "invitation_url": "https://api.plannrcrm.com/fact-find/ab9e9e50-1fb7-465e-a441-d30ce4ddb783/a740a19b-4b92-4826-ac7a-2a25376779d9",
  "invitation_text": "Please complete this fact-find!",
  "fact_find_passes": {
    "firm": {
      "name": "Codepotato Ltd",
      "uuid": "27835f72-8631-4a71-be50-c052fb2a10d4"
    },
    "uuid": "afcecb20-0430-4999-9e66-2653ce8ea2f5",
    "circle": {
      "name": "The Codepotato Gang",
      "uuid": "e7303dea-c623-4b69-87c0-e88125d531b7"
    },
    "account": "App\\Http\\Resources\\MinimalAccountResource",
    "progress": 50,
    "created_at": "2025-08-27T17:31:27+01:00",
    "expires_at": "2025-08-27T17:31:27+01:00",
    "updated_at": "2025-08-27T17:31:27+01:00",
    "is_complete": false,
    "completed_sections": 2
  }
}