Create an income 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/v2/income
Personal access token & O auth2

Headers

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

Body

  • account_uuid string(uuid) Required

    Client account UUID of who this income belongs to.

  • name string Required

    The name of the income.

    Maximum length is 255.

  • type string Required

    The type of income.

    Value Description
    salary Salary
    dividend Dividend
    bonus Bonus
    benefit Benefit
    other Other
    investment Investment
    rental Rental
    pension Pension
    capital_gains Capital Gains
    business_loan Business Loan
    investor_funding Investor Funding
    grant Grant
    charity Charity
    crowdfunding Crowdfunding
    gross_profit Gross Profit
    operating_profit Operating Profit
    operating_revenue Operating Revenue
    non_operating_revenue Non Operating Revenue
    net_profit Net Profit

    Values are salary, dividend, bonus, benefit, other, investment, rental, pension, capital_gains, business_loan, investor_funding, grant, charity, crowdfunding, gross_profit, operating_profit, operating_revenue, non_operating_revenue, or net_profit.

  • type_other string | null

    The type of income when the type is set to "other".

    Maximum length is 255.

  • amount integer Required

    The amount of the income in pennies. For example, £50,000 would be 5000000.

  • amount_type string Required

    The type of the amount.

    Value Description
    net Net
    gross Gross

    Values are net or gross.

  • start_date string(date) | null

    The start date of the income.

  • end_date string(date) | null

    The end date of the income.

  • frequency string Required

    The frequency of the income.

    Value Description
    daily Daily
    weekly Weekly
    fortnightly Fortnightly
    four_weekly Four Weekly
    monthly Monthly
    bimonthly Bimonthly
    quarterly Quarterly
    biannually Biannually
    annually Annually
    adhoc Adhoc
    one_off One Off

    Values are daily, weekly, fortnightly, four_weekly, monthly, bimonthly, quarterly, biannually, annually, adhoc, or one_off.

  • is_taxable boolean

    Denotes if the income is taxable or not.

  • employment_uuid string(uuid)

    Employment to link to this salary, dividend, bonus, benefit type incomes.

Responses

  • 201 application/json
    Hide response attributes Show response attributes object
    • uuid string
    • created_at string
    • updated_at string
    • name string
    • type string
    • type_other string
    • amount object
      Hide amount attributes Show amount attributes object
      • amount object
        Hide amount attributes Show amount attributes object
        • example string
        • description string
      • formatted object
        Hide formatted attributes Show formatted attributes object
        • example string
        • description string
      • currency object
        Hide currency attributes Show currency attributes object
        • example string
        • description string
    • amount_type string
    • start_date string
    • end_date string
    • frequency string
    • is_taxable boolean
    • employment object
      Hide employment attributes Show employment attributes object
      • uuid string
      • created_at string
      • updated_at string
      • status string
      • primary boolean
      • occupation string
      • occupation_code string
      • job_title string
      • employer string
      • started_at string
      • ended_at string
      • is_business_owner boolean
      • percentage_of_business_shared integer
      • address object
        Hide address attributes Show address 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 address

        • address_1

          First line of the address

        • address_2

          Second line of the address

        • address_3

          Third line of the address

        • address_4

          Fourth line of the address

        • town_city

          Town/City

        • county

          County

        • postcode

          Postcode

        • country

          Country

        • move_in_date

          Address move in date. This field may provide inaccurate data. We recommend using the v2/addresses API which has the moved_in_month and moved_in_year fields instead.

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

          Contact detail type

        • name

          Contact detail description

        • value

          Contact detail value

        • phone_number_meta

          If the type is a phone number, this additional field will be displayed giving you information about the phone number.

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

          Contact detail type

        • name

          Contact detail description

        • value

          Contact detail value

        • phone_number_meta

          If the type is a phone number, this additional field will be displayed giving you information about the phone number.

      • shared_owner_type string
      • shared_owner object
        Hide shared_owner attributes Show shared_owner 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 primary_email instead). The email of the account.

        • photo_url

          URL for initial avatar image

        • first_contact_date

          First contact date

        • next_review_date

          Next review date

        • previous_review_date

          Previous review date

        • anniversary_review_date

          Anniversary review date

        • terms_of_business_at

          Date the Terms of Business were agreed and signed

        • client_agreement_at

          Date the client agreement was agreed and signed

        • with_login

          Denotes whether the account has a login to Plannr

        • has_joint_account

          Denotes whether this account belongs to a joint account too

        • can_be_deleted

          Denotes if the account can be deleted

        • ownership_percentage

          Percentage ownership of the plan (This field is only present if viewing the account record via a plans relationship eg Plan -> Accounts)

        • inactive_at

          Inactive from date

        • last_interaction_at

          Last interaction date

        • referral_code

          Unique referral code for the employee account (employees only)

        • is_out_of_office

          Denotes whether the account is currently within an active Out of Office window (employees only)

        • out_of_office_from

          Start of the Out of Office period (employees only). Null when not out of office

        • out_of_office_until

          End of the Out of Office period (employees only). Null when not out of office

        • out_of_office_message

          Message shown to portal users while the account is Out of Office (employees only). Null when not out of office

        • permissions

          Permission map where keys are permission names and values are target arrays

      • last_salary_increase string
      • business_name string
      • business_year_end string
      • business_value object
        Hide business_value attributes Show business_value attributes object
        • amount object
          Hide amount attributes Show amount attributes object
          • example string
          • description string
        • formatted object
          Hide formatted attributes Show formatted attributes object
          • example string
          • description string
        • currency object
          Hide currency attributes Show currency attributes object
          • example string
          • description string
      • directors string
      • shareholding_in_business object
        Hide shareholding_in_business attributes Show shareholding_in_business attributes object
        • amount object
          Hide amount attributes Show amount attributes object
          • example string
          • description string
        • formatted object
          Hide formatted attributes Show formatted attributes object
          • example string
          • description string
        • currency object
          Hide currency attributes Show currency attributes object
          • example string
          • description string
      • profit object
        Hide profit attributes Show profit attributes object
        • amount object
          Hide amount attributes Show amount attributes object
          • example string
          • description string
        • formatted object
          Hide formatted attributes Show formatted attributes object
          • example string
          • description string
        • currency object
          Hide currency attributes Show currency attributes object
          • example string
          • description string
      • accountant_company_name string
      • accountant_email string
      • accountant_telephone_number string
      • accountant_address string
      • turnover_history object
        Hide turnover_history attributes Show turnover_history attributes object
        • year

          The year of the turnover.

        • value

          The value of the turnover.

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

          The name of the income.

        • type

          The type of income.

        • type_other

          The other type of income, if the type is "other".

        • amount

          The amount of the income.

        • amount_type

          The type of the amount.

        • start_date

          The start date of the income.

        • end_date

          The end date of the income.

        • frequency

          The frequency of the income.

        • is_taxable

          Denotes if the income is taxable or not.

        • shared_owner_type

          Denotes if the employment is shared across the client or belongs to one of the owners of the client. (Only applicable for joint/business/trust clients).

      • 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

    • 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.
  • 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/v2/income 
curl \
 --request POST 'https://api.plannrcrm.com/api/v2/income' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --header "X-PLANNR-ACCOUNT-UUID: {YOUR_PLANNR_ACCOUNT_UUID}" \
 --data '{"account_uuid":"cec79562-ec4b-4625-baa9-24d1b714bcc0","name":"My Salary","type":"salary","type_other":"My Other Income","amount":5000000,"amount_type":"net","start_date":"2025-08-07","end_date":"2026-08-07","frequency":"daily","is_taxable":true,"employment_uuid":"1cf9596b-0efb-49df-825c-bc040cd8743b"}'
Request examples 
# Headers
X-PLANNR-ACCOUNT-UUID: {YOUR_PLANNR_ACCOUNT_UUID}

# Payload
{
  "account_uuid": "cec79562-ec4b-4625-baa9-24d1b714bcc0",
  "name": "My Salary",
  "type": "salary",
  "type_other": "My Other Income",
  "amount": 5000000,
  "amount_type": "net",
  "start_date": "2025-08-07",
  "end_date": "2026-08-07",
  "frequency": "daily",
  "is_taxable": true,
  "employment_uuid": "1cf9596b-0efb-49df-825c-bc040cd8743b"
}
Response examples (201) 
{
  "uuid": "36ca50ba-7401-47b0-a61c-87440e59207d",
  "created_at": "2026-08-07T15:29:26+01:00",
  "updated_at": "2026-08-07T15:29:26+01:00",
  "name": "My Salary",
  "type": "salary",
  "type_other": "Other income type",
  "amount": {
    "amount": {
      "example": "4000",
      "description": "Money amount at their lowest denominator (for example: pennies)"
    },
    "formatted": {
      "example": "£40.00",
      "description": "Money amount formatted with currency"
    },
    "currency": {
      "example": "GBP",
      "description": "Currency of the money"
    }
  },
  "amount_type": "net",
  "start_date": "2025-08-07",
  "end_date": "2026-08-07",
  "frequency": "annually",
  "is_taxable": true,
  "employment": {
    "uuid": "8525b5ba-e78f-44ed-83df-397f3c1777c9",
    "created_at": "2026-08-07T15:29:26+01:00",
    "updated_at": "2026-08-07T15:29:26+01:00",
    "status": "employed",
    "primary": true,
    "occupation": "Financial Adviser",
    "occupation_code": "FAC02774",
    "job_title": "Senior financial adviser",
    "employer": "Plannr Technologies Ltd",
    "started_at": "2021-08-07T15:29:26+01:00",
    "ended_at": "2022-08-07T15:29:26+01:00",
    "is_business_owner": true,
    "percentage_of_business_shared": 50,
    "address": {
      "uuid": "41724a78-8f04-4945-a006-54383c218917",
      "created_at": "2026-08-07T15:29:32+01:00",
      "updated_at": "2026-08-07T15:29:32+01:00",
      "name": "Work Address",
      "address_1": "Suite E, 5 The Briars",
      "address_2": "Waterberry Drive",
      "address_3": "The Innovative Centre",
      "address_4": "Waterlooville",
      "town_city": "Waterlooville",
      "county": "Hampshire",
      "postcode": "PO7 7YH",
      "country": "United Kingdom",
      "move_in_date": "2025-08-07"
    },
    "phone_number": {
      "uuid": "68760323-f4da-4f8f-a151-1b3c68c631dd",
      "created_at": "2026-08-07T15:29:31+01:00",
      "updated_at": "2026-08-07T15:29:31+01:00",
      "type": "phone_number",
      "name": "Work number",
      "value": "+443330903630",
      "phone_number_meta": {
        "country": "GB",
        "formatted": "0333 090 3630"
      }
    },
    "email_address": {
      "uuid": "68760323-f4da-4f8f-a151-1b3c68c631dd",
      "created_at": "2026-08-07T15:29:31+01:00",
      "updated_at": "2026-08-07T15:29:31+01:00",
      "type": "phone_number",
      "name": "Work number",
      "value": "+443330903630",
      "phone_number_meta": {
        "country": "GB",
        "formatted": "0333 090 3630"
      }
    },
    "shared_owner_type": "individual",
    "shared_owner": {
      "uuid": "5a9609f8-00cf-4107-9b31-169e28e476f7",
      "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",
      "first_contact_date": "2026-08-07T15:29:31+01:00",
      "next_review_date": "2026-08-07T15:29:31+01:00",
      "previous_review_date": "2026-08-07T15:29:31+01:00",
      "anniversary_review_date": "2026-08-07T15:29:31+01:00",
      "terms_of_business_at": "2026-08-07T15:29:31+01:00",
      "client_agreement_at": "2026-08-07T15:29:31+01:00",
      "with_login": true,
      "has_joint_account": true,
      "can_be_deleted": "false",
      "ownership_percentage": 100.0,
      "inactive_at": "2026-08-07",
      "last_interaction_at": "2026-08-07 15:29:31",
      "referral_code": "ABC12345",
      "is_out_of_office": true,
      "out_of_office_from": "2026-08-07T15:29:31+01:00",
      "out_of_office_until": "2026-08-07T15:29:31+01:00",
      "out_of_office_message": "I am away this week. For urgent matters please contact the office.",
      "permissions": {
        "firm:read": [
          "firm"
        ],
        "network:read": [
          "network:uuid"
        ]
      }
    },
    "last_salary_increase": "2019-01-01",
    "business_name": "My Business",
    "business_year_end": "2020-12-31",
    "business_value": {
      "amount": {
        "example": "4000",
        "description": "Money amount at their lowest denominator (for example: pennies)"
      },
      "formatted": {
        "example": "£40.00",
        "description": "Money amount formatted with currency"
      },
      "currency": {
        "example": "GBP",
        "description": "Currency of the money"
      }
    },
    "directors": "Susan F. Lancaster",
    "shareholding_in_business": {
      "amount": {
        "example": "4000",
        "description": "Money amount at their lowest denominator (for example: pennies)"
      },
      "formatted": {
        "example": "£40.00",
        "description": "Money amount formatted with currency"
      },
      "currency": {
        "example": "GBP",
        "description": "Currency of the money"
      }
    },
    "profit": {
      "amount": {
        "example": "4000",
        "description": "Money amount at their lowest denominator (for example: pennies)"
      },
      "formatted": {
        "example": "£40.00",
        "description": "Money amount formatted with currency"
      },
      "currency": {
        "example": "GBP",
        "description": "Currency of the money"
      }
    },
    "accountant_company_name": "My Accountant",
    "accountant_email": "accountant@email.com",
    "accountant_telephone_number": "+441234567890",
    "accountant_address": "23 Chollerton, Hexham, Northumberland, NE46 4TF",
    "turnover_history": {
      "year": 2020,
      "value": {
        "amount": {
          "example": "4000",
          "description": "Money amount at their lowest denominator (for example: pennies)"
        },
        "formatted": {
          "example": "£40.00",
          "description": "Money amount formatted with currency"
        },
        "currency": {
          "example": null,
          "description": "Currency of the money"
        }
      }
    },
    "income": {
      "uuid": "24120f29-654d-47a4-8464-4d2617be4ea0",
      "created_at": "2026-08-07T15:29:32+01:00",
      "updated_at": "2026-08-07T15:29:32+01:00",
      "name": "My Salary",
      "type": "salary",
      "type_other": "Other income type",
      "amount": {
        "amount": {
          "example": "4000",
          "description": "Money amount at their lowest denominator (for example: pennies)"
        },
        "formatted": {
          "example": "£40.00",
          "description": "Money amount formatted with currency"
        },
        "currency": {
          "example": null,
          "description": "Currency of the money"
        }
      },
      "amount_type": "net",
      "start_date": "2025-08-07",
      "end_date": "2026-08-07",
      "frequency": "annually",
      "is_taxable": true,
      "shared_owner_type": "individual"
    },
    "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"
    }
  },
  "account": {
    "uuid": "0e1aa89c-edd2-4809-9c7d-0b0f87d16994",
    "created_at": "2026-08-07T15:29:26+01:00",
    "updated_at": "2026-08-07T15:29:26+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"
    }
  }
}
Response examples (422) 
{
  "message": "The given data was invalid.",
  "errors": {
    "field": [
      "The field is invalid."
    ]
  }
}