Batch Analysis API

Submit multiple resume–job pairs in a single request. Each item runs through the same premium analysis pipeline used by the single-analysis endpoint.

Authentication

Miri-Api-Key: miri_live_sk_xxxxxxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Every batch request must include a valid MIRI API key. Use X-Request-ID to deduplicate accidental retries at the batch level.

Create Batch

Endpoint

POST /public/v1/analyses/batch

Headers

Miri-Api-Key: miri_live_sk_xxxxxxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
X-Request-ID: 3f3e6d77-9ad3-4ec8-81ad-308b74fb8193 (optional)

Request Body

Content encoding

Each item follows the single-analysis rules: text/html payloads use UTF-8, while pdf/docx payloads are base64-encoded. The total request payload must remain under 10 MB.

{
  "analyses": [
    {
      "referenceId": "candidate-001",
      "resumeData": {
        "type": "pdf",
        "content": "UEsDBBQABgAIAAAAIQAAAAAAAAAAAAAAAAAJAAAAdXJsLnR4dFxTZW5pb3IgQmFja2VuZCBFbmdpbmVlciAtIFJlc3VtZSBFeGNlcnB0cy4uLg=="
      },
      "jobPostingData": {
        "type": "html",
        "content": "<h1>Principal Backend Engineer</h1><p>Lead scalable services...</p>"
      }
    }
  ],
  "options": {
    "parallel": 20,
    "webhook": {
      "url": "https://partner.example.com/webhooks/batch",
      "secret": "optional-hmac-secret"
    }
  }
}

Field Reference

Field	Type	Required	Description
analyses	array	Yes	1–100 analysis items.
analyses[].referenceId	string	Yes	Partner-defined identifier echoed in status responses.
analyses[].resumeData	object	Yes	Same schema as the single Analysis API.
analyses[].resumeData.content	string	Yes	UTF-8 text/HTML, or base64-encoded binary when type is pdf/docx (counts toward the 10 MB limit).
analyses[].jobPostingData	object	Yes	Same schema as the single Analysis API.
analyses[].jobPostingData.content	string	Yes	UTF-8 text/HTML, or base64-encoded binary when type is pdf/docx.
options	object	No	Batch-wide settings.
options.parallel	integer	No	Maximum concurrent workers (1–50, default 10).
options.webhook	object	No	Batch-level webhook configuration.
options.webhook.url	string	Yes	HTTPS endpoint.
options.webhook.secret	string	No	Optional signing secret.

Response (202 Accepted)

{
  "success": true,
  "data": {
    "id": "b59c996e-4d0e-4c08-840a-5a0b4b2bb691",
    "status": "QUEUED",
    "totalCount": 25,
    "estimatedTime": 750,
    "createdAt": "2025-09-19T10:15:23.456Z",
    "webhook": {
      "url": "https://partner.example.com/webhooks/batch",
      "delivery": {
        "state": "PENDING",
        "lastAttemptAt": null,
        "lastStatusCode": null,
        "attemptCount": 0,
        "lastError": null
      }
    },
    "links": {
      "self": "/public/v1/analyses/batch/b59c996e-4d0e-4c08-840a-5a0b4b2bb691",
      "cancel": "/public/v1/analyses/batch/b59c996e-4d0e-4c08-840a-5a0b4b2bb691"
    },
    "metadata": {
      "creditsUsed": 25
    }
  },
  "message": null,
  "code": "SUCCESS",
  "metadata": null
}

Response Fields

Field	Type	Description
id	string	Batch identifier for status polling.
totalCount	integer	Number of analyses submitted.
estimatedTime	integer	totalCount × 30 seconds. Not recalculated after acceptance.
webhook	object/null	Echo of the configured batch webhook plus delivery telemetry.
links.self	string	Status URL for the batch.
links.cancel	string	Cancellation URL (same as self).
metadata.creditsUsed	integer	Credits reserved (equal to totalCount). Omitted while the batch is pending or if reservation fails.

Credit usage

Credits are reserved for every item when the batch is accepted. Actual deductions happen as each underlying analysis completes successfully; items that fail are automatically refunded.

Check Batch Status

Endpoint

GET /public/v1/analyses/batch/{batchId}

Response (200 OK)

{
  "success": true,
  "data": {
    "id": "b59c996e-4d0e-4c08-840a-5a0b4b2bb691",
    "status": "PROCESSING",
    "totalCount": 25,
    "completedCount": 12,
    "failedCount": 1,
    "progressPercentage": 52,
    "items": [
      {
        "referenceId": "candidate-001",
        "status": "COMPLETED",
        "analysisId": "0199f6ac-5c23-41b0-904b-6b9f7c5f2c11",
        "error": null
      },
      {
        "referenceId": "candidate-002",
        "status": "FAILED",
        "analysisId": null,
        "error": {
          "code": "PROCESSING_ERROR",
          "message": "Input validation failed"
        }
      }
    ],
    "createdAt": "2025-09-19T10:15:23.456Z",
    "startedAt": "2025-09-19T10:15:24.010Z",
    "completedAt": null,
    "webhook": {
      "url": "https://partner.example.com/webhooks/batch",
      "delivery": {
        "state": "PENDING",
        "lastAttemptAt": null,
        "lastStatusCode": null,
        "attemptCount": 0,
        "lastError": null
      }
    },
    "links": {
      "self": "/public/v1/analyses/batch/b59c996e-4d0e-4c08-840a-5a0b4b2bb691",
      "cancel": "/public/v1/analyses/batch/b59c996e-4d0e-4c08-840a-5a0b4b2bb691"
    },
    "metadata": {
      "creditsUsed": 25
    }
  },
  "message": null,
  "code": "SUCCESS",
  "metadata": null
}

Field Reference

Field	Type	Description
status	string	QUEUED, PROCESSING, COMPLETED, PARTIAL, FAILED, or CANCELLED.
completedCount	integer	Number of items that finished successfully.
failedCount	integer	Number of items with terminal failure.
progressPercentage	integer	Rounded percent completion across all items.
items[].status	string	PENDING, PROCESSING, COMPLETED, or FAILED.
items[].analysisId	string/null	ID of the single-analysis job (set after creation).
items[].error	object/null	Failure details—code values include PROCESSING_ERROR and CANCELLED.
metadata.creditsUsed	integer	Credits reserved across the batch.

Credit reservation

metadata.creditsUsed reflects the total credits reserved for the batch. Each underlying analysis deducts its credit only when it completes successfully; entries marked FAILED are automatically refunded.

Cancel Batch

DELETE /public/v1/analyses/batch/{batchId}

• Returns 204 No Content when the cancellation request is accepted.
• Allowed while status is QUEUED or PROCESSING.
• Pending items transition to FAILED with error.code = "CANCELLED".

Sandbox Endpoints

Validate integrations without consuming credits.

Create Sandbox Batch

POST /public/v1/analyses/batch/test-run

• Request schema matches the production endpoint.
• Always returns deterministic sample items with metadata.creditsUsed = 0.
• Sandbox batches expire after 10 minutes (NOT001).

Retrieve Sandbox Batch

GET /public/v1/analyses/batch/test-run/{batchId}

Sandbox analysis IDs are only valid for sandbox flows and are rejected by live endpoints.

Webhook Events

When options.webhook.url is provided, the service emits:

• analysis.completed and analysis.failed for each item.
• batch.completed once every item is in a terminal state (COMPLETED, PARTIAL, FAILED, or CANCELLED).

Delivery attempts follow the same policy as the single Analysis API: up to three retries with a fixed two-second interval, and delivery telemetry is reflected in the webhook.delivery object.

Error Codes

Code	HTTP Status	Description
INVALID_API_KEY	401	Missing or malformed Miri-Api-Key.
AUTH001	401	API key authentication failed.
AUTH003	403	Key is suspended.
VAL001	400	Request body cannot be parsed.
VAL002	400	Batch payload missing required fields.
VAL003	400	Field validation failed (type mismatch, invalid size, etc.).
VAL004	400	Payload exceeds the size or batch-count limits.
BUS002	402	Insufficient credits to reserve the batch.
NOT001	404	Batch not found (live or sandbox).
SVC001	503	Temporary platform outage.
SVC002	503	Circuit breaker open.
SVC003	503	Downstream timeout.
INT001	500	Unexpected server error.

Related Endpoints

• Analysis API – Single analysis submission.
• Payment API – Purchase credits used per batch item.