Jobs

A job is the core unit of work in Zoop — a visit, task, or project you perform for a customer. This page covers the five API tools that let you list, fetch, create, update, and cancel jobs.

Jobs move through four statuses: unscheduled → scheduled → done (or cancelled at any point). See the status machine section for the full rules.

Required scopes

Every API call in Zoop needs a scope — a permission that says what the token is allowed to do. You set scopes when you create an API key or start an OAuth flow.

write:jobs does not imply read:jobs. Grant both if your integration needs to read and write jobs. See Scopes for the full scope catalog.

User actor requirement

Some tools require a user actor — a token that is tied to a specific Zoop user (either an OAuth access token or a user-bound API key). This is different from a tenant key (prefix zoop_tk_), which belongs to the account as a whole and has no user identity attached.

jobs.create, jobs.update, and jobs.cancel require a user actor. If you call them with a tenant key, you will get an invalid_input error. See API keys to understand the difference and pick the right token type.

Tools

jobs.list

Returns one page of jobs for the tenant. Results are sorted by scheduled_start ascending (jobs with no start time come last), then by created_at descending. Each page holds up to 20 jobs.

Scope: read:jobs

Response fields:

jobs.get

Fetches the full record for a single job by its ID. The response includes line items, team assignments, and up to 50 media previews (photos and videos attached to the job).

Scope: read:jobs

Returns a not_found error if the job ID does not exist in this tenant.

Response fields:

jobs.create

Creates a new job. Requires a user actor (see user actor requirement above).

Scope: write:jobs

Returns the newly created job row. The shape matches jobs.get, except the nested job_line_items, job_assignments, and job_media arrays are not included.

jobs.update

Partially updates a job. Only the fields you send are changed — you do not need to resend the whole record. Requires a user actor (see user actor requirement above).

Scope: write:jobs

Returns the updated job row.

jobs.cancel

Cancels a job by setting its status to cancelled. The job record is preserved in full — history, line items, and assignments all stay intact. Requires a user actor (see user actor requirement above).

Scope: write:jobs

Returns the updated job row with status: "cancelled".

Example: create a scheduled job

This example creates a job for a customer and assigns it to a team member. Replace the UUIDs with real IDs from your tenant — you can get a customer ID from customers.list and a user ID from your Zoop account settings.

curl -X POST https://app.zoop.example/api/mcp \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "jobs.create",
      "arguments": {
        "title": "Replace kitchen faucet",
        "customer_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "description": "Customer reported dripping cold side. Bring 1/2-inch compression fittings.",
        "scheduled_start": "2026-06-16T09:00:00Z",
        "scheduled_end": "2026-06-16T11:00:00Z",
        "assigned_user_ids": ["f9e8d7c6-b5a4-3210-fedc-ba9876543210"],
        "line_items": [
          {
            "description": "Labor — faucet replacement",
            "unit_price": 95.00,
            "quantity": 2
          },
          {
            "description": "Kitchen faucet (customer-supplied)",
            "unit_price": 0,
            "quantity": 1
          }
        ]
      }
    }
  }'

const response = await fetch('https://app.zoop.example/api/mcp', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'tools/call',
    params: {
      name: 'jobs.create',
      arguments: {
        title: 'Replace kitchen faucet',
        customer_id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
        description: 'Customer reported dripping cold side. Bring 1/2-inch compression fittings.',
        scheduled_start: '2026-06-16T09:00:00Z',
        scheduled_end: '2026-06-16T11:00:00Z',
        assigned_user_ids: ['f9e8d7c6-b5a4-3210-fedc-ba9876543210'],
        line_items: [
          {
            description: 'Labor — faucet replacement',
            unit_price: 95.00,
            quantity: 2,
          },
          {
            description: 'Kitchen faucet (customer-supplied)',
            unit_price: 0,
            quantity: 1,
          },
        ],
      },
    },
  }),
})

const result = await response.json()
// result.result contains the new job row

What happens:

Status machine

Jobs move through four statuses. Zoop sets status for you in many cases — you rarely need to set it explicitly.

Neither done nor cancelled locks the job permanently. You can reopen a done or cancelled job by patching status back to scheduled or unscheduled.

Error reference

See Errors for the full error shape and HTTP status codes.

Related pages

• Job series — create and manage recurring job templates.
• Invoices — turn a completed job into an invoice.
• Quotes — jobs can be created from approved quotes.
• Catalog items — link line items to your pricebook.
• Scopes — full scope catalog and token requirements.