> ## Documentation Index > Fetch the complete documentation index at: https://doc.folkyn.com/llms.txt > Use this file to discover all available pages before exploring further. # List Freelancers > Lists freelancers for the API key's team. ## OpenAPI ````yaml /openapi.yaml get /api/v1/freelancers openapi: 3.0.3 info: title: Folkyn API version: 1.0.0 license: name: Proprietary url: https://folkyn.com description: >- Team API key; responses in `data`, errors in `error` with `X-Request-Id`. Spec at `/api/v1/openapi.yaml` and `/api/v1/openapi.json` (no key). **60 requests/minute** per key on `/api/v1/*`. servers: - url: https://api.folkyn.com description: Production security: - bearerAuth: [] - ApiKeyHeader: [] tags: - name: Specification description: OpenAPI document download (no authentication) - name: Project codes description: Team project codes - name: Team tags description: Team tags - name: Teams description: Organizational teams (team units) and member lists - name: Missions description: Team missions - name: Freelancers description: Team freelancers and invitations - name: Activity reports description: Activity reports (CRA) - name: Accounting description: Accounting entries paths: /api/v1/freelancers: get: tags: - Freelancers summary: List Freelancers description: Lists freelancers for the API key's team. operationId: listFreelancers parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - name: status in: query description: > Comma-separated roster segment: `staffed`, `unstaffed`, `pending`, `archived`, or `all`. `staffed` = at least one active mission; `unstaffed` = active link without such mission; `pending` = invitation not accepted (`id` is a team invitation id); `archived` = archived link. Omit `status` to exclude `archived` and `pending`; use `all` for no filter. schema: type: string example: staffed,unstaffed - name: tag_ids in: query description: >- Comma-separated tag UUIDs (AND — freelancer must have all listed tags). schema: type: string - name: kyc_complete in: query schema: type: string enum: - 'true' - 'false' - name: master_agreement_active in: query schema: type: string enum: - 'true' - 'false' - name: external_id in: query description: >- Filter by exact `external_id` (case-insensitive) — matches the team-set value or, when unset, the value derived from the freelancer's name. schema: type: string example: clementbalea responses: '200': description: Success content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/PaginatedPartnerFreelancers' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/ForbiddenError' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' components: parameters: Page: name: page in: query schema: type: integer minimum: 1 default: 1 PerPage: name: per_page in: query schema: type: integer minimum: 1 maximum: 100 default: 10 schemas: PaginatedPartnerFreelancers: type: object required: - items - total - current_page - per_page properties: items: type: array items: $ref: '#/components/schemas/FreelancerListItemPublic' total: type: integer current_page: type: integer per_page: type: integer FreelancerListItemPublic: type: object required: - id - email - external_id - job_title - note - referent - status - tags - teams - kyc_complete - master_agreement_active - created_at properties: id: type: string format: uuid description: Profile UUID, or invitation UUID when `status` is `pending`. email: type: string first_name: type: string nullable: true last_name: type: string nullable: true external_id: type: string description: > External identifier for integrations. Uses the team-stored value when set; otherwise computed from lowercased `first_name` + `last_name` with spaces and Latin diacritics stripped (e.g. Clément Balea → `clementbalea`). German `ß` becomes `ss`. Empty string if both names are missing and no stored value. job_title: type: string nullable: true note: type: string nullable: true description: Internal team note on the freelancer; null if absent. referent: type: object nullable: true allOf: - $ref: '#/components/schemas/PartnerFreelancerReferentPublic' description: Team referent profile; null if none. status: $ref: '#/components/schemas/PartnerFreelancerListStatus' tags: type: array description: >- Tags for this freelancer on the team (`tag_ids` query uses AND across listed UUIDs). items: $ref: '#/components/schemas/FreelancerTagPublic' teams: type: array description: Organizational teams (team units) this freelancer belongs to. items: $ref: '#/components/schemas/FreelancerTeamPublic' kyc_complete: type: boolean master_agreement_active: type: boolean description: Signed master agreement with a future `valid_until` date. created_at: type: string format: date-time PublicError: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: type: integer description: Same as HTTP status; use `message` and `details` to narrow. enum: - 400 - 401 - 403 - 404 - 429 - 500 example: 401 message: type: string request_id: type: string format: uuid description: Correlates with the X-Request-Id response header. details: $ref: '#/components/schemas/PublicErrorDetails' PartnerFreelancerReferentPublic: type: object description: Team referent (id, first name, last name, email). required: - id - first_name - last_name - email properties: id: type: string format: uuid first_name: type: string last_name: type: string email: type: string PartnerFreelancerListStatus: type: string enum: - staffed - unstaffed - pending - archived description: > Lifecycle status on each list item. `staffed` = active mission on team; `unstaffed` = active link, no such mission; `pending` = invitation not yet accepted; `archived` = archived link. FreelancerTagPublic: type: object required: - id - name description: Team tag attached to the freelancer. properties: id: type: string format: uuid name: type: string FreelancerTeamPublic: type: object required: - id - name - depth - path - parent_id properties: id: type: string format: uuid name: type: string depth: type: integer minimum: 1 maximum: 3 description: Depth in the organizational tree (1 = root). path: type: string description: >- Ancestor path from root to this node (e.g. `Direction › Engineering › Backend`). parent_id: type: string format: uuid nullable: true description: Parent organizational team UUID; null for root nodes. PublicErrorDetails: type: object description: Optional structured hints (validation, scope, rate limit). additionalProperties: true properties: reason: $ref: '#/components/schemas/PartnerValidationErrorReason' field: type: string description: JSON body field name when applicable (e.g. `name`). example: name requiredScope: type: string description: >- Required OAuth-like scope string when `code` is 403 (insufficient scope). example: tags:write retryAfterSeconds: type: integer minimum: 0 description: Hint when `code` is 429. PartnerValidationErrorReason: type: string description: >- Machine-readable validation subtype (HTTP 400) for create tag / project code. enum: - invalid_json - required_field - duplicate_name responses: Unauthorized: description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/PublicError' ForbiddenError: description: Insufficient scope or forbidden content: application/json: schema: $ref: '#/components/schemas/PublicError' RateLimited: description: Too many requests content: application/json: schema: $ref: '#/components/schemas/PublicError' InternalError: description: Server error content: application/json: schema: $ref: '#/components/schemas/PublicError' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: 'Use `Authorization: Bearer `' ApiKeyHeader: type: apiKey in: header name: X-Api-Key ````