openapi: 3.0.3 info: title: SmartRecruiters Candidate API description: >- The SmartRecruiters Candidate API enables customers to import, export, read, and update candidate data. Provides full candidate profile management including personal information, application history, notes, and attachments. version: 1.0.0 contact: name: SmartRecruiters Developer Support url: https://developers.smartrecruiters.com/ servers: - url: https://api.smartrecruiters.com description: SmartRecruiters Production API security: - ApiKey: [] paths: /candidates: get: operationId: listCandidates summary: List Candidates description: >- Returns a paginated list of candidates. Supports filtering by name, email, application status, and date ranges. tags: - Candidates parameters: - name: q in: query required: false description: Search query for candidate name or email schema: type: string - name: limit in: query required: false description: Maximum number of results to return schema: type: integer default: 10 maximum: 100 - name: offset in: query required: false description: Number of results to skip for pagination schema: type: integer default: 0 - name: status in: query required: false description: Filter by application status schema: type: string responses: '200': description: List of candidates content: application/json: schema: $ref: '#/components/schemas/CandidateListResult' '400': description: Bad request '401': description: Unauthorized '403': description: Forbidden '429': description: Too many requests post: operationId: createCandidate summary: Create Candidate description: >- Imports a new candidate into the SmartRecruiters system. Creates a candidate profile with personal information and optional application data. tags: - Candidates requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CandidateCreate' responses: '201': description: Candidate created successfully content: application/json: schema: $ref: '#/components/schemas/Candidate' '400': description: Bad request '401': description: Unauthorized '403': description: Forbidden '409': description: Candidate with this email already exists /candidates/{candidateId}: get: operationId: getCandidate summary: Get Candidate description: Retrieves detailed profile information for a specific candidate. tags: - Candidates parameters: - name: candidateId in: path required: true description: The unique candidate identifier schema: type: string responses: '200': description: Candidate profile content: application/json: schema: $ref: '#/components/schemas/Candidate' '401': description: Unauthorized '403': description: Forbidden '404': description: Candidate not found patch: operationId: updateCandidate summary: Update Candidate description: Updates properties of an existing candidate profile. tags: - Candidates parameters: - name: candidateId in: path required: true description: The unique candidate identifier schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CandidateUpdate' responses: '200': description: Candidate updated successfully content: application/json: schema: $ref: '#/components/schemas/Candidate' '400': description: Bad request '401': description: Unauthorized '403': description: Forbidden '404': description: Candidate not found /candidates/{candidateId}/applications: get: operationId: listCandidateApplications summary: List Candidate Applications description: Returns all job applications associated with a specific candidate. tags: - Candidates - Applications parameters: - name: candidateId in: path required: true description: The unique candidate identifier schema: type: string responses: '200': description: List of applications content: application/json: schema: type: object properties: content: type: array items: $ref: '#/components/schemas/Application' '401': description: Unauthorized '403': description: Forbidden '404': description: Candidate not found /candidates/{candidateId}/messages: get: operationId: listCandidateMessages summary: List Candidate Messages description: Returns all notes and messages associated with a candidate. tags: - Candidates - Messages parameters: - name: candidateId in: path required: true description: The unique candidate identifier schema: type: string responses: '200': description: List of messages content: application/json: schema: type: object properties: content: type: array items: $ref: '#/components/schemas/Message' '401': description: Unauthorized '403': description: Forbidden '404': description: Candidate not found post: operationId: createCandidateMessage summary: Create Candidate Message description: Adds a note or message to a candidate profile. tags: - Candidates - Messages parameters: - name: candidateId in: path required: true description: The unique candidate identifier schema: type: string requestBody: required: true content: application/json: schema: type: object required: - message properties: message: type: string description: The message or note content responses: '201': description: Message created content: application/json: schema: $ref: '#/components/schemas/Message' '400': description: Bad request '401': description: Unauthorized '403': description: Forbidden /candidates/{candidateId}/documents: get: operationId: listCandidateDocuments summary: List Candidate Documents description: Returns all documents (resumes, CVs, cover letters) attached to a candidate profile. tags: - Candidates - Documents parameters: - name: candidateId in: path required: true description: The unique candidate identifier schema: type: string responses: '200': description: List of documents content: application/json: schema: type: object properties: content: type: array items: $ref: '#/components/schemas/Document' '401': description: Unauthorized '403': description: Forbidden '404': description: Candidate not found components: securitySchemes: ApiKey: type: apiKey in: header name: X-SmartToken OAuth2: type: oauth2 flows: clientCredentials: tokenUrl: https://www.smartrecruiters.com/identity/oauth/token scopes: candidates.read: Read candidate data candidates.write: Write candidate data schemas: CandidateListResult: type: object properties: limit: type: integer offset: type: integer totalFound: type: integer content: type: array items: $ref: '#/components/schemas/Candidate' Candidate: type: object properties: id: type: string description: Unique candidate identifier firstName: type: string lastName: type: string email: type: string format: email phoneNumber: type: string location: type: object properties: city: type: string country: type: string countryCode: type: string web: type: object properties: linkedIn: type: string format: uri facebook: type: string format: uri portfolio: type: string format: uri tags: type: array items: type: string consent: type: object properties: status: type: string enum: - PENDING - GIVEN - WITHDRAWN createdOn: type: string format: date-time expirationDate: type: string format: date gdpr: type: object properties: piiExpired: type: boolean sourceDetails: $ref: '#/components/schemas/SourceDetails' createdOn: type: string format: date-time updatedOn: type: string format: date-time CandidateCreate: type: object required: - firstName - lastName - email properties: firstName: type: string lastName: type: string email: type: string format: email phoneNumber: type: string location: type: object properties: city: type: string country: type: string web: type: object properties: linkedIn: type: string format: uri portfolio: type: string format: uri tags: type: array items: type: string sourceDetails: $ref: '#/components/schemas/SourceDetails' CandidateUpdate: type: object properties: firstName: type: string lastName: type: string phoneNumber: type: string location: type: object properties: city: type: string country: type: string web: type: object properties: linkedIn: type: string format: uri portfolio: type: string format: uri tags: type: array items: type: string Application: type: object properties: id: type: string candidateId: type: string jobId: type: string jobTitle: type: string status: type: string enum: - IN_PROGRESS - REJECTED - OFFERED - HIRED appliedOn: type: string format: date-time updatedOn: type: string format: date-time source: $ref: '#/components/schemas/SourceDetails' Message: type: object properties: id: type: string message: type: string type: type: string enum: - NOTE - EMAIL - SYSTEM createdOn: type: string format: date-time createdBy: type: object properties: id: type: string name: type: string Document: type: object properties: id: type: string name: type: string type: type: string enum: - RESUME - COVER_LETTER - ATTACHMENT contentType: type: string size: type: integer addedOn: type: string format: date-time SourceDetails: type: object properties: type: type: string description: The source type (e.g., DIRECT, REFERRAL, LINKEDIN) subtype: type: string refId: type: string