Developer API Documentation

1. Ingesting Job Descriptions

Submit a job listing text or PDF storage ID to parse and extract hard skills, soft skills, and ATS keywords:

POST /api/v1/jobs/process
Headers: { "Authorization": "Bearer <YOUR_KEY>" }
Body:
{
  "companyName": "Google",
  "jobTitle": "L4 Frontend Engineer",
  "rawJdText": "We are looking for React, TypeScript, and state management experts..."
}

The job description ingestion endpoint accepts both raw text input and references to previously uploaded PDF documents. When submitting a PDF, the system extracts text using OCR and natural language processing before beginning the skill extraction pipeline. The response includes extracted hard skills, soft skills, required experience levels, and an ATS keyword density map that shows which terms from the JD appear most frequently.

2. Tailoring Response Schema

The API returns tailored JSON matching the candidate master profile layout:

{
  "structuredContent": {
    "personalInfo": { "name": "..." },
    "experience": [
      {
        "company": "...",
        "bullets": ["Optimized dashboard rendering using React code-splitting..."]
      }
    ]
  },
  "atsCompatibilityScore": 92
}

The tailoring response includes not only the rewritten resume content but also metadata about the tailoring process: which sections were modified, what skill gaps were identified, and a comparison score between the original profile and the tailored version. The ATS compatibility score ranges from 0 to 100 and reflects how well the tailored content aligns with the extracted keywords from the job description.

3. Authentication and Rate Limiting

All API requests require authentication via Bearer token in the Authorization header. Tokens are issued per user account and can be generated from the API Settings page in your dashboard. Each token carries the same quota limits as your account tier. Free tier accounts are limited to 50 API requests per 24-hour rolling window. Pro and Campus accounts have significantly higher limits with burst capacity for batch processing.

Rate limiting is enforced using a sliding window algorithm. The response headers include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset Unix timestamp fields. When you exceed your rate limit, the API returns HTTP 429 (Too Many Requests) with a Retry-After header indicating when you can resume. Implement exponential backoff in your integration to handle rate limits gracefully.

4. Webhook Integration for Real-Time Updates

ResumeFlow supports webhook callbacks for asynchronous job processing. When you submit a tailoring request, the system immediately returns a job ID and processes the request in the background. Once processing completes, the system sends a POST request to your configured webhook URL with the full tailoring response payload.

// Webhook payload example
{
  "jobId": "job_abc123",
  "status": "completed",
  "payload": {
    "structuredContent": { /* tailored resume */ },
    "atsCompatibilityScore": 94,
    "processingTimeMs": 2847
  }
}

Configure webhook endpoints in your dashboard settings. We support retry logic for failed deliveries: if your endpoint returns a non-2xx status code, we retry up to 3 times with exponential backoff (10s, 60s, 300s). Webhook payloads are signed with an HMAC-SHA256 signature sent in the X-Signature header so you can verify the authenticity of incoming callbacks.

5. Error Handling and Best Practices

The API uses conventional HTTP response codes to indicate success and failure. 200-level responses indicate successful processing. 400-level errors indicate client-side issues such as invalid input format, missing required fields, or authentication failures. 500-level errors indicate server-side issues — implement retry logic with backoff for these cases.

• 400 Bad Request: Invalid JSON payload or missing required fields. Check your request structure against the schema documentation.
• 401 Unauthorized: Missing or invalid authentication token. Verify your Bearer token is current and correctly formatted.
• 402 Payment Required: Account quota exhausted. Upgrade your plan or wait for quota reset at midnight UTC.
• 429 Too Many Requests: Rate limit exceeded. Check Retry-After header and implement backoff.
• 5xx Server Errors: Temporary server issues. Retry with exponential backoff starting at 5 seconds, doubling up to a maximum of 300 seconds.

For production integrations, implement idempotency keys for critical operations to prevent duplicate processing in case of network retries. Send an Idempotency-Key header with a unique UUID for each request — if the same key is received within 24 hours, the system returns the cached response from the original request rather than processing a duplicate.