Common workflows

Each workflow lists the calls in order, with the permissions the connection needs. Every create in these workflows should use its own idempotency key.

Schedule a job for a new customer

Permissions: customers:create, customer_locations:create, jobs:create, members:read (their read dependencies are selected automatically).

1. Check whether the customer exists: List customers, filtering by external_reference if your system stored one when it created them.
2. If not, create the customer. Save data.id.
3. Create a location for the job site. Save data.id. Its address is geocoded afterwards; you don't need to wait.
4. Find the technician's member ID with List members.
5. Create the job with customer_id, location_id, a timed schedule and assignee_member_ids.

Through MCP, the same request can be a single sentence: "Create Example Property Services at 100 Example Avenue, Springfield, and schedule an inspection there on 10 November, 9:00–11:00 New York time, assigned to Alex." The client performs these steps with the matching tools.

Add catalog items to a job

Permissions: job_items:create and its dependencies (job_items:read, jobs:read, products:read).

1. Find the product and, if it has several prices, the price ID: List products.
2. Either include the items in items when you create the job, or add them to an existing job.
3. Read the job again to see the updated job_value.

Draft a quote or invoice

Permissions: quotes:create or invoices:create and their dependencies.

1. Find the customer and the products to include.
2. Create the draft: Create a quote or Create an invoice.
3. Review and send it from the FieldTask app. The API creates drafts only; it never sends them, collects payment or accepts quotes.

Invite a team member

Permissions: members:invite and members:read, on a connection whose owner or admin is still eligible to invite.

1. Create an invitation with the person's email address.
2. FieldTask emails the invitation. Track it with Get a member invitation.
3. Once accepted, the person appears in List members and can be assigned to jobs.

Report a member's hours

Permissions: timesheets:read and members:read.

1. Find the member with List members.
2. Read their totals for a date range with Get timesheet totals, or the individual entries with List timesheet entries.

Keep another system in sync

1. Choose webhooks, the event feed, or both.
2. Get a starting cursor, then copy current records with the list endpoints.
3. Apply each change as it arrives by reading the current record. See Event feed.