> ## Documentation Index > Fetch the complete documentation index at: https://api-docs.spott.io/llms.txt > Use this file to discover all available pages before exploring further. # List placements > Returns a list of placements. Supports pagination, filtering by company, sort options, and applied filters. Returns candidate, company, job, fee, and placement metadata. ## OpenAPI ````yaml /openapi-private.json get /placements openapi: 3.1.0 info: title: Spott API Reference version: '0.1' servers: - url: https://api.gospott.com security: [] tags: [] paths: /placements: get: tags: - Placements summary: List placements description: >- Returns a list of placements. Supports pagination, filtering by company, sort options, and applied filters. Returns candidate, company, job, fee, and placement metadata. operationId: getAllPlacements parameters: - name: page required: false in: query schema: minimum: 0 maximum: 10000 default: 0 type: integer - name: pageSize required: false in: query schema: default: 20 type: integer minimum: 1 maximum: 100 - name: companyId required: false in: query schema: type: string - name: modifiedSince required: false in: query description: Filter placements modified on or after this date. schema: $ref: '#/components/schemas/DateISO' default: '1970-01-01T00:00:00.000Z' example: '2024-01-01T00:00:00.000Z' - name: modifiedUntil required: false in: query description: Filter placements modified on or before this date. schema: $ref: '#/components/schemas/DateISO' example: '2024-01-31T23:59:59.999Z' responses: '200': description: >- Successfully retrieved placements. Returns items array with pagination info containing page number, page size, and total count. content: application/json: schema: $ref: '#/components/schemas/PlacementPaginatedResponseDto' '400': description: >- Bad request - invalid query parameters (e.g., page number out of range, invalid filter format) content: application/json: schema: allOf: - $ref: '#/components/schemas/ExceptionBaseDto' - type: object properties: statusCode: type: number example: 400 message: type: string example: Invalid filter format error: type: string example: Bad Request '401': description: Unauthorized - invalid or missing authentication content: application/json: schema: $ref: '#/components/schemas/ExceptionBaseDto' '500': description: Error response content: application/json: schema: $ref: '#/components/schemas/ExceptionBaseDto' security: - x-api-key: [] components: schemas: DateISO: id: DateISO format: date-time anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ - type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ PlacementPaginatedResponseDto: type: object properties: items: type: array items: $ref: '#/components/schemas/PlacementListItemDto' pagination: $ref: '#/components/schemas/PaginationDto' required: - items - pagination id: PrivatePlacementPaginatedResponseDto ExceptionBaseDto: type: object properties: status: type: integer minimum: -9007199254740991 maximum: 9007199254740991 message: type: string requestId: type: string required: - status - message - requestId id: ExceptionBaseDto PlacementListItemDto: type: object properties: id: type: string templateId: type: string type: type: string enum: - CONTINGENT - INTERIM - RETAINED placedByUser: $ref: '#/components/schemas/PlacementUserBadgeDto' placedAt: $ref: '#/components/schemas/DateISO' startDate: anyOf: - $ref: '#/components/schemas/DateISO' - type: 'null' endDate: anyOf: - $ref: '#/components/schemas/DateISO' - type: 'null' fee: anyOf: - $ref: '#/components/schemas/PlacementFeeDto' - type: 'null' extensionOf: anyOf: - $ref: '#/components/schemas/PlacementExtensionOfDto' - type: 'null' applicationId: type: string candidate: $ref: '#/components/schemas/PlacementCandidateBadgeDto' company: $ref: '#/components/schemas/PlacementCompanyBadgeDto' vacancy: anyOf: - $ref: '#/components/schemas/PlacementVacancyBadgeDto' - type: 'null' required: - id - templateId - type - placedByUser - placedAt - startDate - endDate - fee - extensionOf - applicationId - candidate - company - vacancy id: PrivatePlacementListItemDto PaginationDto: type: object properties: totalItems: type: number page: type: number hasNextPage: type: boolean required: - totalItems - page - hasNextPage id: PaginationDto PlacementUserBadgeDto: type: object properties: id: type: string name: type: string avatarUrl: anyOf: - type: string - type: 'null' deactivatedAt: anyOf: - $ref: '#/components/schemas/DateISO' - type: 'null' required: - id - name - avatarUrl - deactivatedAt id: PrivatePlacementUserBadgeDto PlacementFeeDto: type: object properties: id: type: string net: anyOf: - $ref: '#/components/schemas/PlacementMonetaryAmountDto' - type: 'null' splits: type: array items: $ref: '#/components/schemas/PlacementFeeSplitDto' details: description: >- Experimental. The structure of this field is intentionally unspecified and may change without notice. anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: 'null' required: - id - net - splits id: PrivatePlacementFeeDto PlacementExtensionOfDto: type: object properties: id: type: string required: - id id: PrivatePlacementExtensionOfDto PlacementCandidateBadgeDto: type: object properties: id: type: string firstName: type: string lastName: type: string middleName: anyOf: - type: string - type: 'null' secondLastName: anyOf: - type: string - type: 'null' avatarUrl: anyOf: - type: string - type: 'null' required: - id - firstName - lastName - middleName - secondLastName - avatarUrl id: PrivatePlacementCandidateBadgeDto PlacementCompanyBadgeDto: type: object properties: id: type: string name: type: string logoCdnUrl: anyOf: - type: string - type: 'null' required: - id - name - logoCdnUrl id: PrivatePlacementCompanyBadgeDto PlacementVacancyBadgeDto: type: object properties: id: type: string name: type: string required: - id - name id: PrivatePlacementVacancyBadgeDto PlacementMonetaryAmountDto: type: object properties: amount: type: number example: 10000 currency: $ref: '#/components/schemas/DmSupportedCurrency' example: EUR required: - amount - currency id: PrivatePlacementMonetaryAmountDto PlacementFeeSplitDto: type: object properties: user: $ref: '#/components/schemas/PlacementUserBadgeDto' percentage: type: number minimum: 0 maximum: 1 required: - user - percentage id: PrivatePlacementFeeSplitDto DmSupportedCurrency: type: string enum: - EUR - GBP - USD - ZAR - AUD - CHF - SAR - AED - EGP - HUF - RON - BGN - CZK - PLN - NOK - SEK - DKK - CAD - HKD - JPY - THB - CNY - INR - SGD - MYR - QAR - PHP - LKR - KWD - PKR - MOP - IDR - VND - KRW - MXN - BRL - ARS - NZD - TWD - ILS - TRY - RUB - MDL - MUR - OMR id: DmSupportedCurrency securitySchemes: x-api-key: type: apiKey name: x-api-key in: header description: >- API key for authentication. Get your API key from Settings → API Keys in your Spott dashboard. ````