API getting started
Make your first API request
Connect your server application and read your filers in four steps.
- Your serverYour application
- OAuth tokenClient credentials
- 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.
- Open Settings → API Access in E-File Magic.
- Connect the approved application. Allow
filers.readand choose which filers it may access. - 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.
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.itemscontains this page of filers.- Pass
data.next_cursoras the next request’scursor, keeping the same filters. Continue until it is null; an empty page with a cursor is not the end. - Keep
meta.request_idwhen asking for support.
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.
- Create a random state and a 43–128 character verifier. Send the S256 challenge in a pushed authorization request (PAR).
- Direct the user’s browser to authorize with the returned
request_uriand yourclient_id. - After consent, validate the callback’s issuer and state. Exchange the one-time code with the same redirect URI and verifier.
- 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, followRetry-After. For409or412, 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_idfor 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.