Jobs

Create job

Create a new job with property and customer details.

post/v1/jobs

Request

Base URL
https://api.spruce.eco
Auth
HTTP bearer

Request body

altitude_mnumber

Property altitude in meters. Will be derived from the coordinates if not provided.

built_form'detached' | 'semi_detached' | 'mid_terrace' | 'end_terrace' required

Built form of the property

floor_area_m2number required

Total floor area in square meters

Current heating fuel type

loft_insulation'none' | '50mm' | '100mm' | '150mm' | '200mm' | '250+mm' required

Loft insulation thickness

num_bathroomsinteger

Number of bathrooms

num_bedroomsinteger required

Number of bedrooms

num_storeysinteger

Number of storeys

postcodestring required

UK postcode or Irish Eircode

property_type'house' | 'flat' | 'bungalow' required

Property type

room_height_mnumber

Room height in metres

Wall construction and insulation type

window_type'single_glazing' | 'double_glazing' | 'high_performance' | 'triple_glazing' required

Window glazing type

floor_u_valuenumber

Floor U-value in W/m²K (optional, if directly measured or from EPC). If provided, overrides the floor U-value used in the heat loss calculation.

roof_u_valuenumber

Roof U-value in W/m²K (optional, if directly measured or from EPC). If provided, overrides the roof U-value used in the heat loss calculation (otherwise derived from loft_insulation).

wall_u_valuenumber

External wall U-value in W/m²K (optional, if directly measured or from EPC). If provided, overrides both the external wall and party wall U-values used in the heat loss calculation (party wall capped at 0.5 W/m²K; otherwise derived from wall_type).

window_u_valuenumber

Window U-value in W/m²K (optional, if directly measured or from EPC). If provided, overrides the window U-value used in the heat loss calculation (otherwise derived from window_type).

addressstring required

Full property address (consisting of optional apartment number, street and post town) without postcode

cibse_design_temperature_versionnumber

Optional CIBSE weather dataset version to use for this job (2 = 2015 dataset, 3 = 2026 dataset). If omitted, the job inherits the company's configured default at read time.

The country the property is in. Used to determine grant scheme and paperwork. If omitted, it's derived from the postcode / any linked EPC.

customer_emailstring email required

Customer's email address

customer_first_namestring required

Customer's first name

customer_last_namestring required

Customer's last name

customer_phonestring required

Customer's phone number

epc_certificate_numberstring

EPC Certificate number for an English/Welsh EPC. If this is present, we will make a best-effort attempt to retrieve the EPC data and link it to the job.

job_namestring

Optional custom name for the job

job_referencestring

Optional job reference, which must be unique within the company. If not provided, will be generated from the customer surname. Must be at least 3 characters long and not contain the # character. The API will return an error if the reference is invalid or already exists.

lat_lngnumber[] required

Latitude and longitude coordinates of the address [lat, lng]

outdoor_space'ground_floor' | 'upper_floor' | 'none'

Outdoor space availability. Only relevant for flats - indicates where the heat pump could be installed.

payaca_project_idstring

The ID of an associated Payaca project. If included and the authed company has a Payaca integration set up, the job in Spruce will be linked to this Payaca project. This ID cannot be changed after the job is created.

sourcestring

Source of the lead (e.g., 'API', 'Social media', 'Search engine', 'Word of mouth', 'Trade show')

tagsstring[]

Tags to apply to this job. If a tag name does not exist for your company, it will be created automatically.

udprnstring

Unique Delivery Point Reference Number

uprnstring

Unique Property Reference Number. If this is included but the EPC certificate number key is omitted, we will attempt to retrieve the EPC from this. Passing the EPC certificate number is a more reliable method to retrieve an EPC.

year_builtnumber

Year the property was built.

Example request

{
  "altitude_m": 50,
  "built_form": "semi_detached",
  "floor_area_m2": 120,
  "fuel_type": "mains_gas",
  "loft_insulation": "150mm",
  "num_bathrooms": 2,
  "num_bedrooms": 3,
  "num_storeys": 2,
  "postcode": "SW1A 1AA",
  "property_type": "house",
  "room_height_m": 2.4,
  "wall_type": "cavity_wall_filled",
  "window_type": "double_glazing",
  "floor_u_value": 0.18,
  "roof_u_value": 0.11,
  "wall_u_value": 0.18,
  "window_u_value": 1.4,
  "address": "10 Downing Street, Westminster, London",
  "cibse_design_temperature_version": 2,
  "country": "England",
  "customer_email": "james.bond@example.com",
  "customer_first_name": "James",
  "customer_last_name": "Bond",
  "customer_phone": "07700 900123",
  "epc_certificate_number": "0123-4567-8901-2345-6789",
  "job_name": "Bond Residence Heat Pump Installation",
  "job_reference": "BON-007",
  "lat_lng": [
    51.5033,
    -0.1276
  ],
  "outdoor_space": "ground_floor",
  "payaca_project_id": "deea7132-665b-4531-86fb-072439bd68ba",
  "source": "API",
  "tags": [
    "From API",
    "Referral"
  ],
  "udprn": "23747771",
  "uprn": "100023336956",
  "year_built": 1949
}

Response

Job created successfully

job_referencestring required

The unique job reference, which can be used to search for the job in the Spruce admin panel. It is never used by the API.

urlstring uri required

The full admin URL of the job. This URL requires a logged in Spruce account to view.

uuidstring uuid required

The UUID of the new job, which must be used for interacting with the job via the API in future. We strongly recommend that you store this UUID in your internal systems.

Example response

{
  "job_reference": "custom_ref_001",
  "url": "https://app.spruce.eco/admin/quotes/d87fd67e-f2dd-4363-80ef-b5e9d60048de",
  "uuid": "d87fd67e-f2dd-4363-80ef-b5e9d60048de"
}

Changes

No recorded changes to this operation across all 1 revision of this API.