Skip to main content
Version: v1

Workstaff Partner API

Getting started​

Workstaff provides a confidential client_id and client_secret for one company. Keep the secret in server-side configuration. Do not expose it in browser or mobile application code, source control, or logs.

Request an access token​

Use the OAuth 2.0 client credentials grant. Authenticate with HTTP Basic authentication and send a form-encoded request to the token endpoint:

curl --request POST "https://api.workstaff.app/oauth/token/" \
  --user "$CLIENT_ID:$CLIENT_SECRET" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "scope=staff:read staff:write"

The response includes an access_token, its lifetime in expires_in, the Bearer token type, and the granted space-separated scope value. Request only the scopes the integration needs:

  • staff:read lists and retrieves staff profiles.
  • staff:write creates and updates staff profiles.

Make the first staff request​

Send the access token in the Authorization header:

curl "https://api.workstaff.app/partner/v1/staff/" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Accept: application/json"

Access tokens are company-specific. A request can access only staff profiles belonging to the company associated with the OAuth client.

Pagination​

Staff lists use cursor pagination. The default page size is 100 and page_size can request up to 500 results. The response contains results, next, and previous; it does not contain a total count. Follow the returned next or previous URL unchanged. Cursor values are opaque and must not be parsed, modified, or constructed by clients.

Errors​

Partner API errors use a common JSON envelope:

{
  "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 for programmatic decisions. Validation failures include field paths in errors; other failures usually return an empty errors array. Include correlation_id when contacting Workstaff about a failed request.

Common statuses are 400 for invalid input, 401 for missing, invalid, or expired credentials, 403 for a missing scope or an account restriction, 404 for an unavailable resource or cursor, 409 for a duplicate conflict, 415 for a non-JSON request, 429 for rate limiting, and 503 when a required service is unavailable. Each operation documents its applicable errors and any operation-specific recovery details.

Authentication​

Security Scheme Type:

oauth2

OAuth Flow (clientCredentials):

Token URL: /oauth/token/

Scopes:

  • staff:read: Read staff profiles through the Partner API

  • staff:write: Update staff profiles through the Partner API