> ## Documentation Index > Fetch the complete documentation index at: https://docs.awardforce.com/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve users > Retrieves users. ## OpenAPI ````yaml /api-reference/openapi-v2_3.yaml get /user openapi: 3.1.0 info: title: Award Force API version: '2.3' description: > The Award Force API enables you to programmatically manage awards, competitions, scholarships, and recognition programs. Use this API to: - Create and manage entries and submissions - Automate judging workflows and assignments - Process entry fees and payments - Generate reports and analytics - Integrate with external systems via webhooks All API requests require authentication using an API key provided in the `X-Api-Key` header. license: name: Creative Force Client Subscription Terms url: https://creativeforce.team/agreement/ servers: - url: https://api.us.cr4ce.com description: US regional endpoint - url: https://api.eu.cr4ce.com description: EU regional endpoint - url: https://api.au.cr4ce.com description: Australasia regional endpoint - url: https://api.ca.cr4ce.com description: Canada regional endpoint - url: https://api.hk.cr4ce.com description: Hong Kong regional endpoint security: - ApiKeyAuth: [] tags: - name: Account description: >- Use this operation to retrieve information about your organization account. The account resource provides metadata about the tenant associated with your API key. Note: Account information is read-only and contains organization-level settings and identifiers. - name: Assignments description: >- Use these operations to manage judging assignments for evaluating entries. Assignments connect judges (or roles) with entries and score sets to facilitate the review process. Assignments can be created individually or in bulk (asynchronous operations). Each assignment tracks completion status, scores, and panel membership. Assignments enable structured evaluation workflows with configurable score sets. - name: Attachments description: >- Use these operations to manage files uploaded to entries through attachment tabs. Attachments are distinct from field-based file uploads and allow for supplementary materials. Each attachment can have its own metadata and custom fields for categorization. Attachments remain associated with their entry throughout the entry lifecycle. - name: Categories description: >- Use these operations to manage competition categories or award divisions. Categories organize entries into logical groups and can be hierarchical with parent-child relationships. Each category can have its own entry form, chapter availability, entry limits, and custom labels. Categories support translated names and descriptions for multi-language programs. - name: Chapters description: >- Use these operations to manage geographic or organizational divisions within your programs. Chapters enable you to run regional competitions, manage local awards, or organize by business units. Entries can be assigned to chapters, and chapters can have their own administrators and configurations. Chapters support translated names and custom images for branding. - name: Contributors description: >- Use these operations to manage additional people associated with entries beyond the primary entrant. Contributors represent team members, collaborators, or co-authors on a submission. Each contributor can have their own custom fields and data collection requirements. Contributors are organized by tabs and can be managed independently from the main entry. - name: Documents description: >- Use these operations to generate and retrieve PDF documents and data exports. Documents can be created based on entry data, user data, or other program information. Document generation is asynchronous - after creating a document, poll the endpoint to check when generation is complete. Generated documents are available for download and can be associated with specific entrants or entries. - name: Entries description: >- Use these operations to manage entries (submissions) to your awards, competitions, or recognition programs. Entries are the core entity that flows through the entire lifecycle from submission to judging to winner selection. Entries can contain custom form fields, file uploads, contributors, and be organized by categories and chapters. Each entry goes through various statuses including draft, submitted, under review, and finalist stages. - name: Entries (realtime) description: >- Use these operations to perform granular updates on entries without replacing the entire resource. These endpoints enable real-time updates to specific entry properties such as: title, category assignment, chapter assignment, individual field values, file uploads, tags, and recusal status. These operations are optimized for interactive programs that need to update entries incrementally. - name: Fields description: >- Use these operations to manage custom form fields used to collect data throughout your programs. Fields can be attached to entries, users, contributors, attachments, and other resources. Supported field types include text, textarea, select, multi-select, date, file upload, table, and more. Fields support conditional logic, validation rules, and different protection levels. Note: Field deletion and updates are managed through the Award Force interface. - name: Files description: >- Use these operations to retrieve information about uploaded files. Files provide metadata and download links for content uploaded throughout the system. Access files using their secure token identifiers. Note: Files are read-only via this endpoint - file uploads are handled through resource-specific upload endpoints. - name: Leaderboard description: >- Use these operations to retrieve ranking results and scores for entries. The leaderboard shows how entries rank based on score sets, with support for filtering by category, chapter, and tags. Results can be filtered to show specific subsets of the competition. Note: The leaderboard is read-only and reflects calculated results from the judging process. - name: Orders description: >- Use these operations to manage payment transactions for entry fees and other charges. Orders represent financial transactions processed through your program. Each order contains line items, tracks payment status, and can operate in test or live mode. Orders are associated with seasons and can be queried for financial reporting. - name: Review tasks description: >- Use these operations to manage individual review and evaluation activities. Review tasks represent specific actions that judges or administrators need to complete during the evaluation process. Tasks track timestamps, decisions, and judge associations. Review tasks integrate with the broader judging workflow and status tracking. - name: Rounds description: >- Use these operations to retrieve round information for your programs. Rounds represent phases within a season, such as entry rounds, judging rounds, or finalist rounds. Each round has specific start and end dates, associated forms, and can be scoped to specific chapters. Note: Rounds are read-only via the API and must be managed through the Award Force interface. - name: Score sets description: >- Use these operations to retrieve score set configurations and evaluation criteria. Score sets define the questions, scales, and calculation methods used to evaluate entries. Score sets can operate in different modes including judging, ranking, and decision-making. Note: Score sets are read-only via the API and must be configured through the Award Force interface. - name: Seasons description: >- Use these operations to retrieve information about seasons (program cycles). A season represents a time-bound program instance, such as "2026 Awards" or "Q1 2026 Scholarship Round". Seasons contain forms, rounds, categories, and chapters. Seasons progress through statuses: draft, active, archived, and destroyed. Note: Seasons are read-only via the API and must be managed through the Award Force interface. - name: Taxes description: >- Use these operations to retrieve tax configurations for financial transactions. Tax settings define how taxes are calculated and applied to orders and payments. Note: Tax configurations are read-only via the API and must be managed through the Award Force interface. - name: Users description: >- Use these operations to manage user accounts in your organization. Users represent people who interact with your programs, including entrants, judges, administrators, and other roles. Users can be assigned roles, have custom profile fields, receive notifications, and authenticate via API tokens. Each user has a unique slug identifier and can participate across multiple seasons. - name: Webhooks description: >- Use these operations to manage webhook subscriptions for real-time event notifications. Webhooks notify your external systems when events occur in Award Force, such as entry submissions, status changes, or payment completions. Available events include: entry created, entry submitted, entry status changed, payment success, user confirmed, and 20+ more. Configure webhooks to send HTTP POST requests to your specified URLs with event payloads. paths: /user: get: tags: - Users summary: Retrieve users description: Retrieves users. operationId: GetUserCollectionV23 parameters: - $ref: '#/components/parameters/userActiveInSeasonFilter' - $ref: '#/components/parameters/userConfirmationFilter' - $ref: '#/components/parameters/userEntriesFilter' - $ref: '#/components/parameters/userLanguageFilter' - $ref: '#/components/parameters/userRoleFilter' - $ref: '#/components/parameters/userSeasonJoinedFilter' - $ref: '#/components/parameters/deletedFilter' - $ref: '#/components/parameters/trashedFilter' - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/perPage' - $ref: '#/components/parameters/userOrder' - $ref: '#/components/parameters/sortDirection' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/X-Api-Language' responses: '200': description: Users retrieved. headers: ETag: $ref: '#/components/headers/ETag' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/UserList' application/xml: schema: $ref: '#/components/schemas/UserList' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '503': $ref: '#/components/responses/ServiceUnavailable' components: parameters: userActiveInSeasonFilter: name: active_in_season in: query required: false description: Filter by the season the user is active in, identified by season slug. schema: type: string userConfirmationFilter: name: confirmation in: query required: false description: Filter by account confirmation status. schema: type: string enum: - confirmed - pending userEntriesFilter: name: entries in: query required: false description: Filter by entry status. schema: type: string enum: - current_season - none_current_season - archived_season - none userLanguageFilter: name: language in: query required: false description: Filter by language code. schema: type: string userRoleFilter: name: role in: query required: false description: Filter by role slug. schema: type: string userSeasonJoinedFilter: name: season_joined in: query required: false description: Filter by the season the user joined in, identified by season slug. schema: type: string deletedFilter: name: deleted in: query required: false description: |- Filter by deletion mode. * `only` - Show only deleted resources. * `included` - Include deleted resources. * `none` - Exclude deleted resources. schema: type: string enum: - only - included - none trashedFilter: name: trashed in: query required: false description: |- Filter by soft-deletion mode. * `only` - Show only soft-deleted resources. * `all` - Include soft-deleted resources alongside live ones. * `none` - Exclude soft-deleted resources. schema: type: string enum: - only - all - none page: name: page in: query required: false description: Specify the page number to return. schema: type: number perPage: name: per_page in: query required: false description: > Limit the number of items returned to between 1 and 100. If you provide a value outside this range, you will receive a `400` response. schema: type: number userOrder: name: order in: query required: false description: >- Column name to order by. An unrecognised value falls back to the default sort by `updated`. schema: type: string enum: - confirmed_at - created_at - created_by - email - first_name - last_name - mobile - name - updated sortDirection: name: dir in: query required: false description: >- Sort in ascending or descending order. Invalid values are rejected with `400 Bad Request`. schema: type: string enum: - asc - desc Accept: name: Accept in: header required: true description: Defines the response type. schema: type: string enum: - application/vnd.Creative Force.v2.3+json - application/vnd.Creative Force.v2.3+xml X-Api-Language: name: x-api-language in: header required: false description: >- Defines the languages included in the response. If non are provided, the account default language is returned. Value `all` overrides any other values present. You can request multiple languages using a comma-separated string of languages. The selected language must be supported by your account or a `400` error is returned. style: simple explode: false schema: type: array items: type: string enum: - all - ar_AR - bg_BG - bn_IN - ca_ES - cs_CZ - cy_GB - da_DK - de_DE - en_GB - en_US - el_GR - es_NN - es_LA - et_EE - fa_NN - fi_FI - fr_FR - fr_CA - he_IL - hi_IN - hr_HR - hu_HU - hy_AM - it_IT - ja_JP - ko_KR - lt_LT - ms_MY - nl_NL - nb_NO - pl_PL - pt_BR - ro_RO - ru_RU - sk_SK - sl_SI - sq_AL - sr_RS - sv_SE - sw_NN - th_TH - tr_TR - uk_UA - vi_VN - zh_CN - zh_HK example: - en_GB - fr_FR headers: ETag: description: Entity tag for the selected representation. schema: type: string X-RateLimit-Limit: description: Maximum number of requests allowed per minute. schema: type: integer example: 60 X-RateLimit-Remaining: description: Number of requests remaining in the current rate limit window. schema: type: integer example: 58 X-RateLimit-Reset: description: Unix timestamp when the rate limit window resets. schema: type: integer example: 1783470988 Retry-After: description: Number of seconds the client should wait before retrying. schema: type: integer example: 60 schemas: UserList: allOf: - $ref: '#/components/schemas/Pagination' - type: object properties: data: type: array items: $ref: '#/components/schemas/UserSummary' example: current_page: 1 data: - analytics_cookies: true broadcast_emails: true comments: '' confirmation: Confirmed confirmed_at: '2025-08-05T00:00:00Z' created_at: '2025-08-05T09:00:58Z' created_by: invited email: john.doe@example.com first_name: John language: code: en_GB language: English (United Kingdom) last_name: Doe marketing_cookies: true mobile: '' name: John Doe necessary_cookies: true notification_emails: true notification_sms: true roles: - slug: AbCdEfGh link: https://api.eu.staging.cr4ce.com/role/AbCdEfGh name: en_GB: Entrant slug: KlMnOpQr updated: '2026-06-28T08:03:58Z' - analytics_cookies: false broadcast_emails: false comments: '' confirmation: Confirmed confirmed_at: '2025-04-01T00:00:00Z' created_at: '2025-04-23T12:36:32Z' created_by: manual email: jane.roe@example.com first_name: Jane language: code: en_GB language: English (United Kingdom) last_name: Roe marketing_cookies: false mobile: '' name: Jane Roe necessary_cookies: true notification_emails: false notification_sms: false roles: - slug: AbCdEfGh link: https://api.eu.staging.cr4ce.com/role/AbCdEfGh name: en_GB: Entrant - slug: CdEfGhIj link: https://api.eu.staging.cr4ce.com/role/CdEfGhIj name: en_GB: Program manager slug: MnOpQrSt updated: '2026-06-25T15:39:46Z' first_page_url: https://api.eu.staging.cr4ce.com/user?per_page=100&page=1 from: 1 last_page: 5 last_page_url: https://api.eu.staging.cr4ce.com/user?per_page=100&page=5 next_page_url: https://api.eu.staging.cr4ce.com/user?per_page=100&page=2 path: https://api.eu.staging.cr4ce.com/user per_page: 100 prev_page_url: '' to: 100 total: 470 Pagination: type: object title: Pagination description: >- Pagination envelope returned by every list endpoint. Wraps the result set with positional fields (`current_page`, `from`, `to`, `total`) and navigation URLs (`first_page_url`, `last_page_url`, `next_page_url`, `prev_page_url`) for traversing the full list. The records themselves are returned in a sibling `data` array supplied by the wrapping schema. properties: current_page: type: integer description: Number of the page returned by this response. The first page is `1`. first_page_url: type: string description: >- URL of the first page in the result set. Relative when the requested page is beyond the last page. from: type: - integer - 'null' description: >- Position of the first record on this page within the full result set. The first record is at position `1`. `null` when the requested page is beyond the last page. last_page: type: integer description: Number of the last page. Equals the total number of pages. last_page_url: type: string description: >- URL of the last page in the result set. Relative when the requested page is beyond the last page. next_page_url: type: string description: |- URL of the next page in the result set. Empty string when the current page is the last page. path: type: string description: Canonical URL of the endpoint, without query parameters. per_page: type: integer minimum: 1 maximum: 100 default: 10 description: Maximum number of records returned per page. prev_page_url: type: string description: |- URL of the previous page in the result set. Empty string when the current page is the first page. to: type: - integer - 'null' description: >- Position of the last record on this page within the full result set. `null` when the requested page is beyond the last page. total: type: integer description: Total number of records across all pages. UserSummary: type: object description: Core user fields shared by the list and single-user responses. properties: analytics_cookies: type: boolean description: Specifies whether the user accepted analytics cookies. broadcast_emails: type: boolean description: Specifies whether the user accepted broadcast emails. comments: type: string description: >- Administrative notes recorded against the user, formatted for export. confirmation: type: string description: >- Account confirmation status of the user, such as `Confirmed` or `Invited`. confirmed_at: type: - string - 'null' format: date-time description: >- Date and time when the user confirmed the account. Value is `null` for an invited user who has not yet confirmed. created_at: type: string format: date-time description: Date and time when the user account was created. created_by: type: string description: >- Method by which the user account was created, such as `manual` or `registration`. email: type: - string - 'null' format: email description: >- Email address of the user. Value is `null` when no email address is recorded. first_name: type: string description: First name of the user. language: type: object description: Preferred language of the user. properties: code: type: string description: Locale code of the language, such as `en_GB`. language: type: string description: >- Display name of the language, such as `English (United Kingdom)`. last_name: type: string description: Last name of the user. marketing_cookies: type: boolean description: Specifies whether the user accepted marketing cookies. mobile: type: string description: Mobile phone number of the user. name: type: string description: Full name of the user. necessary_cookies: type: boolean description: Specifies whether the user accepted necessary cookies. notification_emails: type: boolean description: Specifies whether the user accepted notification emails. notification_sms: type: boolean description: Specifies whether the user accepted notification text messages. roles: type: array description: Roles assigned to the user within the account. items: type: object properties: slug: type: string description: URL-safe identifier of the role. link: type: string format: uri description: URL of the role resource. name: type: object description: >- Name of the role. Map keyed by locale code (for example, `en_GB` or `fr_FR`). Keys are drawn from the languages enabled on the account. Values are the translated string. additionalProperties: type: string slug: type: string description: URL-safe identifier of the user. updated: type: string format: date-time description: Date and time when the user account was last updated. BadRequest: allOf: - $ref: '#/components/schemas/BaseProblem' - type: object properties: status_code: type: integer minimum: 400 maximum: 400 Unauthorized: allOf: - $ref: '#/components/schemas/BaseProblem' - type: object properties: status_code: type: integer minimum: 401 maximum: 401 Forbidden: allOf: - $ref: '#/components/schemas/BaseProblem' - type: object properties: status_code: type: integer minimum: 403 maximum: 403 TooManyRequests: allOf: - $ref: '#/components/schemas/BaseProblem' - type: object properties: status_code: type: integer minimum: 429 maximum: 429 BaseProblem: description: Standard error envelope shared by every error response on this API. type: object properties: message: type: string status_code: type: integer minimum: 400 maximum: 599 responses: BadRequest: description: >- Request was rejected before the endpoint could process it. Common causes: invalid `Accept` header, unsupported `x-api-language` code, empty request body on `POST` / `PUT`, invalid JSON in the request body, or an invalid slug format in a path parameter. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/BadRequest' application/xml: schema: $ref: '#/components/schemas/BadRequest' Unauthorized: description: Missing `x-api-key` header. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/Unauthorized' application/xml: schema: $ref: '#/components/schemas/Unauthorized' Forbidden: description: |- Authenticated request denied. Common causes: invalid or unknown API key, suspended account, or `api` feature not enabled for the account. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/Forbidden' application/xml: schema: $ref: '#/components/schemas/Forbidden' TooManyRequests: description: Rate limit of 60 requests per minute exceeded. headers: Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: $ref: '#/components/schemas/TooManyRequests' application/xml: schema: $ref: '#/components/schemas/TooManyRequests' ServiceUnavailable: description: Service is temporarily unavailable due to regional maintenance. content: application/json: schema: type: object properties: status: type: string description: Human-readable maintenance status. example: status: Maintenance in progress application/xml: schema: type: object properties: status: type: string description: Human-readable maintenance status. example: status: Maintenance in progress securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: |- API key used to authenticate and authorise every request. Include it in the `x-api-key` header. ````