Developer & Integration Help - Recent Threads

RE: Webhook payload structure for work_order.status_changed

Devon Marsh — Mon, 29 Sep 2025 11:47:00 GMT

Heads up: if you're using the work_order.status_changed event to trigger side effects (notifications, external syncs), watch out for rapid-fire status changes. We've seen cases where a bulk edit or script triggers assigned→in_progress→on_hold→in_progress within seconds. Your webhook handler needs to be idempotent or you'll get race conditions.

We ended up debouncing with a 5-second window keyed on work_order_id + changed_at. YMMV depending on your downstream systems.

Webhook payload structure for work_order.status_changed

Carlos Vega — Sun, 28 Sep 2025 15:15:00 GMT

Need the exact payload structure for work_order.status_changed. Docs show an example but no schema. Specifically:

Is previous_status always present?
What's the timestamp format — ISO 8601 with millis or no?
Are custom fields included or do I need a follow-up API call?

Current handler is breaking on null assignee_id when status goes from assigned → unassigned. Need to know what else can be null.

// What I'm receiving (sanitized):
{
  "event": "work_order.status_changed",
  "timestamp": "2025-09-28T14:32:17.842Z",
  "data": {
    "work_order_id": "wo_...",
    "status": "in_progress",
    "previous_status": "assigned",
    "assignee_id": "usr_...",
    "changed_at": "2025-09-28T14:32:15.000Z"
  }
}

Show me the full schema or point me to OpenAPI/Swagger.

RE: Webhook payload structure for work_order.status_changed

Eli Torres (Staff) — Mon, 29 Sep 2025 09:15:00 GMT

Agreed on OpenAPI. Internal ticket is ENG-4421 — no ETA but it's in the Q4 API polish backlog. I'll poke the team.

For now, here's the validator I use internally (zod) if it helps:

const WebhookPayload = z.object({
  event: z.literal('work_order.status_changed'),
  webhook_id: z.string(),
  timestamp: z.string().datetime(),
  data: z.object({
    work_order_id: z.string(),
    status: z.string(),
    previous_status: z.string().optional().nullable(),
    assignee_id: z.string().nullable(),
    team_id: z.string().nullable(),
    customer_id: z.string(),
    location_id: z.string().nullable(),
    scheduled_start: z.string().datetime().nullable(),
    scheduled_end: z.string().datetime().nullable(),
    changed_at: z.string().datetime(),
    changed_by: z.object({
      type: z.enum(['user', 'system', 'api']),
      id: z.string().nullable()
    })
  })
});

YMMV on the datetime validation — we include millis but not all parsers require them.

RE: Webhook payload structure for work_order.status_changed

Carlos Vega — Sun, 28 Sep 2025 17:31:00 GMT

@eli.torres thanks — null vs omitted was the issue. previous_status missing on new WO caused my validator to throw.

Confirmed changed_by.type === "system" during automated status transitions (SLA breach auto-escalation). id is null as expected.

Still need that OpenAPI spec though. Maintaining hand-rolled validators is brittle.

RE: Webhook payload structure for work_order.status_changed

Leo Nakamura — Sun, 28 Sep 2025 17:08:00 GMT

Worth noting: previous_status can also be null (not just omitted) in legacy event streams. Defensive check:

const prev = payload.data.previous_status ?? null;

Also Setting Up Webhooks has outdated example — missing changed_by entirely. Eli's schema above matches prod.

RE: Webhook payload structure for work_order.status_changed

Eli Torres (Staff) — Sun, 28 Sep 2025 16:42:00 GMT

Hey Carlos — yeah this one tripped me up too when I first looked at it. The docs example is incomplete and I keep meaning to push for a proper JSON Schema. Here's what I can confirm from our side:

Nullable fields (can be null or omitted):

previous_status — omitted entirely on new work orders (no prior state)
assignee_id — null when unassigned
team_id — null when not assigned to a team
scheduled_start / scheduled_end — null when no scheduling

Timestamp format: Always ISO 8601 with milliseconds and Zulu offset (2025-09-28T14:32:17.842Z). The changed_at in your payload is the DB commit time; timestamp is when we fired the webhook (usually 50–200ms later).

Custom fields: Not included in this event. You need to hit GET /v1/work_orders/{id} with ?include=custom_fields if you need them. There's a feature request to optionally include them in webhooks (API v2.1 added it for work_order.created but not status changes yet).

Full schema I'm aware of:

{
  "event": "work_order.status_changed",
  "webhook_id": "wh_...",
  "timestamp": string,  // ISO 8601 with ms
  "data": {
    "work_order_id": string,
    "status": string,           // new status
    "previous_status": string?, // omitted if no prior
    "assignee_id": string?,     // null if unassigned
    "team_id": string?,         // null if no team
    "customer_id": string,
    "location_id": string?,
    "scheduled_start": string?, // ISO 8601
    "scheduled_end": string?,   // ISO 8601
    "changed_at": string,       // when status actually changed
    "changed_by": {             // user or system
      "type": "user" | "system" | "api",
      "id": string?             // null for system
    }
  }
}

The ? denotes optional/nullable. Let me know if you're seeing fields not in that list — we had a brief regression in August where location_id was missing.

RE: Using Make (Integromat) instead of Zapier — gotchas?

Anita Sharma — Fri, 26 Sep 2025 11:30:00 GMT

From a governance perspective, it is worth noting that Make's data residency differs from Zapier. Make offers EU data residency; Zapier does not. If your organization has data localization requirements, this may influence platform selection regardless of functional considerations.

Additionally, Make's audit logging is more comprehensive — i.e., you can export execution logs via API, which may satisfy internal compliance requirements that Zapier's dashboard-only logs do not meet.

Using Make (Integromat) instead of Zapier — gotchas?

Devon Marsh — Thu, 25 Sep 2025 13:30:00 GMT

Hey all — been using Zapier for a while but hit some limits on data transformation and branching logic. Looking at moving a few of our FieldPulse workflows over to Make (Integromat).

Specifically wondering about:

Webhook payload differences — any fields that come through differently?
Authentication refresh — does the OAuth token handling behave the same?
Custom field values in triggers — I saw this thread about Zapier missing custom fields, curious if Make hits the same issue

Also any general YMMV stuff — I've found Make's error handling way more granular which is nice, but the FieldPulse module seems less polished than the Zapier one.

What gotcha am I missing?

RE: Using Make (Integromat) instead of Zapier — gotchas?

Omar Hassan — Fri, 26 Sep 2025 09:15:00 GMT

From a reliability perspective, Make's error handling is indeed more granular — i.e., you can configure specific error routes per module rather than Zapier's all-or-nothing approach.

One edge case to consider: Make's webhook module does not currently support signature verification out of the box (unlike Zapier's "Webhooks by Zapier" which has a raw body option). If you need to verify the X-FieldPulse-Signature header, you'll need to use the HTTP module with "Get request headers" enabled, then run the HMAC verification in a Code module.

Relevant for security posture if you're processing sensitive work order data. The signature verification flow is documented in Setting Up Webhooks — worth implementing if this is customer-facing.

RE: Using Make (Integromat) instead of Zapier — gotchas?

Devon Marsh — Thu, 25 Sep 2025 18:20:00 GMT

Perfect — the v1 vs v2 thing is exactly the kind of detail I needed. Already running into the "run it once to see data" pain, good to know that's expected behavior and not me missing something.

Will likely go HTTP module route for the newer endpoints. Appreciate the confirmation on OAuth refresh too.

RE: Using Make (Integromat) instead of Zapier — gotchas?

Eli Torres (Staff) — Thu, 25 Sep 2025 16:45:00 GMT

Devon — yeah this one tripped me up too when I first looked at it. Leo's right on the custom fields thing, that's a platform limitation on our end not a Zapier/Make thing.

The OAuth refresh is actually smoother in Make in my experience. Their "Connection" model handles token refresh automatically without the extra "Refresh Token" step you need in Zapier. Heads up though: if you're using a custom OAuth app (not the default FieldPulse one in Make's app directory), you'll need to manually configure the token endpoint. That's auth.fieldpulse.io/.../token with grant_type refresh_token.

One gotcha that got me: Make's "FieldPulse" app in the directory is on v1 of our API. If you need v2 features (like the new checklist endpoints), use the generic HTTP module and hit the endpoints directly. The v1 app works fine for work orders and customers, just not the newer stuff.

Also worth noting — Make doesn't have the same "Test Trigger" behavior as Zapier. You often need to run the scenario once to see sample data, which can be annoying when you're building against production. I usually set up a filter early in the scenario to catch only test records while I'm building.

Documentation link for the direct API approach: Using the FieldPulse API

RE: Using Make (Integromat) instead of Zapier — gotchas?

Leo Nakamura — Thu, 25 Sep 2025 14:12:00 GMT

Two things:

Webhook payloads are identical — same JSON structure. The difference is Make parses nested objects differently in the trigger data mapper. Check the "Data structure" settings on your webhook module.
Custom fields: same limitation as Zapier. The custom_fields array is not expanded in trigger payloads. You need a second API call to /work_orders/{id} with include=custom_fields.

See Setting Up Webhooks — the payload examples there apply to both platforms.

RE: Bulk work order import format specification

Omar Hassan — Tue, 23 Sep 2025 14:55:00 GMT

Excellent point regarding ambiguous references. I have confirmed that our customer dataset contains approximately 340 duplicate email records from legacy data quality issues. We will implement a pre-import deduplication pass.

One additional observation: the work_order_number field appears to enforce uniqueness at the account level, not merely within a given import batch. This is the expected behavior, I presume, but it was not explicitly documented. We have historical collisions where our legacy system's sequence reset annually; we will need to namespace these (e.g., WO-2019-0042 → MIG-2019-0042).

Bulk work order import format specification

Omar Hassan — Mon, 22 Sep 2025 14:00:00 GMT

We are preparing to migrate approximately 12,000 historical work orders from our legacy system into FieldPulse. I have reviewed the Bulk Importing Inventory via CSV documentation, but I am seeking clarification on the specific schema requirements for work order imports, as the available documentation appears to focus on inventory rather than work order entities.

Specifically, I would appreciate confirmation on the following points:

Required vs. optional fields: Which fields are mandatory for a successful import? I assume work_order_number, customer_id (or customer_email), and scheduled_date are required, but I would like explicit confirmation.
Date/time formats: The documentation references ISO 8601, but does not specify whether timezone offsets are supported (e.g., 2025-09-22T14:00:00-04:00) or if all timestamps must be normalized to UTC.
Status mapping: Our legacy system uses non-standard status values (e.g., "Dispatched," "In Progress," "Awaiting Parts"). Is there a defined mapping to FieldPulse's internal status enum, or must we pre-transform these values?
Technician assignment: Can we assign technicians via technician_email at import time, or does this require a separate API call post-import?
Custom fields: We have approximately 40 custom fields defined in our legacy system. Are these supported in the bulk import, and if so, what is the expected column naming convention (e.g., custom_field_{id} or cf_{name})?
Validation and error reporting: Does the import process support partial success (i.e., importing valid rows while reporting errors for invalid rows), or is it atomic? What is the granularity of error reporting—row-level, field-level, or batch-level?
Rate limiting and throughput: Are there documented limits on import file size (rows or bytes) and concurrent import operations?

Additionally, I would like to understand whether there is a sandbox or staging environment where we can validate our transformation pipeline before performing the production import. Our migration window is constrained, and we would prefer to avoid iterative correction cycles against production data.

I have attached a sample of our transformed data structure below for reference. Any clarification on the above points would be greatly appreciated.

work_order_number,customer_email,scheduled_date,status,technician_email,custom_field_site_id,custom_field_equipment_type
WO-2019-0042,customer@example.com,2019-03-15T09:00:00,Dispatched,tech@company.com,SITE-442,HVAC-Commercial

RE: Bulk work order import format specification

Devon Marsh — Tue, 23 Sep 2025 11:28:00 GMT

Heads up on a gotcha we hit: the importer validates customer existence by email at import time, but if you have duplicate customers with the same email (e.g., from previous partial migrations or manual entry), the import will fail with AMBIGUOUS_CUSTOMER_REFERENCE even though the email exists.

We had to dedupe our customer base first. The API's /customers endpoint with ?email= returns all matches—worth checking programmatically before your import run.

YMMV, but we ended up doing customer sync via API first, then using customer_id in the work order import rather than email. Eliminated a whole class of reference errors.

RE: Bulk work order import format specification

Leo Nakamura — Tue, 23 Sep 2025 08:12:00 GMT

Supplemental notes from a recent migration:

Custom field keys are case-sensitive and underscore-normalized. "Equipment Type" becomes equipment_type, but if you created it as "Equipment-Type" originally, the key is equipment_type anyway—hyphens become underscores. Verify in the UI.
Technician email matching is case-insensitive but trailing-space sensitive. Strip whitespace in your transform.
Date parsing accepts YYYY-MM-DD without time, assumes 00:00:00 in account timezone. We used this for historical jobs where exact time was lost.

Documentation gaps: Using the FieldPulse API has a more complete field reference than the import docs, oddly.

RE: Bulk work order import format specification

Eli Torres (Staff) — Mon, 22 Sep 2025 20:47:00 GMT

Good catches.

on_hold is API/import-only by default. You can enable it in the UI under Settings → Work Orders → Status Configuration by toggling "Show extended status set." Without that, your ops team will see the order but can't change status to or from on_hold—it'll display as "Unknown Status" which is... not ideal.

Error format is semi-structured. The __import_error column contains pipe-delimited codes and messages like this:

INVALID_CUSTOMER_EMAIL|No customer found with email 'customer@example.com'
REQUIRED_FIELD_MISSING|scheduled_date is required
STATUS_INVALID|Value 'Dispatched' is not a valid status; use 'dispatched'

The prefix before the pipe is stable-ish—we don't change them often, but they're not formally versioned. If you're building automated retry logic, I'd suggest parsing on the pipe and maintaining a lookup table rather than relying on position. The human-readable portion after the pipe occasionally gets tweaked for clarity.

Yeah, I know "semi-structured" is frustrating. There's an open ticket to expose proper JSON error arrays, but it's behind some larger importer refactoring work. I'll bump the thread with your use case—12,000 rows is exactly the scale where machine-readable errors matter.

RE: Bulk work order import format specification

Omar Hassan — Mon, 22 Sep 2025 18:15:00 GMT

Thank you for the comprehensive response, Eli. This is precisely the level of detail I needed.

A follow-up regarding the on_hold status: I note that this status is not exposed in the standard UI dropdown for manual work order creation. Is this status accessible exclusively via import and API, or is there a configuration setting that enables it in the web interface? I want to ensure our operations team can subsequently manage these records without encountering unexpected visibility issues.

Additionally, regarding the __import_error column: is the error message format stable enough for programmatic parsing? Specifically, does it follow a structured format (e.g., JSON-encoded error objects, or machine-readable error codes), or is it free-form natural language intended solely for human review?

RE: Bulk work order import format specification

Eli Torres (Staff) — Mon, 22 Sep 2025 16:34:00 GMT

Hey Omar, great questions—this is exactly the level of detail that makes migrations go smoothly. Let me work through these one by one.

Required fields: You've got the core three right. Minimum viable row needs work_order_number, customer_email (customer_id also works if you've already synced customers), and scheduled_date. Everything else is optional, though I'd recommend including status so you're not left with 12,000 "Draft" orders to update later.

Date formats: Timezone offsets are supported and encouraged—much better than assuming UTC and having 6am jobs show up at the wrong time. The parser handles both 2025-09-22T14:00:00-04:00 and the Zulu format. If no offset is provided, it assumes the account's configured timezone, which has caused some fun surprises in the past.

Status mapping: This is where it gets tricky. FieldPulse's internal enum is draft, scheduled, dispatched, in_progress, completed, cancelled, and on_hold. Your "Dispatched" maps cleanly, "In Progress" → in_progress, but "Awaiting Parts" doesn't have a direct equivalent. Most folks map that to on_hold with a note in the internal comments. There's no automatic fuzzy matching—you'll need to pre-transform.

Technician assignment: Yes, technician_email works at import time, but the technician needs to exist in the system first. The importer won't auto-provision users. If you have multiple technicians per order, use technician_emails (plural) with comma-separated values.

Custom fields: Supported, but the naming convention is custom_{field_key}, not ID-based. You can find the field keys under Settings → Custom Fields → Work Orders—they're the URL-safe slugs, not the display names. So if your field is named "Equipment Type," the column might be custom_equipment_type or custom_equipment_type_2 depending on duplicates.

Validation: Partial success with row-level error reporting. You'll get a downloadable CSV with an __import_error column appended. Atomicity is per batch, and batches are chunked at 500 rows. So if row 501 fails, rows 1-500 still commit.

Limits: 50,000 rows or 10MB per file, whichever comes first. No hard limit on concurrent imports, but we throttle to 2 per account to avoid database contention. If you need more throughput, open a ticket and we can coordinate.

Sandbox: We don't have a public sandbox environment for imports specifically, but I'd recommend creating a trial account under a different email domain for validation. The importer behaves identically, and you can blow it away after testing. Just don't use your production customer/technician emails or you'll get deduplication weirdness.

Your sample looks structurally sound. One heads up: if that 2019 date is representative, check your account's data retention settings—importing very old orders can trigger archival rules you weren't expecting.

Full schema reference is at Bulk Importing Inventory via CSV (yes, the work order section is buried in there—we're fixing that). Also worth reading Duplicate Inventory Items Created During Import for common pitfalls that apply to work orders too.

RE: Scope API key to read-only access

Leo Nakamura — Sun, 21 Sep 2025 14:07:00 GMT

Related: API key rotation with zero downtime covers automated rotation patterns.

Also worth noting — the official Python SDK doesn't expose the underlying HTTP status code cleanly on 403s. You'll need to catch FieldPulseAPIError and inspect error.response.status_code manually.

Scope API key to read-only access

Rachel Nguyen — Sat, 20 Sep 2025 16:15:00 GMT

We are implementing a data warehouse sync using the FieldPulse API and need to adhere to our internal least-privilege security policy. I have confirmed that the current API key we are using has full read/write access to all endpoints.

I have reviewed the following documentation:

API authentication overview (Using the FieldPulse API)
User roles and permissions (Managing User Roles and Permissions)

However, I cannot locate specific instructions for scoping an API key to read-only operations (GET requests only) or restricting access to specific resource types (e.g., work orders and customers only, excluding inventory modifications).

Environment:

FieldPulse account: Enterprise tier
Current API key created: 2025-09-15
Integration framework: Python 3.11, using official FieldPulse Python SDK v2.3.1

Questions:

Does FieldPulse support fine-grained API key permissions (read-only vs. read-write)?
Is it possible to scope a key to specific endpoints or resource types?
If not natively supported, what is the recommended pattern for achieving least-privilege access for automated read-only integrations?

I can reproduce the current full-access behavior consistently across all tested endpoints. Please advise on available configuration options.

RE: Scope API key to read-only access

Fatima Al-Rashid — Sun, 21 Sep 2025 09:22:00 GMT

From a governance perspective, it is worth noting that the workaround described above (using a restricted user role) does not satisfy all compliance frameworks that require cryptographic separation of privileges. In environments subject to SOC 2 Type II or ISO 27001 audits, auditor expectations typically include:

API keys that are explicitly scoped at creation time, not merely restricted by runtime permissions
Immutable audit trails of key creation and scope changes
Automatic key expiration with rotation enforcement

It is also worth noting that the current FieldPulse API key model lacks:

Key expiration dates (keys are valid until manually revoked)
Usage analytics or anomalous access detection
IP allowlisting at the key level

For organizations with strict security requirements, I recommend implementing compensating controls:

Key rotation every 90 days via automated process
Monitoring of all write operations via Audit Logs to detect any unexpected mutations
Network-level restriction via egress filtering if your infrastructure supports it

I have raised this topic with our CISO and would be interested in participating in any customer advisory sessions regarding the Q1 2026 scoped key feature.

RE: Scope API key to read-only access

Eli Torres (Staff) — Sat, 20 Sep 2025 19:15:00 GMT

Awesome, glad that unblocked you. For the beta — shoot me a DM with your account ID and I'll flag you for the early access list when we start private previews. Probably late Q4 2025.

One heads up: the Viewer role blocking writes is Working As Intended™ but not officially guaranteed behavior, since the API key itself still has "full" scope in a sense. I wouldn't build critical security logic around it without monitoring. If someone accidentally bumps that service account to Manager, your sync suddenly has write access.

Consider adding a cheap safety check in your Python wrapper — something like:

def validate_read_only(self, method):
    if method != 'GET' and not self.allow_writes:
        raise ValueError(f"Read-only client rejected {method} request")

Defense in depth, etc etc.

RE: Scope API key to read-only access

Rachel Nguyen — Sat, 20 Sep 2025 18:30:00 GMT

Thank you for the detailed response, Eli. I have confirmed that Option 1 works as described. I created a service account with the "Viewer" role and generated a new API key. I tested the following:

GET /v1/work_orders — returns 200 with expected payload
POST /v1/work_orders — returns 403 with message "User does not have permission to create work orders"

This satisfies our security requirements for the data warehouse sync. I will proceed with this configuration.

I have noted the Q1 2026 roadmap item — is there a public feature request or beta list we can join to track progress on scoped API keys?

RE: Scope API key to read-only access

Eli Torres (Staff) — Sat, 20 Sep 2025 17:42:00 GMT

Hey Rachel — great question, and honestly this is something we could document better. Short answer: we don't currently support fine-grained scopes on API keys. A key is either valid (full access based on the account's feature tier) or it's not.

The auth model right now is basically:

Your API key inherits the permissions of the user account that created it
There's no "read-only" key type or endpoint-level restrictions

That said, for your use case, here are the workarounds I see teams use:

Option 1: Service Account with Restricted User Role

Create a dedicated user account in FieldPulse with the Viewer role (or custom role with "View" permissions only), then generate the API key from that account. The key will still technically be able to call POST/PUT endpoints, but the underlying user permissions will block mutations. You'll get 403s on write attempts, which is ... not elegant, but functional.

Option 2: Reverse Proxy with Request Filtering

Some teams put a lightweight proxy (nginx, AWS API Gateway, etc.) in front of our API that rejects anything except GET requests. Yeah, this is infrastructure you have to maintain, but it gives you surgical control.

What we're actually building

Scoped API keys with explicit read/write and resource-level permissions are on the roadmap for Q1 2026. I can't share the full spec yet, but think along the lines of:

{
  "name": "Data Warehouse Sync",
  "scopes": ["work_orders:read", "customers:read"],
  "allowed_ips": ["10.0.0.0/8"]
}

No promises on exact syntax, but that's the direction.

For now, I'd recommend Option 1 — it's what most of our Enterprise customers do for read-only ETL jobs. Want me to walk through setting up a restricted service account?