E-File Magic

API getting started

Make your first API request

Connect your server application and read your filers in four steps.

  1. Your serverYour application
  2. OAuth tokenClient credentials
  3. Filing APIRead your filers

You’ll need

An E-File Magic account

An approved application

An account administrator

Server-to-server · Client credentials
This walkthrough uses a service credential. Your account’s API access must be enabled, and the application must allow this grant.

Connect your application

Give your application permission to read filers, then create its service credential.

  1. Open Settings → API Access in E-File Magic.
  2. Connect the approved application. Allow filers.read and choose which filers it may access.
  3. Under Service credentials, select Create credential. Save the client ID and secret returned for that credential.

Discover the endpoints

Start with the configured OAuth issuer for your environment. Load the authorization-server metadata and the Filing API’s protected-resource metadata.

Keep the issuer, resource and token endpoint exactly as supplied; do not substitute an origin from a different environment.

Get an access token

This example uses HTTP Basic client authentication (client_secret_basic). Send your service credential’s client ID and secret to the token endpoint.

Save access_token and use expires_in to track expiry. Client credentials do not return a refresh token; request a new access token when needed.

If your application, connection or credential requires DPoP, include the required proof. The bearer example below applies to tokens that are not DPoP-bound.

Request a token
curl --request POST '<token_endpoint from metadata>' \
  --user '<client_id>:<client_secret>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'resource=<Filing API resource from metadata>' \
  --data-urlencode 'scope=filers.read'

Static example with placeholders. Use your registered authentication method and the exact discovered endpoint.

Read your filers

Send the access token in the Authorization header. The connection can read only its authorized filers.

  • data.items contains this page of filers.
  • Pass data.next_cursor as the next request’s cursor, keeping the same filters. Continue until it is null; an empty page with a cursor is not the end.
  • Keep meta.request_id when asking for support.
List filers
curl --request GET 'https://api.efilemagic.com/api/v1/filers/list?limit=25' \
  --header 'Authorization: Bearer <access_token>'

The production API origin is shown. Use the API resource origin for your environment.

Acting on a user’s behalf?Use authorization code with S256 PKCE for delegated access.
  1. Create a random state and a 43–128 character verifier. Send the S256 challenge in a pushed authorization request (PAR).
  2. Direct the user’s browser to authorize with the returned request_uri and your client_id.
  3. After consent, validate the callback’s issuer and state. Exchange the one-time code with the same redirect URI and verifier.
  4. Store rotating refresh tokens atomically. Reusing an old refresh token revokes its token family.

Confidential clients use their registered authentication method. If DPoP is required, generate proofs with the same bound key.

Building an MCP client?MCP uses a separate resource and public-client authorization.

Discover the MCP resource and current registration settings. Public MCP clients use authorization code with S256 PKCE and client_id, without a client secret. They may use the supported direct authorization flow or PAR; client credentials are not supported.

MCP tokens and Filing API tokens are not interchangeable. MCP tools prepare filing work; the user reviews services and submits payment in E-File Magic through a checkout email invitation. The tools cannot pay for or submit an order.

Handle retries and keep credentials privateUse idempotency keys for protected mutations and retain request IDs for support.
  • For operations requiring Idempotency-Key, use a new key for each logical action. Keep the same key and body when recovering an uncertain result.
  • For 429, follow Retry-After. For 409 or 412, read the current state or obtain a fresh order preview before deciding how to proceed.
  • Download URLs are short-lived credentials. Keep them and Tax IDs out of logs. Retain request_id for support instead.

Continue building

Read the exact form and tax-year catalog, then create or import your filers and recipients. Preview services and prices before submitting an order with the required approval, funding and terms. Track the order to retrieve available deliverables.