Torch USCIS Case Status API (Beta)

Developers › Torch API › Case Status

Get real‑time USCIS receipt tracking in your apps with normalized categories and optional webhooks. Torch is currently in beta and available by request.

Get Torch API key →

Torch quickstart code samples

Use your beta base URL and API key from onboarding.

• Environment variables

• BASE_URL: your Torch environment base URL

• PARLEY_API_KEY: your issued API key

• curl

curl -G "$BASE_URL/case-status" \
 -H "Authorization: Bearer $PARLEY_API_KEY" \
 --data-urlencode "receipt=ABC1234567890"

• Node.js (native fetch, Node 18+)

const BASE_URL = process.env. BASE_URL;
const KEY = process.env. PARLEY_API_KEY;

async function getStatus(receipt) {
 const url = new URL(`${BASE_URL}/case-status`);
 url.searchParams.set('receipt', receipt);
 const res = await fetch(url, {
 headers: { Authorization: `Bearer ${KEY}` }
 });
 if (!res.ok) throw new Error(`HTTP ${res.status}`);
 return res.json();
}

getStatus('ABC1234567890').then(console.log).catch(console.error);

• Python (requests)

import os, requests
BASE_URL = os.environ["BASE_URL"]
API_KEY = os.environ["PARLEY_API_KEY"]

resp = requests.get(
 f"{BASE_URL}/case-status",
 headers={"Authorization": f"Bearer {API_KEY}"},
 params={"receipt": "ABC1234567890"},
 timeout=15,
)
resp.raise_for_status()
print(resp.json())

Torch OpenAPI snippet (beta)

The exact shape may vary by environment; your onboarding pack is authoritative.

openapi: 3.0.3
info:
 title: Torch USCIS Case Status API (Beta)
 version: v1-beta
servers:

 - url: https://{region}.torch.parley.so
 variables:
 region:
 default: us
paths:
 /case-status:
 get:
 summary: Get latest status for a single receipt
 parameters:

 - in: query
 name: receipt
 required: true
 schema: { type: string }
 responses:
 '200':
 description: OK
 content:
 application/json:
 schema:
 type: object
 properties:
 receipt_number: { type: string }
 status_text: { type: string }
 status_category: { type: string }
 last_checked_at: { type: string, format: date-time }
 last_status_at: { type: string, format: date-time }
 source_hint: { type: string }
 '400': { description: Bad request }
 '401': { description: Unauthorized }
 '404': { description: Not found }
 '429': { description: Rate limited }
 /case-status/batch:
 get:
 summary: Get statuses for multiple receipts
 parameters:

 - in: query
 name: receipt
 required: true
 schema:
 type: array
 items: { type: string }
 style: form
 explode: true
 responses:
 '200':
 description: OK
 content:
 application/json:
 schema:
 type: array
 items:
 $ref: '#/components/schemas/Status'
components:
 schemas:
 Status:
 type: object
 properties:
 receipt_number: { type: string }
 status_text: { type: string }
 status_category: { type: string, description: 'e.g., Case Received, Request for Evidence, Approved, Rejected' }
 last_checked_at: { type: string, format: date-time }
 last_status_at: { type: string, format: date-time }
 source_hint: { type: string }
security:

 - bearerAuth: []
components:
 securitySchemes:
 bearerAuth:
 type: http
 scheme: bearer
 bearerFormat: JWT

Need access?

Torch is in closed beta. Request access and the Postman collection via the contact form; include “Torch API (Case Status)” in your note.

Request Torch access →

Introduction

The USCIS Torch API is Parley’s programmatic interface for retrieving and monitoring USCIS case status updates by receipt number. It builds on the same live tracking capabilities already available in Parley’s AI‑native case management, now exposed for developers as a beta service. This page covers quickstart, authentication, rate limits, and webhooks, with a request path for the Postman collection. For background on Parley’s live case tracking and AI case management features, see the July and June product updates and platform pages. Parley AI Case Management – July changelog, June changelog, Parley platform overview, Privacy Policy, Terms and Use Agreement.

What the API does

• Programmatic read access to current case status text for a USCIS receipt number.

• Event delivery when Parley detects a status change (webhooks; beta).

• Consistent normalization so your apps can key off both the raw USCIS text and a stable category.

• Designed for integration into case management systems, internal dashboards, CRMs, and workflow automation. For context on Parley’s underlying live tracking within the product UI, see the July changelog (“The USCIS API is live… start receiving updates on your case”). Source.

Data model (beta)

Returned objects include the information your systems typically need to reconcile status changes, without altering the official meaning of USCIS text:

• receipt_number: the USCIS receipt identifier you provide

• status_text: latest USCIS case status string as observed

• status_category: normalized category (e.g., “Case Received”, “Request for Evidence”, “Approved”, “Rejected”); categories may expand over time

• last_checked_at: timestamp Parley last observed the case

• last_status_at: timestamp Parley last observed this specific status_text

• source_hint: human‑readable note indicating that official status remains USCIS

Note: Field names and categories may evolve during beta; do not hardcode against the exact text. The goal is stability in category semantics, not immutability of labels.

Quickstart

1) Request beta access and keys

• Visit Parley’s Contact page and request “Torch API (Case Status) beta.” You’ll receive onboarding details and credentials. Contact Parley.

2) Add your credentials to your environment

• Store the issued API key as PARLEY_API_KEY and your region‑specific base URL as BASE_URL (provided in your welcome email).

3) Make your first read call

• Example (shell):

curl -G "$BASE_URL/case-status" \ -H "Authorization: Bearer $PARLEY_API_KEY" \ --data-urlencode "receipt=ABC1234567890"

4) Register a webhook endpoint (optional, recommended)

• During beta, register webhooks via your Parley onboarding form or with your Parley contact. Programmatic registration will be offered after beta.

5) Verify delivery and idempotency

• Your endpoint should treat repeated notifications of the same status as idempotent. Persist by (receipt_number + last_status_at) or a delivered event_id if present in your onboarding pack.

6) Move to production usage

• Start with a small subset of receipts, monitor logs, and then scale. Contact Parley to discuss workload patterns and throughput before high‑volume use. June changelog – real‑time tracking from dashboard.

Authentication

• Scheme: Bearer token over HTTPS.

• Provisioning: Keys are issued during beta onboarding and can be rotated on request.

• Storage: Treat keys as secrets; avoid embedding in client‑side code.

• Compliance context: Parley maintains SOC 2 Type 2 and GDPR compliance for its platform; your use of the API remains subject to Parley’s Privacy Policy and Terms. Privacy, Terms, Platform overview citing SOC2/GDPR.

Endpoints (beta)

Endpoints at a glance

Note: Paths and params may be version‑prefixed or vary slightly by environment. Use your onboarding pack as the source of truth.

Webhook payload (beta) example

During beta, Parley delivers a JSON body when a status changes. Field names may vary by environment; confirm against your onboarding pack.

{
 "type": "case.status.updated",
 "data": {
 "receipt_number": "ABC1234567890",
 "status_text": "Case Was Received",
 "status_category": "Case Received",
 "last_status_at": "2025-01-15T14:03:27Z"
 },
 "id": "evt_01hx...",
 "sent_at": "2025-01-15T14:03:30Z"
}

Recommended verification and handling

• Authenticate: Webhook requests include a shared secret header (name provided in onboarding). Validate this value server‑side before processing.

• Idempotency: De‑dupe by event id if present, or by (receipt_number + last_status_at).

• Retries: Expect retries with backoff on non‑2xx. Return 2xx only after durable persistence.

Authentication details (recap)

• Header: Authorization: Bearer YOUR_API_KEY

• Transport: HTTPS only. Do not expose keys in client‑side code.

• Rotation: Keys can be rotated during beta on request via your Parley contact.

Quick 5‑minute test plan

1) Set BASE_URL and PARLEY_API_KEY from your onboarding email. 2) Call GET /case-status with a known test receipt. 3) Register your webhook URL via your onboarding form (optional). 4) Trigger a test delivery with your Parley contact; verify signature and idempotency. 5) Import the Postman collection from your onboarding pack to explore batch reads.

Versioning and changelog

• v1‑beta: Initial release with GET /case-status, GET /case-status/batch, and private webhooks. Announced alongside live tracking in Parley’s product updates; see the July and June changelogs for context on the underlying tracking capabilities now exposed via API. July changelog, June changelog. The following resource design is available to beta participants. Exact parameter names or headers may vary by environment; your welcome pack is the source of truth.

• GET /case-status

• Purpose: Return the latest status for a single receipt.

• Required query parameter: receipt

• Returns: fields described in Data model (beta) above.

• GET /case-status/batch

• Purpose: Retrieve statuses for multiple receipts using repeated receipt parameters.

• Required query parameters: receipt (repeatable)

• Returns: list of status objects.

Note: Endpoint paths may be prefixed by a version segment (e.g., v1) in your environment. Use the base URL provided during onboarding.

Webhooks

• Event type(s): case.status.updated (additional types may be added during beta).

• Delivery: HTTPS POST to your registered endpoint when a status changes.

• Payload: includes receipt_number, status_text, status_category, last_status_at, and metadata to ensure idempotency. Exact field names are provided in your onboarding pack.

• Security: Webhook requests include authentication material (e.g., a shared secret header). Validate all incoming requests server‑side before processing.

• Retries: Parley retries on non‑2xx responses with backoff. Design your endpoint to be idempotent and fast.

Rate limits and fair use

• The beta enforces per‑minute and daily limits to protect upstream availability and ensure fair access across participants.

• If you anticipate high concurrency (e.g., nightly reconciliations), contact Parley to coordinate an appropriate plan during onboarding.

Errors and behaviors

Recommended client behaviors:

• Backoff on 429; retry after the window resets.

• Use idempotent semantics for webhook processing; de‑dupe by event identity or (receipt_number + last_status_at).

Postman collection

• A ready‑to‑use Postman collection is available to beta users. Request access via Parley’s Contact page; include “Torch API (Case Status) – Postman” in your note. Contact Parley.

Security, privacy, and compliance

• Parley is built for professional immigration workflows and handles sensitive client data with industry‑standard controls. Public documentation notes SOC 2 Type 2 and GDPR posture; see the platform site and policies. Platform overview, Privacy Policy, Terms.

• Your integration must comply with applicable laws and your firm’s data handling policies. Do not transmit end‑client PII you do not need for status checks.

Roadmap and related capabilities

• Dashboard + API parity: Web‑based receipt tracking (already live in Parley) and webhook self‑service will converge with API features post‑beta. July changelog.

• Broader immigration automation: The same infrastructure powers Parley’s AI drafting, form‑filling, and RFE workflows for H‑1B, TN, L‑1, EB‑1/EB‑2 NIW, O‑1, and more. See the platform pages and Business Insider coverage for context. Platform overview, Business Insider coverage of Parley, How lawyers use AI (mentions Parley), June changelog.

Support

• Beta operations: If you experience delivery delays or suspect upstream changes, contact your Parley representative.

• General inquiries and beta access: use the Contact page. Contact Parley.