Skip to main content
Initialize a new provider connection between Filed and your platform. This establishes the connection using your partner key and firm-specific credentials.
Implementation Details: The specific implementation of what happens on Filed’s side when this mutation is called will be discussed and coordinated between your team and Filed’s engineering team during the integration process.
mutation StartProviderConnection($workspaceId: ID!, $providerKey: String!, $inputs: JSON) {
  startProviderConnection(workspaceId: $workspaceId, providerKey: $providerKey, inputs: $inputs) {
    id
    workspaceId
    providerKey
    status
    action
    displayName
    createdAt
  }
}

​
Arguments

​
workspaceId
ID!
required
The ID of the workspace (tax firm) you’re setting up the integration for.
​
providerKey
String!
required
Your partner key provided by Filed. Examples: <partner_key>, qount. Your specific partner key will be provided during partner onboarding.
​
inputs
JSON
Optional JSON object containing firm-specific credentials and configuration. Common fields include:
  • apiKey: Firm’s API key for your platform
  • securityToken: Security token or authentication token
  • baseUrl: Base URL for API calls (if different from default)
  • Any other credentials or configuration your platform requires

​
Returns

​
id
ID!
Connection identifier. Save this for the collect step.
​
workspaceId
ID!
Workspace identifier this connection belongs to.
​
providerKey
String!
The partner key used to create this connection.
​
status
String!
Connection status. Will be pending until you complete the collect step.
​
action
String
Next action required. Typically collect after starting a connection.
​
displayName
String
Display name for the connection.
​
createdAt
Date!
Timestamp when the connection was created.

​
Example

curl -X POST https://gateway.filed.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <accessToken>" \
  -H "source-platform: my-sample-platform" \
  -d '{
    "query": "mutation StartProviderConnection($workspaceId: ID!, $providerKey: String!, $inputs: JSON) { startProviderConnection(workspaceId: $workspaceId, providerKey: $providerKey, inputs: $inputs) { id workspaceId providerKey status action displayName createdAt } }",
    "variables": {
      "workspaceId": "workspace_123456",
      "providerKey": "<partner_key>",
      "inputs": {
        "apiKey": "firm-specific-api-key-12345",
        "securityToken": "firm-security-token-abc",
        "baseUrl": "https://api.canopy.com"
      }
    }
  }'

{
  "data": {
    "startProviderConnection": {
      "id": "connection_789",
      "workspaceId": "workspace_123456",
      "providerKey": "<partner_key>",
      "status": "pending",
      "action": "collect",
      "displayName": null,
      "createdAt": "2024-01-15T10:30:00Z"
    }
  }
}
Save the id from the response - you’ll need it for the collect provider connection step. The connection status will be pending until you complete the collect step.

​
Troubleshooting

Problem: startProviderConnection fails with invalid partner key Solutions:
  • Verify your partner key is correct (contact Filed if unsure)
  • Ensure the partner key matches what was provided during partner onboarding
  • Check that the partner key is spelled correctly (case-sensitive)
Problem: Connection created but credentials are invalid Solutions:
  • Verify the credentials in the inputs parameter are correct
  • Ensure API keys and tokens have the necessary permissions
  • Check that the credentials are for the correct tax firm/workspace