Skip to main content
Are you a partner? If you are an official Filed partner managing multiple tax firm customers, please use the Partner integration guide instead.
This guide walks you through the complete API integration process for customers, from generating your API key to making your first authenticated request. Follow these steps to start building with Filed’s API.

​
Prerequisites

Before you begin, ensure you have:
  • An active Filed account
  • Access to Developer Settings in your workspace
  • GraphQL endpoint: https://gateway.filed.com/graphql
If you need assistance accessing Developer Settings or have questions about API access, please contact [email protected]

​
Overview

The API integration process consists of three simple steps:
  1. Generate API Key from Developer Settings
  2. Exchange API Key for an access token
  3. Make authenticated requests to the Filed API

​
Step 1: Generate API Key

Navigate to Developer Settings in your Filed workspace to generate your API key.
1

Access Developer Settings

Log in to your Filed account and navigate to Settings → Developer Settings
2

Generate New API Key

Click Generate API Key and provide a descriptive name for your key (e.g., “Production Integration”, “Development Testing”)
3

Save Your API Key

Copy and securely store your API key immediately - you won’t be able to see it again
Security Best Practice: Store your API key securely and never commit it to version control. Use environment variables or secure secret management tools.

​
Step 2: Exchange API Key for Access Token

Use your API key to obtain an access token that will authenticate all your API requests.

​
GraphQL Mutation

mutation LoginViaPersonalApiToken($apiKey: String!) {
  loginViaPersonalApiToken(token: $apiKey) {
    accessToken
  }
}

​
Implementation Notes

  • Store the accessToken securely and use it in the Authorization header for all subsequent requests
  • Access tokens are valid for a limited time; implement token refresh logic as needed
  • Format: Authorization: Bearer <accessToken>
  • Include a source-platform header with a custom identifier for your integration (e.g., tax-firm-a, my-sample-platform, qount). This header is used to uniquely identify API requests for analytical purposes and does not affect rate limits or any other API functionality.

​
Step 3: Verify Your Connection

Make a test request to verify your API key works correctly. The me query returns information about the authenticated user.

​
GraphQL Query

query Me {
  me {
    id
    name
  }
}

​
Implementation Notes

  • The me query returns information about the currently authenticated user
  • A successful response confirms your API integration is working correctly
  • The id field uniquely identifies the authenticated user
Success! If you receive a valid response with your user information, your API integration is working correctly and you’re ready to start building.

​
Complete Integration Example

Here’s a complete example showing all three steps together: 
const GRAPHQL_ENDPOINT = 'https://gateway.filed.com/graphql';
const API_KEY = process.env.FILED_API_KEY;

async function integrateWithFiled() {
  // Step 2: Exchange API Key for Access Token
  const authResponse = await fetch(GRAPHQL_ENDPOINT, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'source-platform': 'tax-firm-a'
    },
    body: JSON.stringify({
      query: `
        mutation LoginViaPersonalApiToken($apiKey: String!) {
          loginViaPersonalApiToken(token: $apiKey) {
            accessToken
          }
        }
      `,
      variables: { apiKey: API_KEY }
    })
  });

  const { data: authData } = await authResponse.json();
  const accessToken = authData.loginViaPersonalApiToken.accessToken;
  
  console.log('✓ Successfully authenticated');

  // Step 3: Verify Connection
  const meResponse = await fetch(GRAPHQL_ENDPOINT, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`,
      'source-platform': 'tax-firm-a'
    },
    body: JSON.stringify({
      query: `
        query Me {
          me {
            id
            name
          }
        }
      `
    })
  });

  const { data: meData } = await meResponse.json();
  console.log('✓ Connection verified');
  console.log('Current user:', meData.me);
  
  return { accessToken, user: meData.me };
}

// Run the integration
integrateWithFiled()
  .then(({ user }) => {
    console.log(`\n🎉 Integration successful! User ID: ${user.id}`);
  })
  .catch(error => {
    console.error('Integration failed:', error);
  });

​
Best Practices

​
Security

  1. Never expose API keys: Store API keys in environment variables or secure secret management systems
  2. Use HTTPS: Always make API requests over HTTPS
  3. Validate inputs: Always validate user inputs before making API calls

​
Error handling

  1. Handle authentication errors: Implement retry logic for expired tokens
  2. Validate responses: Check for errors in GraphQL responses
  3. Log errors: Maintain error logs for debugging and monitoring

​
Next Steps

Now that you’ve successfully integrated with Filed’s API, you can:
  1. Explore the API: Browse the full API reference to discover available queries and mutations
  2. Build features: Start implementing features using Filed’s GraphQL API
  3. Monitor usage: Track your API usage and monitor for errors

​
Support

Need help with your integration? We’re here to help you succeed with Filed’s API!