Jobs API

Create jobs directly from your website or partner systems.

What Is the Jobs API?

While work requests capture customer enquiries and the Quotes API creates priced quotes, the Jobs API goes further by creating actual jobs ready for scheduling. This is useful for:

• Partner integrations - Referral partners sending confirmed work
• Automated job creation - Creating jobs from approved quotes in external systems
• B2B workflows - Commercial clients with pre-agreed service schedules

How It's Different from Work Requests and Quotes

Feature	Work Requests	Quotes API	Jobs API
Purpose	Capture customer enquiries	Create priced quotes	Create scheduled work
Pricing	None - manual follow-up	Automatic - includes pricing	Optional line items
Result	Request for manual quoting	Ready-to-send quote	Ready-to-schedule job
Use Case	Contact forms	Quote calculators	Partner integrations, B2B

Before You Start

You'll need:

1. An API key from YardPilot
2. A developer to implement the integration
3. Customer details including phone number

What's Required

Customer Information

Field	Required	Description
Name	Yes	Customer's full name
Email	Yes	Customer's email address
Phone	Yes	Customer's phone number

Job Details

Field	Required	Description
Title	Yes	Short description of the job

Address (Required)

Field	Required	Description
Street Line 1	Yes	Street address
Street Line 2	No	Unit number, etc.
City	Yes	Suburb/city
State	Yes	3-letter code (QLD, NSW, etc.)
Postcode	Yes	4-digit Australian postcode

Optional Job Fields

Field	Description
Description	Detailed description of the work
Customer Notes	Notes visible to the customer
Job Type	one-off or recurring
Priority	low, normal, high, or urgent
Estimated Minutes	Expected duration in minutes
Quote ID	Link job to an existing quote (ULID format)

Quote Linking

If you provide a quote_id, the job will be linked to that quote only if:

1. The quote exists
2. The quote belongs to your company

If the quote doesn't exist or belongs to another company, the job will still be created successfully but without the quote link. Invalid quote IDs are logged for debugging.

Scheduling Note

Jobs created via the API are always unscheduled (marked as "schedule later"). You cannot set start or end dates via the API - this must be done in the YardPilot dashboard after reviewing the job.

Line Items (Optional)

Each item needs:

Field	Required	Description	Example
Name	Yes	Service name	"Lawn Mowing"
Description	No	What's included	"Fortnightly mowing service"
Quantity	Yes	How many units	4
Unit Price	Yes	Price per unit in cents	5000 ($50.00)
Unit	No	Unit of measure	"visit", "hour", "sqm"
Tax Rate	No	GST percentage (default 10%)	10.00

Price Format

Prices must be in cents, not dollars. For $50.00, send 5000.

What Happens When a Job Is Created

1. Contact Created - If the email is new, a contact is added to your CRM as a "Lead"
2. Property Created - The address becomes a property record
3. Job Created - A draft job is created with all details
4. Ready to Schedule - Assign crew and schedule visits

Draft Status

Jobs created via API start in "Draft" status. This lets you review them before scheduling.

Technical Details

Endpoint

POST https://app.yardpilot.io/api/v1/integration/jobs

Headers

Content-Type: application/json
X-Company-Key: your_api_key_here

Example Request (Minimal)

{
  "customer_name": "Sarah Johnson",
  "customer_email": "sarah@example.com",
  "customer_phone": "0412 345 678",
  "title": "Lawn Mowing Service",
  "street_line_1": "123 Main Street",
  "city": "Brisbane",
  "state": "QLD",
  "postcode": "4000"
}

Example Request (Full)

{
  "customer_name": "Michael Chen",
  "customer_email": "michael@example.com",
  "customer_phone": "0412 345 678",
  "title": "Weekly Pool Maintenance",
  "description": "Regular pool cleaning and chemical balance",
  "customer_notes": "Gate code: 1234",
  "job_type": "recurring",
  "priority": "normal",
  "estimated_minutes": 60,
  "quote_id": "01JCQR8X9PQZW3Y5K7N4M6B2T8",
  "street_line_1": "42 Oxford Street",
  "street_line_2": "Unit 3",
  "city": "Bulimba",
  "state": "QLD",
  "postcode": "4171",
  "line_items": [
    {
      "name": "Pool Cleaning",
      "description": "Weekly pool cleaning service",
      "sku": "POOL-CLEAN",
      "quantity": 4,
      "unit": "visit",
      "unit_price": 8500,
      "tax_rate": 10.0
    }
  ]
}

Success Response

{
  "message": "Job created successfully",
  "job_id": "01JCQR8X9PQZW3Y5K7N4M6B2T8",
  "job_number": "J-001",
  "job": {
    "id": "01JCQR8X9PQZW3Y5K7N4M6B2T8",
    "number": "J-001",
    "title": "Weekly Pool Maintenance",
    "status": "draft",
    "job_type": "recurring",
    "priority": "normal",
    "estimated_cost": 37400
  }
}

Developer Documentation

For complete technical details including error handling and code examples in JavaScript, PHP, and Python, see our Integration API Developer Guide.

Use Case: Partner Job Creation

Receive confirmed jobs from referral partners:

1. Partner Confirms Work

A referral partner or marketplace confirms a customer booking through their system.

2. Partner Sends Job to YardPilot

The partner's system calls your YardPilot API with the job details:

{
  "customer_name": "Jane Smith",
  "customer_email": "jane@example.com",
  "customer_phone": "0423 456 789",
  "title": "Garden Cleanup - Marketplace Booking",
  "description": "Full garden cleanup including mowing, edging, and green waste removal",
  "estimated_minutes": 120,
  "street_line_1": "88 Park Road",
  "city": "Milton",
  "state": "QLD",
  "postcode": "4064"
}

3. Job Appears in YardPilot

The job appears in your dashboard ready to be assigned to your crew.

Tips for Success

1. Always Include Phone Numbers

Phone numbers are required for jobs - this ensures you can contact the customer about scheduling.

2. Use Clear Titles

Make job titles descriptive so your team understands the work at a glance:

• Good: "Fortnightly Lawn Mowing - Medium Property"
• Bad: "Lawn"

3. Include Duration Estimates

If you know how long the job should take, include the estimated minutes:

{
  "estimated_minutes": 60
}

This helps when scheduling the job in the dashboard later.

4. Test Thoroughly

Use test keys to verify your integration before going live.

How test keys work for jobs:

When you submit jobs using a test key (ypk_test_...):

1. Jobs are validated exactly like live jobs
2. Jobs, contacts, and properties are created with a TEST badge
3. Test data is hidden by default from all lists
4. No notifications are sent to your team
5. All test records are automatically deleted after 24 hours

Testing workflow:

1. Generate a test API key in Settings -> API Keys
2. Configure your integration to use the test key
3. Create test jobs through your integration
4. Check Jobs (with "Show test data" enabled) to verify data
5. Switch to your live API key when ready

Don't Forget to Switch Keys

If you accidentally leave a test key in production, jobs will be marked as test data and automatically deleted after 24 hours. Always verify you're using a live key (ypk_live_...) before launching.

Troubleshooting

Job Not Creating

1. Check required fields - Name, email, phone, title, and full address are required
2. Check phone format - Must be a valid phone number
3. Check address fields - State must be 3 letters, postcode must be 4 digits

Line Item Issues

1. Price in cents - $50 should be 5000, not 50
2. Tax rate format - Use 10.00 for 10%, not 0.10
3. Quantity required - Each line item needs a quantity

Duplicate Jobs

If the same customer + title + address are submitted within 5 minutes, YardPilot returns the existing job instead of creating a duplicate.

Next Steps

• Scheduling Visits - Schedule and assign crews
• Work Requests - For simple contact forms
• Quotes API - Create priced quotes