Documents

During conversations, candidates can share documents such as resumes, certificates, portfolios, and other files. Popp automatically processes and classifies these documents, making them available through the API.

Collecting Documents Workflow

To collect documents from candidates, follow this workflow:

Step 1: Create a Campaign with Document Questions

In the Popp platform, create a campaign that includes document collection:

Navigate to Campaigns → Create Campaign
Add a Document Question to your screening flow
Select the Document Type you want to collect (e.g., Resume, Certificate, Portfolio)
Configure other campaign settings as needed
Save and activate your campaign

The AI agent will automatically ask the candidate to share the specified document type during the conversation.

Step 2: Create Conversations via API

Use the API to create conversations for candidates in your campaign:

curl -X POST "https://api.popp.ai/v1/conversations" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: YOUR_ORGANIZATION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "YOUR_CAMPAIGN_ID",
    "firstName": "John",
    "phoneNumber": "+14155551234",
    "externalId": "candidate-123"
  }'

Step 3: Receive Webhook When Conversation Completes

Set up a webhook to receive notifications when conversations complete. The CONVERSATION_COMPLETED event indicates the candidate has finished the conversation and submitted any requested documents.

{
  "event": "CONVERSATION_COMPLETED",
  "eventId": "evt_abc123",
  "eventTimestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "recordId": "conv_xyz789",
    "organizationId": "org_123456",
    "externalId": "candidate-123",
    "conversationStatus": "COMPLETED"
  }
}

Step 4: Fetch and Process Documents

When you receive the webhook, fetch the documents for that conversation:

async function handleConversationCompleted(webhookPayload: any) {
  const conversationId = webhookPayload.data.recordId;
  const externalId = webhookPayload.data.externalId;

  // Fetch documents from the conversation
  const response = await fetch(
    `https://api.popp.ai/v1/conversations/${conversationId}/documents`,
    {
      headers: {
        'x-api-key': process.env.POPP_API_KEY,
        'x-organization-id': process.env.POPP_ORGANIZATION_ID,
      },
    },
  );

  const { items: documents } = await response.json();

  for (const doc of documents) {
    // Get download URL
    const mediaResponse = await fetch(
      `https://api.popp.ai/v1/documents/${doc.id}/media`,
      {
        headers: {
          'x-api-key': process.env.POPP_API_KEY,
          'x-organization-id': process.env.POPP_ORGANIZATION_ID,
        },
      },
    );

    const media = await mediaResponse.json();

    // Download and save to your system (e.g., S3, ATS)
    await saveDocumentToATS({
      candidateId: externalId,
      fileName: doc.fileName,
      documentType: doc.classifiedDocumentType,
      downloadUrl: media.tempUrl,
    });
  }
}

Complete Workflow Diagram

┌──────────────────────────────────────────────────────────────────────┐
│                     DOCUMENT COLLECTION WORKFLOW                     │
│                                                                      │
│  1. CREATE CAMPAIGN                                                  │
│     └─ Add document questions to screening flow                      │
│                           │                                          │
│                           ▼                                          │
│  2. CREATE CONVERSATIONS (API)                                       │
│     └─ POST /v1/conversations with campaignId                        │
│                           │                                          │
│                           ▼                                          │
│  3. CANDIDATE COMPLETES CONVERSATION                                 │
│     └─ AI agent collects documents from candidate                    │
│                           │                                          │
│                           ▼                                          │
│  4. RECEIVE WEBHOOK                                                  │
│     └─ CONVERSATION_COMPLETED event with conversationId              │
│                           │                                          │
│                           ▼                                          │
│  5. FETCH DOCUMENTS (API)                                            │
│     └─ GET /v1/conversations/{id}/documents                          │
│                           │                                          │
│                           ▼                                          │
│  6. DOWNLOAD & PROCESS                                               │
│     └─ Save to ATS, S3, or your system                               │
└──────────────────────────────────────────────────────────────────────┘

How Documents Work

┌─────────────────────────────────────────────────────────────┐
│                      CONVERSATION                           │
│                                                             │
│   Candidate sends a document (resume, certificate, etc.)    │
│                           │                                 │
│                           ▼                                 │
│   ┌─────────────────────────────────────────────────────┐   │
│   │              DOCUMENT PROCESSING                    │   │
│   │  • File stored securely                             │   │
│   │  • Document type classified by AI                   │   │
│   │  • Metadata extracted                               │   │
│   └─────────────────────────────────────────────────────┘   │
│                           │                                 │
│                           ▼                                 │
│   Available via API: List, Get Details, Download            │
└─────────────────────────────────────────────────────────────┘

Document Properties

Property	Type	Description
`id`	string	Unique document identifier
`fileName`	string	Original file name with extension
`classifiedDocumentType`	string	Document type classified by Popp AI
`contentType`	string	MIME type (e.g., `application/pdf`, `image/jpeg`)
`size`	integer	File size in bytes

Supported File Types

MIME Type	Description
`application/pdf`	PDF documents
`image/jpeg`, `image/png`	Images
`application/msword`	Word documents
`application/vnd.openxmlformats-officedocument.wordprocessingml.document`	Word (DOCX)

Document Classification

Popp's AI automatically classifies documents into types such as:

Resume/CV - Candidate resumes and curriculum vitae
Certificate - Professional certifications and credentials
Portfolio - Work samples and portfolios
ID Document - Identity documents
Other - Unclassified documents

Listing Documents in a Conversation

Retrieve all documents shared in a specific conversation:

curl -X GET "https://api.popp.ai/v1/conversations/{conversationId}/documents" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: YOUR_ORGANIZATION_ID"

Response

{
  "items": [
    {
      "id": "doc_abc123",
      "fileName": "john_doe_resume.pdf",
      "classifiedDocumentType": "Resume",
      "contentType": "application/pdf",
      "size": 245678
    },
    {
      "id": "doc_def456",
      "fileName": "aws_certification.png",
      "classifiedDocumentType": "Certificate",
      "contentType": "image/png",
      "size": 128000
    }
  ],
  "nextToken": null
}

Pagination

For conversations with many documents, use pagination:

curl -X GET "https://api.popp.ai/v1/conversations/{conversationId}/documents?limit=10&nextToken=TOKEN" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: YOUR_ORGANIZATION_ID"

Getting Document Details

Retrieve metadata for a specific document:

curl -X GET "https://api.popp.ai/v1/documents/{documentId}" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: YOUR_ORGANIZATION_ID"

Response

{
  "id": "doc_abc123",
  "fileName": "john_doe_resume.pdf",
  "classifiedDocumentType": "Resume",
  "contentType": "application/pdf",
  "size": 245678
}

Downloading Documents

Step 1: Get a Temporary Download URL

First, request a temporary URL to download the document:

curl -X GET "https://api.popp.ai/v1/documents/{documentId}/media" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: YOUR_ORGANIZATION_ID"

Response

{
  "fileName": "john_doe_resume.pdf",
  "tempUrl": "https://storage.popp.ai/documents/abc123?token=xyz...",
  "contentType": "application/pdf",
  "size": 245678,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

Step 2: Download the File

Use the tempUrl to download the file content:

curl -o resume.pdf "https://storage.popp.ai/documents/abc123?token=xyz..."

Note: The tempUrl is temporary and will expire. Request a new URL if the download fails.

Direct Binary Download

Alternatively, download the document content directly:

curl -X GET "https://api.popp.ai/v1/documents/{documentId}/download" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: YOUR_ORGANIZATION_ID" \
  -o document.pdf

Example: Processing All Documents in a Conversation

interface Document {
  id: string;
  fileName: string;
  classifiedDocumentType: string;
  contentType: string;
  size: number;
}

interface MediaResponse {
  fileName: string;
  tempUrl: string;
  contentType: string;
  size: number;
}

async function downloadConversationDocuments(conversationId: string) {
  // 1. List all documents in the conversation
  const response = await fetch(
    `https://api.popp.ai/v1/conversations/${conversationId}/documents`,
    {
      headers: {
        'x-api-key': process.env.POPP_API_KEY,
        'x-organization-id': process.env.POPP_ORGANIZATION_ID,
      },
    },
  );

  const { items: documents } = await response.json();

  // 2. Process each document
  for (const doc of documents) {
    console.log(`Processing: ${doc.fileName} (${doc.classifiedDocumentType})`);

    // 3. Get download URL
    const mediaResponse = await fetch(
      `https://api.popp.ai/v1/documents/${doc.id}/media`,
      {
        headers: {
          'x-api-key': process.env.POPP_API_KEY,
          'x-organization-id': process.env.POPP_ORGANIZATION_ID,
        },
      },
    );

    const media: MediaResponse = await mediaResponse.json();

    // 4. Download the file
    const fileContent = await fetch(media.tempUrl);
    // Save or process the file content...

    console.log(`Downloaded: ${doc.fileName}`);
  }
}

Use Cases

Resume Storage: Automatically collect and store candidate resumes from conversations
Document Verification: Review certificates and credentials shared by candidates
ATS Integration: Sync documents to your applicant tracking system
Compliance: Archive all documents exchanged during the hiring process

API Reference

List Conversation Documents - Get all documents in a conversation
Get Document - Get document metadata
Get Document Media - Get temporary download URL
Download Media - Download document content

Next Steps

Understanding Conversations - Learn about conversation lifecycle
Webhooks - Get notified about conversation events