Visits | FieldCamp API

The FieldCamp Visits API represents scheduled on-site appearances for a job. A single job may have one visit (a quick service call) or several visits chained together (a delivery followed by a collection, a diagnostic followed by a repair, or a multi-day install). The v1 endpoints expose the full visit lifecycle — from creation through dispatch, arrival, completion, and cancellation — and integrate with FieldCamp's AI Dispatcher and live team tracking.

When to create visits explicitly

For most simple jobs, FieldCamp auto-generates a visit from the job's time window when you POST /api/v1/jobs with visits: []. Create visits explicitly via POST /api/v1/visits when you need:

• More than one visit per job — e.g. a two-stop install, or a return trip for a part that was on backorder.
• Explicit control over scheduledStart / scheduledEnd — instead of inheriting the job's window.
• A different team or technician than the parent job — e.g. the estimator visits first, then the install crew.
• Unscheduled or anytime visits — placeholders that sit on the unscheduled queue until your dispatcher assigns a slot.
• Different serviceDuration — useful when one stop is long (an install) and another is short (a follow-up walkthrough).

Visit lifecycle and visitStatus

Every visit moves through a defined lifecycle. The visitStatus field is the single source of truth and powers the dispatch calendar, live tracking, and reporting. You can filter GET /api/v1/visits?visitStatus=... by any of the eight states below — and pass multiple values to fetch several at once.

See Job and visit statuses for the parent-job mapping of these states.

Fields

• jobId — the parent job, returned from POST /api/v1/jobs.
• scheduledStart / scheduledEnd — UTC ISO-8601 datetimes. Omit both with unscheduled: true.
• teamId[] — an array of user IDs from GET /api/v1/team. The Visits API accepts multiple assignees per visit, so a two-person crew is a single visit, not two. Replaces the old single technicianId field.
• serviceDuration — the planned on-site duration in minutes. Used by the dispatcher to fit the visit into the team's capacity even when scheduledEnd is not yet pinned.
• unscheduled — boolean. When true, the visit is created without a time slot and sits on the dispatch queue.
• anyTime — boolean. Marks the visit as flexible-within-day (no fixed hour). The dispatcher will slot it into the first open window.
• visitStatus — one of the eight values in the lifecycle table above.

Creating a visit

Listing and filtering visits

GET /api/v1/visits supports filtering by visitStatus, teamId, jobId, and date range. Common patterns:

• Today's active work — ?visitStatus=in_transit,arrived,in_progress,paused.
• Backlog for a dispatcher — ?visitStatus=unscheduled.
• A crew's day — ?teamId=usr_abc&from=2026-05-29T00:00:00Z&to=2026-05-29T23:59:59Z.
• What got cancelled last week — ?visitStatus=cancelled&from=...&to=... for churn analysis.

Pair these queries with FieldCamp's route optimization and AI Dispatcher to keep the day moving when statuses change in real time.

Updating and cancelling visits

PUT /api/v1/visits/:id lets you reschedule, reassign, change duration, or push a status forward. Common updates include:

• Reassigning a visit to a different teamId[] after a call-out.
• Bumping scheduledStart/scheduledEnd when a prior visit overruns.
• Setting visitStatus: "cancelled" with a reason note when the customer cancels.

DELETE /api/v1/visits/:id permanently removes a visit. Use this for clearing test data or removing a duplicate that was created in error — it does not preserve audit history. For a customer-facing cancellation, prefer PUT with visitStatus: "cancelled" so the timeline keeps the record.

Endpoints

curl -X GET "https://api.fieldcamp.ai/api/v1/visits"

{
  "success": true,
  "data": {
    "visits": [
      {
        "jobId": "string",
        "scheduledStart": "2019-08-24T14:15:22Z",
        "scheduledEnd": "2019-08-24T14:15:22Z",
        "technicianId": "string",
        "id": "string",
        "visitStatus": "scheduled",
        "createdAt": "2019-08-24T14:15:22Z"
      }
    ]
  }
}

{
  "success": false,
  "error": "Invalid or expired token"
}

curl -X POST "https://api.fieldcamp.ai/api/v1/visits" \  -H "Content-Type: application/json" \  -d '{    "jobId": "job_abc123",    "scheduledStart": "2026-05-01T09:00:00.000Z",    "scheduledEnd": "2026-05-01T17:00:00.000Z",    "technicianId": "user_xyz789"  }'

{
  "success": true,
  "data": {
    "visitId": "string",
    "visit": {
      "jobId": "string",
      "scheduledStart": "2019-08-24T14:15:22Z",
      "scheduledEnd": "2019-08-24T14:15:22Z",
      "technicianId": "string",
      "id": "string",
      "visitStatus": "scheduled",
      "createdAt": "2019-08-24T14:15:22Z"
    }
  }
}

{
  "success": false,
  "error": "jobNumber is required"
}

{
  "success": false,
  "error": "Invalid or expired token"
}

curl -X PUT "https://api.fieldcamp.ai/api/v1/visits/string" \  -H "Content-Type: application/json" \  -d '{}'

{
  "success": true,
  "data": {
    "visit": {
      "jobId": "string",
      "scheduledStart": "2019-08-24T14:15:22Z",
      "scheduledEnd": "2019-08-24T14:15:22Z",
      "technicianId": "string",
      "id": "string",
      "visitStatus": "scheduled",
      "createdAt": "2019-08-24T14:15:22Z"
    }
  }
}

{
  "success": false,
  "error": "Invalid or expired token"
}

curl -X DELETE "https://api.fieldcamp.ai/api/v1/visits/string"

{
  "success": false,
  "error": "Invalid or expired token"
}

Best practices

Troubleshooting

Why am I getting 400: technicianId is not allowed? The legacy technicianId field was replaced by teamId[]. Convert single IDs to a one-element array.

My visit was created but doesn't appear on the calendar. Check visitStatus. If it's unscheduled or anyTime: true, it lives on the unscheduled queue until a slot is set. The dispatch calendar has a separate panel for these.

Can I move a completed visit back to in_progress? Only by re-opening it from the FieldCamp UI. The API will reject the direct status transition to protect reporting integrity.

How do I assign a two-person crew? Pass both user IDs in teamId[] on the same visit. Do not create two visits — that double-counts the work in capacity planning.

Does deleting a visit delete the job? No. Visits and jobs are separate resources. Deleting all visits on a job leaves the job in place; FieldCamp will prompt a dispatcher to add a new visit or close the job.

FAQs

What's the difference between scheduled and arrived? scheduled means a time slot exists. arrived means the technician is physically on-site (confirmed via GPS or a manual mobile action) but hasn't started work yet.

Can the AI Dispatcher create visits on my behalf? Yes. When you submit a job for AI dispatch, it creates the visit, assigns the team, and sets the status — all via the same v1 endpoints.

Are unscheduled visits counted against capacity? Only after they are assigned and a scheduledStart is set. Until then they live in the backlog and don't reserve a slot.

Related articles

• Jobs | FieldCamp API
• Team | FieldCamp API
• Webhooks | FieldCamp API
• Rate limits | FieldCamp API
• Idempotency | FieldCamp API
• Errors | FieldCamp API
• Job and visit statuses in FieldCamp
• How to use the dispatch calendar
• Route optimization in FieldCamp
• How AI Dispatcher works under the hood
• Multi-day jobs overview
• Submitting a job for AI dispatch