openapi: 3.0.3 info: title: Hubstaff Activities Members API description: 'The Hubstaff API v2 provides programmatic read and write access to Hubstaff''s time tracking, timesheet, workforce management, and project management data - organizations, members, teams, projects, tasks, clients, activities (10-minute tracked time blocks with activity percentages), daily activity aggregates, time entries, timesheets and approvals, time off requests/policies/balances, attendance schedules and shifts, screenshots, app and URL usage, invoices, team payments, and webhooks. Authentication uses OpenID Connect / OAuth 2.0 through Hubstaff Account (https://account.hubstaff.com). For server-side scripts, create a personal access token at https://developer.hubstaff.com/personal_access_tokens - the PAT acts as an OAuth refresh token (90-day expiry) that you exchange for short-lived access tokens at https://account.hubstaff.com/access_tokens. Send the access token as a Bearer token on every request. Rate limit: authenticated users are allowed 1,000 requests per hour per application; individual requests time out after 30 seconds. All requests must use HTTPS. Collection endpoints use cursor pagination via page_start_id and page_limit. This document is a curated OpenAPI 3.0 rendering of the live Swagger 2.0 definition published at https://api.hubstaff.com/v2/docs, covering the primary resource areas; consult the live definition for the complete surface (insights, job sites, budgets, overtime policies, integrations, and more).' version: '2.0' contact: name: Hubstaff Developer Portal url: https://developer.hubstaff.com/ termsOfService: https://hubstaff.com/terms servers: - url: https://api.hubstaff.com description: Hubstaff production API (paths include the /v2 prefix) security: - oauth2: - hubstaff:read - personalAccessToken: [] tags: - name: Members description: Organization membership - list, add, and update members and their pay/bill rates. paths: /v2/organizations/{organization_id}/members: get: operationId: getV2OrganizationsOrganizationIdMembers tags: - Members summary: List organization members description: "Returns a collection of members for the given organization.\n\nResults can be filtered by search, user IDs, membership role, and date range.\n\n*trackable* - Whether the user can track time. This is one of 3 values\n- *false* -- meaning tracking has been explicitly disabled for this user regardless of their role\n- *true* -- meaning they are allowed to track time\n- *viewer* -- meaning they are allowed to track time, however as they are only a project viewer (or no\n memberships) they implicitly can not track on any project\n\n*membership_role* - The basic role in this organization\n- *owner* - An owner of the organization. This member can do anything within the organization.\n- *manager* - An manager of the organization. This member can do anything within the organization\n except things to do with money. (payroll, invoicing, account billing)\n- *user* - (By project). A member of the organization where permissions are defined by their project memberships\n\n*effective_role* - represents an effective role that combines a member's organization role and their project roles\n- *organization_owner* - The member is an organization owner\n- *organization_manager* - The member is an organization manager\n- *project_manager* - The member is an organization user and a manager on all projects and teams\n- *project_user* - The member is an organization user and a user on all projects and teams\n- *project_viewer* - The member is an organization user and a viewer on all projects and teams\n- *by_project* - The member is an organization user and has mixed roles on their projects and team memberships (advanced in the web UI)\n- *unassigned* - The member has no assigned role and no project memberships (No role in the web UI)\n\n*profile* - The profile information for the user. Only organization owners and managers may see this information.\n- *custom_fields* - The custom fields, defined for organization, in format of \"key\": \"value\". The meaning\n of keys is defined in organization.member_profile_fields.\n\n**Filtering by dates:**\n\nYou can filter members by when they were added to the organization using the `created_at` parameter:\n- Use `created_at[start]` to get members added on or after a specific date\n- Use `created_at[stop]` to get members added before a specific date\n- Use both to get members added within a date range\n\nYou can also filter by when membership was last updated using the `updated_at` parameter:\n- Use `updated_at[start]` to get members updated on or after a specific date\n- Use `updated_at[stop]` to get members updated before a specific date\n- Use both to get members updated within a date range" parameters: - name: organization_id in: path required: true schema: type: integer format: int32 - name: page_start_id in: query description: The page start ID. schema: type: integer format: int32 default: 0 - name: page_limit in: query description: The default page size schema: type: integer format: int32 default: null - name: search[email] in: query description: An email to search for members schema: type: string - name: search[name] in: query description: A name to search for members schema: type: string - name: include_removed in: query description: Include members that were removed from the organization schema: type: boolean default: false - name: include_profile in: query description: Include member profile information schema: type: boolean default: false - name: include_projects in: query description: Include project memberships for this member schema: type: boolean default: false - name: project_statuses in: query description: Filter projects by status when include_projects=true schema: type: array items: type: string enum: - active - archived - deleted - name: include_limits in: query description: Include member limits information schema: type: boolean default: false - name: membership_roles in: query description: Search by membership role schema: type: array items: type: string enum: - owner - manager - user - unassigned - name: created_at[start] in: query description: Start date for created_at filter (inclusive) schema: type: string format: date-time - name: created_at[stop] in: query description: End date for created_at filter (exclusive) schema: type: string format: date-time - name: updated_at[start] in: query description: Start date for updated_at filter (inclusive) schema: type: string format: date-time - name: updated_at[stop] in: query description: End date for updated_at filter (exclusive) schema: type: string format: date-time - name: user_ids in: query description: List of user IDs schema: type: array items: type: integer format: int32 - name: include in: query description: Specify related data to side load. schema: type: array items: type: string enum: - users - projects responses: '200': description: A list of members '400': description: Invalid parameters '401': description: Unauthorized '403': description: API access is only for organizations on an active plan '404': description: Could not find record '429': description: Rate limit exceeded post: operationId: postV2OrganizationsOrganizationIdMembers tags: - Members summary: Create organization member description: 'Creates a new user and adds them to the organization as a member. Returns the created member. Available roles: - organization_manager - Organization manager - project_manager - Project manager - project_user - Project user - project_viewer - Project viewer Available pay periods: - none - Disables automatic payments - weekly - Pay users weekly - twice_per_month - Pay users twice a month - biweekly - Pay users bi-weekly - monthly - Pay users monthly' parameters: - name: organization_id in: path required: true schema: type: integer format: int32 requestBody: required: true content: application/json: schema: type: object description: Request payload. See the live Hubstaff API reference (https://api.hubstaff.com/v2/docs) for the full schema. responses: '201': description: A member '400': description: Invalid parameters '401': description: Unauthorized '403': description: API access is only for organizations on an active plan '404': description: Could not find record '429': description: Rate limit exceeded /v2/organizations/{organization_id}/update_members: put: operationId: putV2OrganizationsOrganizationIdUpdateMembers tags: - Members summary: Update organization members description: 'Updates organization members. Returns {success: true} on success. Only pass in the members you want to change. Available roles: - user - Member role determined by project membership - manager - Organization manager - owner - Organization owner - remove - Removes user from organization (and all projects/teams) Limits: Specify full limits config. Missing limits will be removed. Empty "limits" removes all limits. Projects: Specify project memberships to change. Available project roles: viewer, user, manager, remove. Metadata: Only specify keys to change. Non-existent keys are created. Use null to remove a key. Key requirements: - 2-30 characters - Lowercase letters, numbers, and underscores only Value requirements: - Valid UTF-8 string - Maximum 200 characters Batch size: Up to 150 members per request. Larger requests are rejected with HTTP 400 and code "too_many_members".' parameters: - name: organization_id in: path description: Organization ID required: true schema: type: integer format: int32 requestBody: required: true content: application/json: schema: type: object description: Request payload. See the live Hubstaff API reference (https://api.hubstaff.com/v2/docs) for the full schema. responses: '200': description: Updated successfully '400': description: Invalid parameters '401': description: Unauthorized '403': description: API access is only for organizations on an active plan '404': description: Could not find record '429': description: Rate limit exceeded /v2/teams/{team_id}/members: get: operationId: getV2TeamsTeamIdMembers tags: - Members summary: List team members description: 'Returns a collection of members for the given team. Membership roles: - manager - Can track time, view all data, change settings, and manage membership - user - Can track time and view only their own data - viewer - Can view reports but cannot make changes' parameters: - name: team_id in: path description: Team ID required: true schema: type: integer format: int32 - name: page_start_id in: query description: The page start ID. schema: type: integer format: int32 default: 0 - name: page_limit in: query description: The default page size schema: type: integer format: int32 default: null - name: include in: query description: Specify related data to side load. schema: type: array items: type: string enum: - users responses: '200': description: A list of members '400': description: Invalid parameters '401': description: Unauthorized '403': description: API access is only for organizations on an active plan '404': description: Could not find record '429': description: Rate limit exceeded /v2/projects/{project_id}/members: get: operationId: getV2ProjectsProjectIdMembers tags: - Members summary: List project members description: 'Returns a collection of members for the given project. Results can be filtered by search, user IDs, membership role, and date range. *membership_role* - The permission role the member has in this project - *manager* - An manager can track time, see data for any member within the project, can change settings, and manage membership within the project - *user* - A user can track time against the project and see only their own data within the project - *viewer* - A viewer can access reports based on data for any member within the project but can not change anything **Note**: A member must have membership within a project in order to track on that project, even if they are an organization owner or manager **Filtering by dates:** You can filter members by when they were added to the project using the `created_at` parameter: - Use `created_at[start]` to get members added on or after a specific date - Use `created_at[stop]` to get members added before a specific date - Use both to get members added within a date range You can also filter by when membership was last updated using the `updated_at` parameter: - Use `updated_at[start]` to get members updated on or after a specific date - Use `updated_at[stop]` to get members updated before a specific date - Use both to get members updated within a date range' parameters: - name: project_id in: path required: true schema: type: integer format: int32 - name: page_start_id in: query description: The page start ID. schema: type: integer format: int32 default: 0 - name: page_limit in: query description: The default page size schema: type: integer format: int32 default: null - name: search[email] in: query description: An email to search for members schema: type: string - name: search[name] in: query description: A name to search for members schema: type: string - name: include_removed in: query description: Include members that were removed from the project schema: type: boolean default: false - name: include_profile in: query description: Include member profile information schema: type: boolean default: false - name: direct_only in: query description: If true, only include members assigned directly to the project and not as member of a team working on the project schema: type: boolean default: false - name: membership_roles in: query description: Search by membership role schema: type: array items: type: string enum: - manager - user - viewer - name: created_at[start] in: query description: Start date for created_at filter (inclusive) schema: type: string format: date-time - name: created_at[stop] in: query description: End date for created_at filter (exclusive) schema: type: string format: date-time - name: updated_at[start] in: query description: Start date for updated_at filter (inclusive) schema: type: string format: date-time - name: updated_at[stop] in: query description: End date for updated_at filter (exclusive) schema: type: string format: date-time - name: user_ids in: query description: List of user IDs schema: type: array items: type: integer format: int32 - name: include in: query description: Specify related data to side load. schema: type: array items: type: string enum: - users responses: '200': description: A list of members '400': description: Invalid parameters '401': description: Unauthorized '403': description: API access is only for organizations on an active plan '404': description: Could not find record '429': description: Rate limit exceeded components: securitySchemes: oauth2: type: oauth2 description: Hubstaff Account OpenID Connect / OAuth 2.0 authentication. Scopes are hubstaff:read and hubstaff:write. flows: authorizationCode: authorizationUrl: https://account.hubstaff.com/authorizations/new tokenUrl: https://account.hubstaff.com/access_tokens scopes: hubstaff:read: Read access to the Hubstaff API hubstaff:write: Write access to the Hubstaff API personalAccessToken: type: http scheme: bearer description: Access token obtained by exchanging a personal access token (created at https://developer.hubstaff.com/personal_access_tokens) via the OAuth 2.0 refresh token grant at https://account.hubstaff.com/access_tokens. PATs expire after 90 days. externalDocs: description: Hubstaff API v2 reference (interactive) url: https://developer.hubstaff.com/docs/hubstaff_v2