openapi: 3.2.0
info:
  title: Popp Document Credentials API
  description: Popp API documentation
  version: '1'
servers:
- url: https://api.joinpopp.com
  description: Development server
security:
- popp_api_key: []
  organization_id: []
tags:
- name: Document Credentials
paths:
  /v1/document-credentials:
    post:
      summary: Register Document Credential
      description: 'Register a credential Popp uses to fetch a candidate''s protected documentUrl. Stored at the organization-group level behind your API key. Only one credential is allowed per organization group; if one already exists, this returns 409 (update it with PATCH or remove it first). The token is write-only: it is encrypted at rest and never returned. Popp sends it as the {headerTokenKey} header over HTTPS. Authenticated with your API key alone.'
      operationId: create-document-credential
      parameters: []
      tags:
      - Document Credentials
      security:
      - popp_api_key: []
      requestBody:
        description: The credential to register.
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDocumentCredentialRequest'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentCredential'
          headers: {}
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers: {}
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers: {}
        '409':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers: {}
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers: {}
    get:
      summary: List Document Credentials
      description: List the document-fetch credentials for the organization group behind your API key (paginated). Tokens are never returned. Authenticated with your API key alone.
      operationId: list-document-credentials
      parameters:
      - name: limit
        in: query
        description: Maximum number of items per page (1-50). Defaults to 20.
        required: false
        schema:
          $ref: '#/components/schemas/limit-104ed3a6-fe93-428e-850f-2c854880f17b'
      - name: nextToken
        in: query
        description: Pagination token returned by a previous call.
        required: false
        schema:
          $ref: '#/components/schemas/nextToken'
      tags:
      - Document Credentials
      security:
      - popp_api_key: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDocumentCredentialsResponse'
          headers: {}
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers: {}
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers: {}
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers: {}
  /v1/document-credentials/{id}:
    patch:
      summary: Update Document Credential
      description: 'Update or rotate a document-fetch credential. Send only the fields you are changing (for example { "token": "..." } to rotate the key). The token is write-only and never returned. A credential in another organization group returns 404. Authenticated with your API key alone.'
      operationId: update-document-credential
      parameters:
      - name: id
        in: path
        description: The document credential id.
        required: true
        schema:
          $ref: '#/components/schemas/id'
      tags:
      - Document Credentials
      security:
      - popp_api_key: []
      requestBody:
        description: The fields to change.
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDocumentCredentialRequest'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentCredential'
          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: {}
    delete:
      summary: Delete Document Credential
      description: Remove a document-fetch credential. A credential in another organization group returns 404. Authenticated with your API key alone.
      operationId: delete-document-credential
      parameters:
      - name: id
        in: path
        description: The document credential id.
        required: true
        schema:
          $ref: '#/components/schemas/id'
      tags:
      - Document Credentials
      security:
      - popp_api_key: []
      responses:
        '204':
          description: ''
          content: {}
          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:
    ListDocumentCredentialsResponse:
      title: ListDocumentCredentialsResponse
      type: object
      properties:
        items:
          type: array
          description: Document-fetch credentials in the organization group. Tokens are never returned.
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              headerTokenKey:
                type: string
              createdAt:
                type: string
                format: date-time
            required:
            - id
            - name
            - headerTokenKey
            - createdAt
            additionalProperties: false
        nextToken:
          type:
          - string
          - 'null'
      required:
      - items
      - nextToken
      additionalProperties: false
    UpdateDocumentCredentialRequest:
      title: UpdateDocumentCredentialRequest
      type: object
      description: Send only the fields you are changing. At least one is required.
      minProperties: 1
      properties:
        name:
          type: string
        headerTokenKey:
          type: string
        token:
          type: string
          description: New token value to rotate to (max 4096 bytes). Encrypted at rest and never returned.
      additionalProperties: false
    nextToken:
      type: string
    CreateDocumentCredentialRequest:
      title: CreateDocumentCredentialRequest
      type: object
      required:
      - name
      - headerTokenKey
      - token
      properties:
        name:
          type: string
          description: A label for the credential.
        headerTokenKey:
          type: string
          description: Header name Popp should send the token under, e.g. x-api-key or Authorization.
        token:
          type: string
          description: The API key value (max 4096 bytes). Encrypted at rest and never returned.
      additionalProperties: false
    limit-104ed3a6-fe93-428e-850f-2c854880f17b:
      type: integer
      minimum: 1
      maximum: 50
    ErrorResponse:
      type: object
    id:
      type: string
    DocumentCredential:
      title: DocumentCredential
      type: object
      description: A document-fetch credential. The token is write-only and is never returned.
      properties:
        id:
          type: string
        name:
          type: string
        headerTokenKey:
          type: string
          description: Header name Popp sends the token under, e.g. x-api-key.
        createdAt:
          type: string
          format: date-time
      required:
      - id
      - name
      - headerTokenKey
      - createdAt
      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