Create an Employment Run in API Explorer
Ask AI
Creates an employment record
Body
-
The uuid of the account to link Employment to.
-
The name of the accountant company.
Maximum length is
255. -
The email of the accountant.
Maximum length is
255. -
The telephone number of the accountant.
-
The address of the accountant.
Maximum length is
255. -
The name of the business.
Maximum length is
255. -
The value of the business in pennies.
-
The year end of the business.
Maximum length is
255. -
The directors of the business.
Maximum length is
255. -
The name of the employer/business.
Maximum length is
255. -
The email address of the employer. Will be added as a contact detail.
Maximum length is
255. -
An optional end date of the employment.
-
Denotes if the employment owner is the business owner.
-
Job title if no suitable occupation code is found.
Maximum length is
255. -
The date of the last salary increase.
-
The Origo occupation code for the given employment. You can use the /api/v1/static/occupations endpoint to get a list of occupations.
-
The percentage of the business owned.
Minimum value is
0, maximum value is100. -
The phone number of the employer. In E.164 format. Will be added as a contact detail.
-
Make this employment the primary employment. Will make all other employments no longer primary.
-
The profit of the business in pennies.
Minimum value is
0. -
An optional start date of the employment.
-
The employment status for the given employment.
Value Description employed Employed self_employed Self Employed student Student unemployed Unemployed house_person House Person retired Retired other Other Values are
employed,self_employed,student,unemployed,house_person,retired, orother. -
An array of turnover history items.
POST
/api/v2/employments
curl \
--request POST 'https://api.plannrcrm.com/api/v2/employments' \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header "Content-Type: application/json" \
--header "X-PLANNR-ACCOUNT-UUID: {YOUR_PLANNR_ACCOUNT_UUID}" \
--data '{"account_uuid":"52357768-e835-4fa5-ac9f-921188820464","accountant_company_name":"My Company","accountant_email":"accountant@email.com","accountant_telephone_number":"0123456789","accountant_address":"1 My Street, My Town, My Country","business_name":"My Business","business_value":5000000,"business_year_end":"2019-01-01","directors":"John Doe","employer":"Plannr Technologies Ltd","email_address":"gareth@plannrcrm.com","ended_at":"2022-01-16","is_business_owner":true,"job_title":"Senior Developer","last_salary_increase":"2019-01-01","occupation_code":"FAC02774","percentage_of_business_owned":50,"phone_number":"+443330509960","primary":true,"profit":5000000,"shareholding_in_business":50.5,"started_at":"2021-01-16","status":"employed","turnover_history":[{"year":"2020","value":1000000}],"address":{"name":"Work Address","address_1":"Suite E","address_2":"5 The Briars","address_3":"Waterberry Drive","address_4":"The Innovative Centre","town_city":"Waterlooville","county":"Hampshire","postcode":"PO7 7YH","country":"United Kingdom","move_in_date":"2024-06-20","moved_in_month":6,"moved_in_year":2022,"moved_out_month":1,"moved_out_year":2024,"residential_status":"homeowner","residential_status_other":"Non-tenant occupier"}}'
Request examples
# Headers
X-PLANNR-ACCOUNT-UUID: {YOUR_PLANNR_ACCOUNT_UUID}
# Payload
{
"account_uuid": "52357768-e835-4fa5-ac9f-921188820464",
"accountant_company_name": "My Company",
"accountant_email": "accountant@email.com",
"accountant_telephone_number": "0123456789",
"accountant_address": "1 My Street, My Town, My Country",
"business_name": "My Business",
"business_value": 5000000,
"business_year_end": "2019-01-01",
"directors": "John Doe",
"employer": "Plannr Technologies Ltd",
"email_address": "gareth@plannrcrm.com",
"ended_at": "2022-01-16",
"is_business_owner": true,
"job_title": "Senior Developer",
"last_salary_increase": "2019-01-01",
"occupation_code": "FAC02774",
"percentage_of_business_owned": 50,
"phone_number": "+443330509960",
"primary": true,
"profit": 5000000,
"shareholding_in_business": 50.5,
"started_at": "2021-01-16",
"status": "employed",
"turnover_history": [
{
"year": "2020",
"value": 1000000
}
],
"address": {
"name": "Work Address",
"address_1": "Suite E",
"address_2": "5 The Briars",
"address_3": "Waterberry Drive",
"address_4": "The Innovative Centre",
"town_city": "Waterlooville",
"county": "Hampshire",
"postcode": "PO7 7YH",
"country": "United Kingdom",
"move_in_date": "2024-06-20",
"moved_in_month": 6,
"moved_in_year": 2022,
"moved_out_month": 1,
"moved_out_year": 2024,
"residential_status": "homeowner",
"residential_status_other": "Non-tenant occupier"
}
}
Response examples (201)
{
"uuid": "c3ccf951-bed8-4eb4-bda6-507e2e0c44f3",
"income": {
"name": "My Salary",
"type": "salary",
"uuid": "0ce39049-eb93-4a68-b78f-44358bbdef90",
"amount": {
"amount": {
"example": "4000",
"description": "Money amount at their lowest denominator (for example: pennies)"
},
"currency": {
"example": "GBP",
"description": "Currency of the money"
},
"formatted": {
"example": "£40.00",
"description": "Money amount formatted with currency"
}
},
"account": "App\\Http\\Resources\\MinimalAccountResource",
"end_date": "2026-01-16",
"frequency": "annually",
"created_at": "2026-01-16T13:10:24+00:00",
"employment": "App\\Http\\Resources\\EmploymentResource",
"is_taxable": true,
"start_date": "2025-01-16",
"type_other": "Other income type",
"updated_at": "2026-01-16T13:10:24+00:00",
"amount_type": "net",
"shared_owner": "App\\Http\\Resources\\AccountResource",
"shared_owner_type": "individual"
},
"profit": {
"amount": {
"example": "4000",
"description": "Money amount at their lowest denominator (for example: pennies)"
},
"currency": {
"example": "GBP",
"description": "Currency of the money"
},
"formatted": {
"example": "£40.00",
"description": "Money amount formatted with currency"
}
},
"status": "employed",
"account": {
"name": "Gareth Thompson",
"role": "client",
"type": "client",
"uuid": "28daf6f3-5e7d-4f13-b356-24cce6db32df",
"email": "gareth@codepotato.co.uk",
"last_name": "Thompson",
"photo_url": "https://eu.ui-avatars.com/api/?name=Gareth+Thompson",
"created_at": "2026-01-16T13:10:24+00:00",
"first_name": "Gareth",
"updated_at": "2026-01-16T13:10:24+00:00",
"external_references": "App\\Http\\Resources\\ExternalReferenceResource"
},
"address": {
"name": "Work Address",
"uuid": "1b123dfb-abf7-47fa-9132-92c1f00db89a",
"county": "Hampshire",
"country": "United Kingdom",
"accounts": "App\\Http\\Resources\\AccountResource",
"postcode": "PO7 7YH",
"address_1": "Suite E, 5 The Briars",
"address_2": "Waterberry Drive",
"address_3": "The Innovative Centre",
"address_4": "Waterlooville",
"town_city": "Waterlooville",
"created_at": "2026-01-16T13:10:24+00:00",
"updated_at": "2026-01-16T13:10:24+00:00",
"move_in_date": "2025-01-16"
},
"primary": true,
"employer": "Plannr Technologies Ltd",
"ended_at": "2022-01-16T13:10:24+00:00",
"directors": "Susan F. Lancaster",
"job_title": "Senior financial adviser",
"created_at": "2026-01-16T13:10:24+00:00",
"occupation": "Financial Adviser",
"started_at": "2021-01-16T13:10:24+00:00",
"updated_at": "2026-01-16T13:10:24+00:00",
"phone_number": {
"name": "Work number",
"type": "phone_number",
"uuid": "1ef9e248-3958-4c18-bfd2-e1b9d0964e2e",
"value": "+443330903630",
"accounts": "App\\Http\\Resources\\AccountResource",
"created_at": "2026-01-16T13:10:24+00:00",
"updated_at": "2026-01-16T13:10:24+00:00",
"phone_number_meta": {
"country": "GB",
"formatted": "0333 090 3630"
}
},
"shared_owner": {
"firm": "App\\Http\\Resources\\FirmResource",
"name": "Gareth Thompson",
"role": "client",
"tags": "App\\Http\\Resources\\TagResource",
"type": "client",
"uuid": "707626f8-80f3-4054-8bff-6129cc02235e",
"email": "gareth@codepotato.co.uk",
"groups": "App\\Http\\Resources\\GroupResource",
"owners": "App\\Http\\Resources\\AccountResource",
"circles": "App\\Http\\Resources\\CircleResource",
"last_name": "Thompson",
"photo_url": "https://eu.ui-avatars.com/api/?name=gareth+thompson",
"created_at": "2026-01-16T13:10:24+00:00",
"first_name": "Gareth",
"updated_at": "2026-01-16T13:10:24+00:00",
"with_login": true,
"inactive_at": "2026-01-16",
"custom_fields": "App\\Http\\Resources\\CustomFieldValueResource",
"introduced_by": "App\\Http\\Resources\\AccountResource",
"primary_email": "App\\Http\\Resources\\ContactDetailResource",
"can_be_deleted": "false",
"assigned_adviser": "App\\Http\\Resources\\AccountResource",
"next_review_date": "2026-01-16T13:10:24+00:00",
"has_joint_account": true,
"current_time_entry": "App\\Http\\Resources\\TimeEntryResource",
"first_contact_date": "2026-01-16T13:10:24+00:00",
"external_references": "App\\Http\\Resources\\ExternalReferenceResource",
"last_interaction_at": "2026-01-16 13:10:24",
"assigned_paraplanner": "App\\Http\\Resources\\AccountResource",
"joint_account_circle": "App\\Http\\Resources\\CircleResource",
"ownership_percentage": 100,
"previous_review_date": "2026-01-16T13:10:24+00:00",
"primary_phone_number": "App\\Http\\Resources\\ContactDetailResource",
"assigned_administrator": "App\\Http\\Resources\\AccountResource",
"anniversary_review_date": "2026-01-16T13:10:24+00:00"
},
"business_name": "My Business",
"email_address": {
"name": "Work number",
"type": "phone_number",
"uuid": "aebec487-3155-4bff-879f-daf97f8eb9c8",
"value": "+443330903630",
"accounts": "App\\Http\\Resources\\AccountResource",
"created_at": "2026-01-16T13:10:24+00:00",
"updated_at": "2026-01-16T13:10:24+00:00",
"phone_number_meta": {
"country": "GB",
"formatted": "0333 090 3630"
}
},
"business_value": {
"amount": {
"example": "4000",
"description": "Money amount at their lowest denominator (for example: pennies)"
},
"currency": {
"example": "GBP",
"description": "Currency of the money"
},
"formatted": {
"example": "£40.00",
"description": "Money amount formatted with currency"
}
},
"occupation_code": "FAC02774",
"accountant_email": "accountant@email.com",
"turnover_history": {
"year": 2020,
"value": {
"amount": {
"example": "4000",
"description": "Money amount at their lowest denominator (for example: pennies)"
},
"currency": {
"example": "GBP",
"description": "Currency of the money"
},
"formatted": {
"example": "£40.00",
"description": "Money amount formatted with currency"
}
}
},
"business_year_end": "2020-12-31",
"is_business_owner": true,
"shared_owner_type": "individual",
"accountant_address": "23 Chollerton, Hexham, Northumberland, NE46 4TF",
"last_salary_increase": "2019-01-01",
"accountant_company_name": "My Accountant",
"shareholding_in_business": {
"amount": {
"example": "4000",
"description": "Money amount at their lowest denominator (for example: pennies)"
},
"currency": {
"example": "GBP",
"description": "Currency of the money"
},
"formatted": {
"example": "£40.00",
"description": "Money amount formatted with currency"
}
},
"accountant_telephone_number": "+441234567890",
"percentage_of_business_shared": 50
}