Idempotency | FieldCamp API

FieldCamp does not currently support server-side idempotency keys. Without care, a retried POST /api/jobs can create a duplicate job.

The recommended pattern: make jobNumber a deterministic, unique string that you generate, and check whether it already exists before creating.

Recommended pattern

1. Choose a unique jobNumber format tied to your source data — for example ACME-{bookingId} or BOOKING-{orderId}-{kind}.
2. Before creating a job, list jobs and filter client-side for that jobNumber.
3. If a match exists, skip the create and return the existing job.
4. Otherwise, create the job.

This pattern lets your caller retry the whole operation safely: the retry finds the existing job and no-ops.

async function findJobByNumber(jobNumber) {
  const { data } = await fc.get('/api/jobs');
  const match = (data.data?.jobs ?? []).find(j => j.jobNumber === jobNumber);
  return match ? (match.id ?? match.recordId ?? match._id) : null;
}

async function createJobIdempotently(jobData, notes) {
  const existing = await findJobByNumber(jobData.jobNumber);
  if (existing) return existing;

  const form = new FormData();
  form.append('jobData', JSON.stringify(jobData));
  form.append('notes', notes);

  const { data } = await fc.post('/api/jobs', form, { headers: form.getHeaders() });
  return data.data.jobId ?? data.data.job.id;
}

Naming your jobNumber

Good jobNumber values are:

• Unique per real-world unit of work. A booking ID. An order number. A case ID from your ticketing system.
• Prefixed with your system name. ACME-, BOOKING-, WC- — so you can tell at a glance where a job came from in the FieldCamp UI.
• Suffixed by kind if you create more than one job per source record. BOOKING-5512-MOVE, BOOKING-5512-RETURN.
• Stable across retries. Never include a timestamp or random suffix — those defeat deduplication.

What about GET and PUT?

GET is idempotent by nature. PUT /api/jobs/{id} is a partial update — the same request twice yields the same state, so retries are safe.

POST /api/clients and POST /api/product-service can create duplicates. The same lookup-then-create pattern applies: for clients, look up by email; for items, look up by name and price.

Roadmap

Server-side idempotency keys (a standard Idempotency-Key request header with deduplication on our side) are on the roadmap. The client-side pattern above will continue to work after that ships.