Skip to main content

Start an asynchronous directory export job

POST 
/directory/:entityType/exports

Enqueues an asynchronous export of provider directory data for the specified entity type and returns a job ID to track progress.

When to use: Call this endpoint to initiate a bulk export of practitioners, facilities, or groups for a tenant. Use the returned exportJobId with GET /directory/{entityType}/exports/{exportJobId} to poll for completion and retrieve the download URL. Do not re-call this endpoint to check status.

Preconditions: The tenant must have existing practitioner or facility data; if none is found a 404 is returned. The caller must hold the READ_DIRECTORY permission.

Deduplication: Export requests for the same tenant, entity type, and filter parameters are deduplicated within a configurable window — 60 seconds by default. A duplicate request within the window returns the existing exportJobId instead of starting a new job.

Request body fields:

  • responseFormat — output file type: ndjson (default) or csv.
  • templateId — optional egress template ID. When provided, the export uses the template's column mappings instead of the legacy pipeline; the template must belong to the tenant and have status=active, or the request fails with 400. If responseFormat is also supplied, it must match the template's configured output format or the request fails with 400.
  • filters — optional NPI and/or TIN scoping; each list is capped at 100 entries by default and matched with OR logic when both are supplied. TIN-only filters are rejected for practitioners exports (400) since TIN is not a first-class practitioner identifier.
  • from / to — UTC calendar dates (yyyy-MM-dd, inclusive) bounding the window of a Manual Change File template; both are required for such a template and rejected (400) for Scheduled Change File templates and full roster exports. to must not precede from.

Returns: A JSON object containing exportJobId, tenantId, startedAt, and entityType. Supply exportJobId to the GET status endpoint to poll for completion. This operation has no other side effects — no files are written until the export job itself completes.

Request​

Responses​

The directory export job was accepted and enqueued.