Skip to main content

API conventions

Partner API endpoints use https://api.workstaff.app/partner/v1/ as their base URL. Requests and responses use JSON unless an endpoint specifies otherwise.

Pagination​

List operations use cursor pagination. The default page size is 100, and page_size can request up to 500 results.

{
  "next": "https://api.workstaff.app/partner/v1/staff/?cursor=opaque-value",
  "previous": null,
  "results": []
}

Follow the next or previous URL without modifying it. Cursor values are opaque and must not be parsed or constructed by clients. A null link means there is no page in that direction.

Errors​

Partner API errors use a common JSON structure:

{
  "code": "validation_error",
  "message": "The request contains invalid fields.",
  "errors": [
    {
      "field": "name.first_name",
      "code": "blank",
      "message": "This field may not be blank."
    }
  ],
  "correlation_id": "request-correlation-id"
}

Use code and field-level error codes for programmatic decisions. Human-readable messages may change. Include the correlation_id when contacting Workstaff about a failed request.

Rate limits​

Rate limits apply separately to each Partner API client. If the API returns 429 Too Many Requests, wait before retrying and respect the Retry-After response header.

Updates and empty values​

For PATCH requests, omitted fields remain unchanged. A null value clears a field only when that field is nullable. Arrays use [] when empty and are never returned as null.