Developer & Integration Help - Recent Threads

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.

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?

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

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.

Subscribe to multiple webhook events with single endpoint

Carlos Vega — Thu, 18 Sep 2025 10:05:00 GMT

Need to route multiple webhook events to one endpoint. Current setup has separate endpoints per event type which is unmaintainable.

Looking at the dashboard I can only add one event per webhook subscription. Is there a way to subscribe to multiple events (work_order.created, work_order.status_changed, invoice.paid) with a single URL?

Payload structure below if relevant:

{
  "event": "work_order.created",
  "data": { ... }
}

Prefer not to manage 15 separate endpoints.

Paginating through large work order lists via API

Leo Nakamura — Mon, 15 Sep 2025 08:45:00 GMT

Pagination behavior on GET /v1/work_orders appears inconsistent when result sets exceed 10k records. Observed:

Using page + per_page parameters
Records 9,001–10,000: returns as expected
Records 10,001+: duplicates from previous pages, gaps, or empty data array

No Link headers present in response. Documentation mentions cursor-based pagination but does not specify parameter names. Questions:

Is offset pagination deprecated for large result sets?
What are the exact cursor parameter names (cursor, after, start_after)?
Is cursor value the id field or a separate token?
Maximum per_page limit?

Tested with:

Account: ~45k work orders
per_page=100 (also tried 50, 200)
Endpoint: /v1/work_orders?status=completed&created_after=2024-01-01

Response structure does not include cursor in body. Example truncated response:

{
  "data": [...],
  "meta": {
    "total": 45231,
    "page": 100,
    "per_page": 100
  }
}

Required fields for POST /work_orders

Leo Nakamura — Fri, 12 Sep 2025 08:30:00 GMT

Documentation lists title as required. Is that the only required field, or are there others I'm missing?

Testing with just title works. Testing with empty body returns 422. Want to confirm before we ship.

Filter work orders by status and date range in single API call

Leo Nakamura — Mon, 08 Sep 2025 12:10:00 GMT

Can GET /v1/work_orders accept multiple filters simultaneously? Specifically:

status (e.g., completed, in_progress)
scheduled_date_from / scheduled_date_to

Documentation implies params are additive but doesn't explicitly confirm. Need to avoid chaining multiple requests for a dashboard view.

Batch updates vs single record API calls

Omar Hassan — Fri, 05 Sep 2025 14:45:00 GMT

The current API documentation suggests that all write operations (POST, PATCH, DELETE) must be performed on individual records. However, for large-scale data synchronization scenarios — e.g., updating status on 10,000+ work orders nightly from an external ERP — this presents significant performance concerns.

Specifically, I am seeking clarification on the following:

Does the FieldPulse API expose any batch or bulk endpoints (e.g., /batch, /bulk, or JSON:API-style compound documents) that would allow multiple records to be modified in a single request?
If not, what is the recommended architecture for high-volume operations? I.e., should clients implement exponential backoff with jitter per RFC 7234, or are there higher rate limits available for authenticated integration partners?
Are there any idempotency guarantees (e.g., Idempotency-Key headers per RFC 7230) to prevent duplicate records in the event of network partition during a long-running batch process?

I have reviewed API Rate Limits and Best Practices, but it does not address the batch semantics question directly. Any guidance on the intended pattern here would be appreciated.

Rate limit on FieldPulse API and handling 429 errors

Omar Hassan — Wed, 03 Sep 2025 11:42:00 GMT

I have been reviewing the API Rate Limits and Best Practices documentation, but I would like to clarify several points regarding the exact semantics of the throttling mechanism.

Specifically:

Is the rate limit enforced per API key, per account, or per IP address? I.e., if multiple services share a single account's API credentials, do they share a single quota?
What are the exact header values returned on a 429 response? I have observed X-RateLimit-Remaining and X-RateLimit-Reset in other systems, but I want to confirm the FieldPulse implementation before implementing client-side logic.
Is the reset window a fixed calendar window (e.g., top of minute) or a rolling window from first request? This materially affects backoff calculations for bursty traffic patterns.
Are there different tiers or limits for read vs. write operations? I.e., does GET /work_orders consume quota identically to POST /work_orders?

I am also interested in any edge cases or failure modes: e.g., if a request is rate-limited, are idempotent retries safe for non-idempotent methods (POST, PATCH) given potential server-side partial processing?

Finally, has anyone benchmarked the actual vs. documented limits? I prefer empirical data over specification when designing resilient systems.

SAML assertion errors after IdP certificate update

Fatima Al-Rashid — Tue, 02 Sep 2025 14:10:00 GMT

We recently completed a scheduled certificate rotation on our Okta tenant per our security policy (certificate valid from 2025-08-15 to 2026-08-15). Following the rotation, a subset of users—approximately 12 of 340—are experiencing authentication failures when attempting to access FieldPulse via SSO.

Error Manifestation

The affected users receive a generic "Authentication failed" message at the FieldPulse login screen after successful authentication at the IdP. I have confirmed that:

The IdP-initiated flow completes successfully on the Okta side (SAML assertion generated, no policy violations)
The SP-initiated flow exhibits identical failure patterns
The discrepancy is not correlated with user role, department, or last login timestamp
Metadata refresh has been performed on both systems

IdP Configuration Details

Identity Provider: Okta Workforce Identity Cloud
SAML Version: 2.0
Binding: HTTP-POST
NameID Format: EmailAddress (urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress)
Signature Algorithm: RSA_SHA256
Certificate Chain: Single certificate, no intermediates

From a governance perspective, I am particularly concerned that the failure is selective rather than universal. This suggests a potential mismatch in attribute mapping or certificate validation logic that is not immediately apparent in the standard integration documentation.

It is worth noting that our previous certificate rotation (August 2024) proceeded without incident using identical procedures.

I have captured SAML assertion samples from both successful and failed authentications. The differences appear minimal, though I observe that the failed assertions contain an additional saml:AuthnContextClassRef node that was not present in our prior configuration. I am uncertain whether FieldPulse's SAML implementation enforces strict schema validation that might reject assertions with this element.

Requesting guidance on:

Whether FieldPulse maintains certificate pinning that would require explicit update on the service provider side
Any known issues with AuthnContextClassRef handling in the current SAML implementation
Recommended debugging steps to capture SP-side validation errors (currently obscured by generic error messaging)

Ticket reference: FP-SAML-20250902-001

Deep-link into specific work order from external app

Carlos Vega — Sat, 30 Aug 2025 12:25:00 GMT

Need to deep-link from our internal dashboard directly into a specific work order in FieldPulse mobile app. URL scheme documentation is sparse.

Tried fieldpulse://work_orders/{id} — no response. Also fieldpulse://app/work_orders/{id}.

What's the actual URL scheme? Need this working for iOS and Android.

How do I verify webhook signature in Node.js?

Carlos Vega — Fri, 29 Aug 2025 10:05:00 GMT

Need to verify webhook signatures in Node. Docs mention HMAC-SHA256 but no code example. Payload I'm getting:

{
  "event": "work_order.status_changed",
  "timestamp": "2025-08-29T09:45:00Z",
  "data": { ... }
}

Header is X-FieldPulse-Signature. What's the exact algorithm? Raw body or JSON.stringify()? Case-sensitive key name?

Zapier: trigger on work order status 'Completed' only

Brandon Okafor — Mon, 25 Aug 2025 13:00:00 GMT

We need Zapier to fire only when a work order hits "Completed" — not on every status change. Right now we're getting flooded with triggers on "In Progress", "On Hold", etc.

Is there a way to filter this in the FieldPulse trigger itself, or do I need to add a Zapier filter step? My team can't move forward on the customer notification workflow until we nail this down.

Webhook payload missing custom fields — expected?

Devon Marsh — Fri, 22 Aug 2025 12:35:00 GMT

Hey all — running into something that feels like a bug but might just be a known limitation.

I've got a webhook set up for work_order.status_changed and I'm noticing that custom field values aren't showing up in the payload. The standard fields are all there (id, status, assignee_id, customer, etc.) but the custom_fields object is either empty or just... not present? Hard to tell since the key itself is missing.

I've confirmed the custom fields have values in the UI, and they're showing up fine when I hit the REST API directly with a GET on the same work order. So the data exists, it's just not making it into the webhook payload.

Is this expected behavior? I didn't see it called out explicitly in the webhook setup docs, though I might have missed something. If this is a limitation, worth noting that it makes the webhook a lot less useful for our integration — we'd need to follow up with an API call every time just to get the full picture.

For what it's worth, I'm seeing this on both v1 and v2 webhook endpoints. YMMV but figured I'd flag it.

Webhook retry behavior on failed deliveries

Carlos Vega — Mon, 18 Aug 2025 10:20:00 GMT

Seeing inconsistent delivery on our webhook endpoint. Some events arrive 3-4 times. Need to understand:

What's the retry policy? Exponential backoff or fixed intervals?
How many attempts before FieldPulse gives up?
Is there a dead letter queue or visibility into failed deliveries?

Currently returning 500 on purpose for testing — seeing retries come in at weird intervals. No docs on this.

Also: what's the idempotency key situation? Need to dedupe on our end.

API pagination skipping records at page boundaries

Leo Nakamura — Thu, 14 Aug 2025 08:55:00 GMT

Observed behavior:

Fetching /v1/work_orders with limit=100
Using cursor from next_cursor in response
Page 1 returns records A–J (IDs: 1001–1100)
Page 2 returns records B–K (IDs: 1101–1200), but record A from page 1 never appears on page 2
After ~10 pages, total count is 40 short of expected

Reproduction:

GET /v1/work_orders?limit=100&cursor=eyJpZCI6MTEwMH0=
# response
{
  "data": [...],
  "next_cursor": "eyJpZCI6MTIwMH0=",
  "has_more": true
}

Timestamp ordering in DB appears stable. No concurrent deletes during fetch. Same behavior observed with customers endpoint.

Documentation states cursor is "opaque" — need to know if implementation is timestamp-based vs ID-based. Gap suggests records with identical sort values are being dropped at boundary.

API returning 500 on nested custom field expansion

Carlos Vega — Tue, 12 Aug 2025 09:50:00 GMT

Getting consistent 500s when trying to expand custom fields on /work_orders. Request works fine without expansion.

GET /v1/work_orders?expand=custom_fields.customer_preferences&limit=50

Response:

HTTP/1.1 500 Internal Server Error
{"error": "internal_server_error", "request_id": "req_7a8f9e2d1c4b"}

Works:

GET /v1/work_orders?expand=assignee,customer&limit=50

Same behavior on jobs endpoint. Custom fields exist and are populated in UI.

req_7a8f9e2d1c4b, req_8b3c0a5f2e9d, req_9d1e4f7a3b8c — all from last 2 hours.

How do I authenticate with the FieldPulse API using OAuth?

Carlos Vega — Tue, 12 Aug 2025 09:23:00 GMT

Need OAuth flow for API access. Docs mention authorization code but no example. Is it standard PKCE or client credentials? What endpoints?

Also need token refresh details — expiry time, refresh token validity.

Testing webhooks locally without public URL

Carlos Vega — Fri, 08 Aug 2025 16:20:00 GMT

Need to test webhook payloads on localhost. Currently using ngrok but connection drops after 2 hours on free tier. Looking for alternatives that don't require public deployment.

Specifically:

Need stable tunnel for multi-day testing
Must inspect raw POST body for signature verification
Running Node.js handler locally

What are people using? Cloudflare Tunnel? LocalStack? Something else?

Create work order and assign technician in single API call?

Devon Marsh — Tue, 05 Aug 2025 11:30:00 GMT

Hey folks — working on an integration where we're creating work orders from an external scheduling system. Right now I'm making two calls: POST to /work_orders to create, then PATCH to update the assignee_id.

Wondering if there's a way to do this in one shot? I tried including assignee_id in the POST body but got a 422 with "assignee cannot be set during creation."

Is this a hard limitation or am I missing something in the payload structure? Would be nice to cut the round-trip latency here.

cc similar OAuth question for context on how I'm authenticating these calls.

QuickBooks tax rate not applied correctly on sync

Brandon Okafor — Mon, 04 Aug 2025 14:50:00 GMT

We're seeing an issue where invoices synced from FieldPulse to QuickBooks Online are coming through with the wrong tax rate. In FieldPulse, we have a 7.25% rate configured for California jobs, but QBO is applying 8.75% instead. This is creating discrepancies on every invoice and my finance team is having to manually adjust each one. I checked the tax rate mapping in the integration settings and it looks correct on our end. The sync is going through without errors, so I'm not sure where the breakdown is happening. Has anyone else run into this? Need to get this resolved before our next billing cycle.

Sandbox environment for API development

Omar Hassan — Fri, 01 Aug 2025 09:40:00 GMT

Before we commit to building our integration against the production API, we need to understand the availability and characteristics of any sandbox or test environment.

Specifically:

Is there a dedicated sandbox environment with isolated data, or should we use a production account with test data?
If a sandbox exists, does it mirror production API versions and behavior (e.g., rate limits, webhook delivery semantics)?
Are there restrictions on data persistence or account longevity that would affect our CI/CD pipeline testing?
Does the sandbox support the full OAuth flow, including refresh token rotation?

We are particularly concerned with the fidelity of webhook delivery and idempotency guarantees, as our integration depends on reliable event ordering for work order state transitions.

References to relevant documentation or RFC-style specifications would be appreciated.

Zapier trigger not passing custom field values

Mike Dolan — Thu, 31 Jul 2025 09:55:00 GMT

We've got a Zap set up that triggers when a work order status changes. The trigger fires fine, but the custom fields we added to the work order aren't showing up in the payload. Just the standard fields.

Need these values to pass into our CRM. Is this a known limitation or am I missing a configuration step somewhere?

Import customer list without creating duplicates

Anita Sharma — Mon, 28 Jul 2025 15:40:00 GMT

I am preparing to import approximately 12,000 customer records from our legacy CRM into FieldPulse. I have reviewed the bulk import documentation and have a concern regarding duplicate prevention.

Our legacy system contains multiple entries for the same customer due to historical data quality issues. I have confirmed that:

Approximately 2,300 records share phone numbers with at least one other record
Approximately 1,800 records share email addresses with at least one other record
Approximately 890 records have matching first name, last name, and street address but different contact methods

My questions are as follows:

What match key(s) does the FieldPulse import process use to identify potential duplicates?
Is there a configurable merge rule set, or is deduplication handled automatically according to a fixed hierarchy?
Can I specify which record should be considered "master" when duplicates are detected (e.g., most recent updated date, most complete data)?
Does the import provide a preview or dry-run option showing which records would be merged versus created as new?
Are there any constraints on which fields can be used as custom match keys?

I have noted that the import template includes columns for "Customer ID (External)" — it is not clear whether this field participates in deduplication logic or is strictly for reference.

Prior to executing this import, I require a reproducible process that does not create duplicate customer records, as remediation would be operationally costly.

Environment details: I will be using the web interface bulk import function, not the API, for this operation. Our account is on the Enterprise tier.