openapi: 3.2.0 info: title: Popp Analysis API description: Popp API documentation version: '1' servers: - url: https://api.joinpopp.com description: Development server security: - popp_api_key: [] organization_id: [] tags: - name: Analysis paths: /v1/analyses: post: summary: Create analysis description: Creates a new analysis with the given title, job description, and requirements. Immediately starts processing. operationId: create-analysis parameters: [] tags: - Analysis requestBody: description: The input to create an analysis required: true content: application/json: schema: $ref: '#/components/schemas/CreateAnalysisInput' responses: '201': description: '' content: application/json: schema: $ref: '#/components/schemas/Analysis' headers: {} '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: {} '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: {} get: summary: List analyses description: 'Lists the organization''s analyses, with optional filtering. Analyses managed by Workflow Builder (`isWorkflowManaged: true`) are left out. A page can hold fewer items than `limit`, or none, and still return a `nextToken`: keep paging until `nextToken` is null.' operationId: list-analyses parameters: - name: limit in: query description: Maximum number of results to return (1-50) required: false schema: $ref: '#/components/schemas/limit' - name: nextToken in: query description: Pagination token from a previous response required: false schema: $ref: '#/components/schemas/nextToken' - name: status in: query description: Filter analyses by status required: false schema: $ref: '#/components/schemas/status-3c845253-19cc-46fa-bf36-1e2b52143644' - name: externalId in: query description: Filter analyses by external ID required: false schema: $ref: '#/components/schemas/externalId' tags: - Analysis responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/ListAnalysesResponse' headers: {} '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: {} '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: {} /v1/analyses/generate-requirements: post: summary: Generate requirements description: Uses AI to extract requirements from a job description. Stateless - does not create or modify any data. operationId: generate-requirements parameters: [] tags: - Analysis requestBody: description: The job description to extract requirements from required: true content: application/json: schema: $ref: '#/components/schemas/GenerateRequirementsInput' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/GenerateRequirementsResponse' headers: {} '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: {} '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: {} /v1/analyses/{id}: get: summary: Get analysis description: Get a single analysis with full requirements operationId: get-analysis parameters: - name: id in: path description: The ID of the analysis to get required: true schema: $ref: '#/components/schemas/id' tags: - Analysis responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/Analysis' headers: {} '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: {} '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: {} '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: {} put: summary: Update analysis description: Update analysis metadata (title, job description, external ID). Does not update requirements. operationId: update-analysis parameters: - name: id in: path description: The ID of the analysis to update required: true schema: $ref: '#/components/schemas/id' tags: - Analysis requestBody: description: The fields to update (at least one required) required: true content: application/json: schema: $ref: '#/components/schemas/UpdateAnalysisInput' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/Analysis' headers: {} '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: {} '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: {} '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: {} /v1/analyses/{id}/archive: post: summary: Archive analysis description: 'Archives an analysis (soft delete). Only DRAFT or LIVE analyses can be archived. Archiving an already-archived analysis is idempotent. An analysis managed by Workflow Builder can''t be archived here: the request returns 400, even if the analysis is already archived.' operationId: archive-analysis parameters: - name: id in: path description: The ID of the analysis to archive required: true schema: $ref: '#/components/schemas/id' tags: - Analysis responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/Analysis' headers: {} '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: {} '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: {} '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: {} /v1/analyses/{id}/update-requirements-and-reanalyse: post: summary: Update requirements and reanalyse description: Replaces all requirements on the analysis and triggers re-analysis of existing candidates. Requirements with an ID are updated, without an ID are created, and existing requirements not in the array are deleted. Only DRAFT or LIVE analyses can be updated. operationId: update-requirements-and-reanalyse parameters: - name: id in: path description: The ID of the analysis to update requirements for required: true schema: $ref: '#/components/schemas/id' tags: - Analysis requestBody: description: The new set of requirements required: true content: application/json: schema: $ref: '#/components/schemas/UpdateRequirementsInput' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/Analysis' headers: {} '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: {} '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: {} '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: {} /v1/analysis/candidates: post: summary: Create analysis candidate description: Queues a CV or questionnaire for scoring against an analysis. operationId: create-analysis-candidate parameters: [] tags: - Analysis requestBody: description: The input to create an analysis candidate required: true content: application/json: schema: $ref: '#/components/schemas/CreateAnalysisCandidateInput' responses: '202': description: '' content: application/json: schema: $ref: '#/components/schemas/CreateAnalysisCandidateResponse' headers: {} '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: {} '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: {} '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: {} '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: {} components: schemas: externalId: type: string UpdateRequirementsInput: type: object required: - requirements properties: requirements: type: array minItems: 1 items: type: object required: - text properties: id: type: string description: The requirement ID. Include to update an existing requirement. Omit to create a new one. Existing requirements not included in the array will be deleted. text: type: string minLength: 1 description: The requirement text. isMandatory: type: boolean default: false description: Whether this is a knockout requirement. weight: type: number default: 1 description: Scoring weight for this requirement. description: The full set of requirements. This replaces all existing requirements. additionalProperties: false nextToken: type: string Analysis: type: object properties: id: type: string description: The unique identifier for the analysis. title: type: string description: The title of the analysis. jobDescription: type: string description: The job description text. status: type: string enum: - DRAFT - PROCESSING - LIVE - ARCHIVED description: The current status of the analysis. requirements: type: array items: type: object properties: id: type: string description: The unique identifier for the requirement. text: type: string description: The original requirement text. generatedText: type: - string - 'null' description: AI-generated version of the requirement text. isMandatory: type: boolean description: Whether this is a knockout requirement. weight: type: number description: Scoring weight for this requirement. description: The analysis requirements. Only included in single analysis responses. candidatesCount: type: integer description: Total number of candidates in the analysis. candidatesRequirementsMetCount: type: integer description: Number of candidates who met requirements. candidatesRequirementsNotMetCount: type: integer description: Number of candidates who did not meet requirements. externalId: type: - string - 'null' description: External system identifier. isWorkflowManaged: type: - boolean - 'null' description: True when the analysis was created for an analysis node in a published workflow. A workflow-managed analysis can't be edited, archived or sent candidates through the analysis endpoints. To use different requirements, publish a new version of the workflow. Its results are read under the workflow (`GET /v1/workflows/{workflowId}/analyses/{workflowNodeSlug}`). Null for an analysis created outside workflows. workflowId: type: - string - 'null' description: The workflow the analysis belongs to. workflowVersionId: type: - string - 'null' description: The workflow version that created the analysis. workflowRunId: type: - string - 'null' description: Not used for analyses. Always null. workflowNodeId: type: - string - 'null' description: The analysis node's id in that workflow version. workflowNodeSlug: type: - string - 'null' description: The analysis node's slug. Returned by `GET /v1/analyses/{id}`; null elsewhere. createdAt: type: string format: date-time description: ISO 8601 timestamp of creation. updatedAt: type: string format: date-time description: ISO 8601 timestamp of last update. CreateAnalysisInput: type: object required: - title - jobDescription - requirements properties: title: type: string minLength: 1 description: The title of the analysis. jobDescription: type: string minLength: 1 description: The full job description text. requirements: type: array minItems: 1 items: type: object required: - text properties: text: type: string minLength: 1 description: The requirement text. isMandatory: type: boolean default: false description: Whether this is a knockout requirement. weight: type: number default: 1 description: Scoring weight for this requirement, as a positive whole number. A fractional weight is accepted but treated as 1. description: The analysis requirements. externalId: type: string description: External system identifier. additionalProperties: false limit: type: integer CreateAnalysisCandidateResponse: type: object properties: message: type: string required: - message additionalProperties: false CreateAnalysisCandidateInput: type: object properties: analysisId: type: string title: Analysis ID description: The unique identifier for the analysis. externalAnalysisId: type: string title: External Analysis ID description: The unique identifier for the analysis in the external system. Surrounding whitespace is removed before the analysis is resolved. documentUrl: type: string format: uri title: Document URL description: The URL of the document to analyze. Must be a valid URL. documentBase64: type: string title: Document Base64 description: The base64-encoded content of the document to analyze. firstName: type: string title: First Name description: The first name of the candidate. lastName: type: string title: Last Name description: The last name of the candidate. phoneNumber: type: string title: Phone Number description: The phone number of the candidate in E.164 format. emailAddress: type: string format: email title: Email Address description: The email address of the candidate. externalId: type: string title: External ID description: The unique identifier for the candidate in the external system. documentType: type: string enum: - cv - questionnaire default: cv title: Document Type description: The type of document being uploaded. Defaults to 'cv'. oneOf: - title: Analysis ID Required description: Either analysisId or externalAnalysisId is required. required: - analysisId - title: External Analysis ID Required description: Either externalAnalysisId or analysisId is required. required: - externalAnalysisId additionalProperties: false status-3c845253-19cc-46fa-bf36-1e2b52143644: type: string enum: - DRAFT - PROCESSING - LIVE - ARCHIVED ErrorResponse: type: object GenerateRequirementsResponse: type: object properties: requirements: type: array items: type: object properties: text: type: string description: The suggested requirement text. isMandatory: type: boolean description: Whether this is a knockout requirement. weight: type: number description: Scoring weight (default 1.0). ListAnalysesResponse: type: object properties: data: type: array items: type: object properties: id: type: string description: The unique identifier for the analysis. title: type: string description: The title of the analysis. jobDescription: type: string description: The job description text. status: type: string enum: - DRAFT - PROCESSING - LIVE - ARCHIVED description: The current status of the analysis. requirements: type: array items: type: object properties: id: type: string description: The unique identifier for the requirement. text: type: string description: The original requirement text. generatedText: type: - string - 'null' description: AI-generated version of the requirement text. isMandatory: type: boolean description: Whether this is a knockout requirement. weight: type: number description: Scoring weight for this requirement. description: The analysis requirements. Only included in single analysis responses. candidatesCount: type: integer description: Total number of candidates in the analysis. candidatesRequirementsMetCount: type: integer description: Number of candidates who met requirements. candidatesRequirementsNotMetCount: type: integer description: Number of candidates who did not meet requirements. externalId: type: - string - 'null' description: External system identifier. isWorkflowManaged: type: - boolean - 'null' description: True when the analysis was created for an analysis node in a published workflow. A workflow-managed analysis can't be edited, archived or sent candidates through the analysis endpoints. To use different requirements, publish a new version of the workflow. Its results are read under the workflow (`GET /v1/workflows/{workflowId}/analyses/{workflowNodeSlug}`). Null for an analysis created outside workflows. workflowId: type: - string - 'null' description: The workflow the analysis belongs to. workflowVersionId: type: - string - 'null' description: The workflow version that created the analysis. workflowRunId: type: - string - 'null' description: Not used for analyses. Always null. workflowNodeId: type: - string - 'null' description: The analysis node's id in that workflow version. workflowNodeSlug: type: - string - 'null' description: The analysis node's slug. Returned by `GET /v1/analyses/{id}`; null elsewhere. createdAt: type: string format: date-time description: ISO 8601 timestamp of creation. updatedAt: type: string format: date-time description: ISO 8601 timestamp of last update. description: List of analyses. nextToken: type: - string - 'null' description: Pagination token for the next page of results. Null on the last page. A page can hold fewer items than `limit`, or none, while more pages remain. id: type: string GenerateRequirementsInput: type: object required: - jobDescription properties: jobDescription: type: string minLength: 1 description: The full job description text to extract requirements from. additionalProperties: false UpdateAnalysisInput: type: object properties: title: type: string minLength: 1 description: The title of the analysis. jobDescription: type: string minLength: 1 description: The full job description text. externalId: type: string minLength: 1 description: External system identifier. minProperties: 1 additionalProperties: false securitySchemes: popp_api_key: description: Your Popp API key for authentication type: apiKey name: x-api-key in: header organization_id: description: Your organization's unique identifier type: apiKey name: x-organization-id in: header x-provenance: method: searched source: https://docs.joinpopp.com/reference harvested: '2026-10-14' tool: harvest-readme-openapi.py note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored. assembled_from: - https://docs.joinpopp.com/reference/add-candidates-to-list-by-external-id.md - https://docs.joinpopp.com/reference/add-candidates-to-list.md - https://docs.joinpopp.com/reference/archive-analysis.md - https://docs.joinpopp.com/reference/archive-document-type.md - https://docs.joinpopp.com/reference/archive-workflow-by-external-id.md - https://docs.joinpopp.com/reference/archive-workflow.md - https://docs.joinpopp.com/reference/bulk-create-conversations.md - https://docs.joinpopp.com/reference/cancel-booking.md - https://docs.joinpopp.com/reference/cancel-workflow-run.md - https://docs.joinpopp.com/reference/create-analysis-candidate.md - https://docs.joinpopp.com/reference/create-analysis.md - https://docs.joinpopp.com/reference/create-campaign.md - https://docs.joinpopp.com/reference/create-candidate-list.md - https://docs.joinpopp.com/reference/create-candidate-note-by-external-id.md - https://docs.joinpopp.com/reference/create-candidate-note.md - https://docs.joinpopp.com/reference/create-candidate.md - https://docs.joinpopp.com/reference/create-conversation.md - https://docs.joinpopp.com/reference/create-custom-field.md - https://docs.joinpopp.com/reference/create-document-credential.md - https://docs.joinpopp.com/reference/create-document-type.md - https://docs.joinpopp.com/reference/create-meeting-template.md - https://docs.joinpopp.com/reference/create-organization-config.md - https://docs.joinpopp.com/reference/create-scheduling-conversation.md - https://docs.joinpopp.com/reference/create-user.md - https://docs.joinpopp.com/reference/create-webhook.md - https://docs.joinpopp.com/reference/create-workflow.md - https://docs.joinpopp.com/reference/deactivate-user-by-email.md - https://docs.joinpopp.com/reference/deactivate-user.md - https://docs.joinpopp.com/reference/delete-candidate-by-email.md - https://docs.joinpopp.com/reference/delete-candidate-by-external-id.md - https://docs.joinpopp.com/reference/delete-candidate-by-phone-number.md - https://docs.joinpopp.com/reference/delete-candidate-list-by-external-id.md - https://docs.joinpopp.com/reference/delete-candidate-list.md - https://docs.joinpopp.com/reference/delete-candidate-note.md - https://docs.joinpopp.com/reference/delete-candidate.md - https://docs.joinpopp.com/reference/delete-custom-field.md - https://docs.joinpopp.com/reference/delete-document-credential.md - https://docs.joinpopp.com/reference/delete-document-type.md - https://docs.joinpopp.com/reference/delete-meeting-template.md - https://docs.joinpopp.com/reference/delete-tag.md - https://docs.joinpopp.com/reference/delete-user-by-email.md - https://docs.joinpopp.com/reference/delete-user.md - https://docs.joinpopp.com/reference/delete-webhook.md - https://docs.joinpopp.com/reference/download-media.md - https://docs.joinpopp.com/reference/generate-preferred-answer-requirements.md - https://docs.joinpopp.com/reference/generate-questions.md - https://docs.joinpopp.com/reference/generate-requirements.md - https://docs.joinpopp.com/reference/get-analysis.md - https://docs.joinpopp.com/reference/get-booking.md - https://docs.joinpopp.com/reference/get-campaign.md - https://docs.joinpopp.com/reference/get-candidate-by-external-id.md - https://docs.joinpopp.com/reference/get-candidate-list-by-external-id.md - https://docs.joinpopp.com/reference/get-candidate-list.md - https://docs.joinpopp.com/reference/get-candidate-profile-by-external-id.md - https://docs.joinpopp.com/reference/get-candidate.md - https://docs.joinpopp.com/reference/get-conversation.md - https://docs.joinpopp.com/reference/get-custom-field.md - https://docs.joinpopp.com/reference/get-document-media.md - https://docs.joinpopp.com/reference/get-document-type.md - https://docs.joinpopp.com/reference/get-document.md - https://docs.joinpopp.com/reference/get-meeting-template.md - https://docs.joinpopp.com/reference/get-organization-config-by-external-id.md - https://docs.joinpopp.com/reference/get-organization-config.md - https://docs.joinpopp.com/reference/get-organization-details.md - https://docs.joinpopp.com/reference/get-user-by-email.md - https://docs.joinpopp.com/reference/get-user-calendar.md - https://docs.joinpopp.com/reference/get-user.md - https://docs.joinpopp.com/reference/get-workflow-analysis-application.md - https://docs.joinpopp.com/reference/get-workflow-analysis.md - https://docs.joinpopp.com/reference/get-workflow-by-external-id.md - https://docs.joinpopp.com/reference/get-workflow-run.md - https://docs.joinpopp.com/reference/get-workflow.md - https://docs.joinpopp.com/reference/hand-conversation-to-agent.md - https://docs.joinpopp.com/reference/invite-calendar-contact.md - https://docs.joinpopp.com/reference/list-agents.md - https://docs.joinpopp.com/reference/list-analyses.md - https://docs.joinpopp.com/reference/list-ats-job-stages.md - https://docs.joinpopp.com/reference/list-ats-jobs.md - https://docs.joinpopp.com/reference/list-ats-rejection-reasons.md - https://docs.joinpopp.com/reference/list-bookings.md - https://docs.joinpopp.com/reference/list-campaigns.md - https://docs.joinpopp.com/reference/list-candidate-lists.md - https://docs.joinpopp.com/reference/list-candidate-notes-by-external-id.md - https://docs.joinpopp.com/reference/list-candidate-notes.md - https://docs.joinpopp.com/reference/list-conversation-documents.md - https://docs.joinpopp.com/reference/list-conversation-messages.md - https://docs.joinpopp.com/reference/list-conversations.md - https://docs.joinpopp.com/reference/list-custom-fields.md - https://docs.joinpopp.com/reference/list-document-credentials.md - https://docs.joinpopp.com/reference/list-document-types.md - https://docs.joinpopp.com/reference/list-meeting-templates.md - https://docs.joinpopp.com/reference/list-organization-users.md - https://docs.joinpopp.com/reference/list-organizations.md - https://docs.joinpopp.com/reference/list-tags.md - https://docs.joinpopp.com/reference/list-templates.md - https://docs.joinpopp.com/reference/list-user-calendars.md - https://docs.joinpopp.com/reference/list-users.md - https://docs.joinpopp.com/reference/list-webhook-events.md - https://docs.joinpopp.com/reference/list-webhooks.md - https://docs.joinpopp.com/reference/list-workflow-analysis-application-history.md - https://docs.joinpopp.com/reference/list-workflow-analysis-applications.md - https://docs.joinpopp.com/reference/list-workflow-runs.md - https://docs.joinpopp.com/reference/list-workflows.md - https://docs.joinpopp.com/reference/parse-availability.md - https://docs.joinpopp.com/reference/pause-workflow-by-external-id.md - https://docs.joinpopp.com/reference/pause-workflow.md - https://docs.joinpopp.com/reference/process-document.md - https://docs.joinpopp.com/reference/publish-workflow-by-external-id.md - https://docs.joinpopp.com/reference/publish-workflow.md - https://docs.joinpopp.com/reference/reactivate-user-by-email.md - https://docs.joinpopp.com/reference/reactivate-user.md - https://docs.joinpopp.com/reference/remove-candidate-document-by-external-id.md - https://docs.joinpopp.com/reference/remove-candidate-document.md - https://docs.joinpopp.com/reference/remove-candidates-from-list-by-external-id.md - https://docs.joinpopp.com/reference/remove-candidates-from-list.md - https://docs.joinpopp.com/reference/reparse-candidate-cv-by-external-id.md - https://docs.joinpopp.com/reference/reparse-candidate-cv.md - https://docs.joinpopp.com/reference/resend-booking-url.md - https://docs.joinpopp.com/reference/resume-workflow-by-external-id.md - https://docs.joinpopp.com/reference/resume-workflow.md - https://docs.joinpopp.com/reference/send-conversation-message.md - https://docs.joinpopp.com/reference/set-user-calendar-availability.md - https://docs.joinpopp.com/reference/sign-out-user-by-email.md - https://docs.joinpopp.com/reference/sign-out-user.md - https://docs.joinpopp.com/reference/start-workflow-runs-by-external-id.md - https://docs.joinpopp.com/reference/start-workflow-runs.md - https://docs.joinpopp.com/reference/stop-campaign.md - https://docs.joinpopp.com/reference/takeover-conversation.md - https://docs.joinpopp.com/reference/update-analysis.md - https://docs.joinpopp.com/reference/update-booking.md - https://docs.joinpopp.com/reference/update-campaign.md - https://docs.joinpopp.com/reference/update-candidate-by-external-id.md - https://docs.joinpopp.com/reference/update-candidate-list-by-external-id.md - https://docs.joinpopp.com/reference/update-candidate-list.md - https://docs.joinpopp.com/reference/update-candidate-note.md - https://docs.joinpopp.com/reference/update-candidate.md - https://docs.joinpopp.com/reference/update-custom-field.md - https://docs.joinpopp.com/reference/update-document-credential.md - https://docs.joinpopp.com/reference/update-document-type.md - https://docs.joinpopp.com/reference/update-meeting-template.md - https://docs.joinpopp.com/reference/update-organization-config-by-external-id.md - https://docs.joinpopp.com/reference/update-organization-config.md - https://docs.joinpopp.com/reference/update-organization-details.md - https://docs.joinpopp.com/reference/update-requirements-and-reanalyse.md - https://docs.joinpopp.com/reference/update-user-by-email.md - https://docs.joinpopp.com/reference/update-user.md - https://docs.joinpopp.com/reference/update-webhook.md - https://docs.joinpopp.com/reference/update-workflow-by-external-id.md - https://docs.joinpopp.com/reference/update-workflow.md merge: pages: 149 deduped: 618 conflicts_kept_first: 0