API Basics

Understanding these core concepts will help you integrate more effectively and avoid common pitfalls.

Pagination

Most list endpoints (like GET /workorders) are paginated to improve performance. The API standardizes pagination using page and per_page query parameters.

Response Metadata

Paginated responses include a metadata object with counts and active state:

{
  "metadata": {
    "total": 150,
    "per_page": 25,
    "pages": 6,
    "page": 1,
    "sort": "schedule",
    "order": "asc",
    "list": "workorders_all"
  },
  "results": [ ... ]
}

Filtering & Sorting

The API supports powerful filtering and sorting capabilities to help you find the exact data you need.

Filtering (f_)

Filters are passed as query parameters prefixed with f_. For GET /workorders, always include a list parameter to scope results to a lifecycle stage, and pass sticky=false to keep each request self-contained.

• f_state: Filter by state abbreviation (e.g., TX, CA).
• f_project: Filter by project ID.
• f_created_date: Filter by creation date or range (e.g., 2025-01-01 or 2025-01-01,2025-03-31).

Example: GET /workorders?list=workorders_all&f_project=55&f_state=TX&sticky=false

For the full list of available filters, see Search & Filter Work Orders.

Sorting

Use sort and order to control result ordering.

• sort: The field to sort on. Valid values: id, title, schedule, status, pay, created_date.
• order: asc or desc.

Example: GET /workorders?list=workorders_all&sort=created_date&order=desc&sticky=false

Content Types

• Requests: Must use Content-Type: application/json (unless uploading files).
• Responses: All responses are returned as application/json.

Date & Time

Field Nation uses a specific object structure for timestamps to explicitly handle Timezones. You must typically send dates in this format.

"start": {
   "utc": "2023-11-07 13:00:00"
}

• Format: YYYY-MM-DD HH:mm:ss (24-hour format).
• Timezone: Always convert to UTC before sending. The API handles the conversion to local time based on the work order's location.

Rate Limiting

To ensure fair usage and stability, the API enforces rate limits. If you exceed the limit, you will receive a 429 Too Many Requests response.

• Best Practice: Implement exponential backoff when you encounter a 429 or 5xx error.
• Webhooks: Prefer using Webhooks for real-time updates instead of polling the API, to save your rate limit quota.

Error Handling

Standard HTTP status codes are used to indicate success or failure. For detailed resolution steps, see the Troubleshooting guide.

Troubleshooting

If you encounter issues, check these common pitfalls: