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 typically include a metadata object with total counts:

{
  "metadata": {
    "total": 150,
    "per_page": 25,
    "pages": 6,
    "page": 1
  },
  "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_.

• f_status: Filter by status ID (e.g., f_status=10 for "Work Done").
• f_project: Filter by project ID.
• f_created: Filter by creation date range (often supports start,end or specific dates).

Example: GET /workorders?f_status=10&f_project=55&page=1

Sorting

Use sort_by and sort_direction to order your results.

• sort_by: The field to sort on (e.g., created, status).
• sort_direction: asc or desc.

Example: GET /workorders?sort_by=created&sort_direction=desc

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: