> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apps.filed.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Start provider connection

> Initialize a provider connection for a workspace with partner credentials

Initialize a new provider connection between Filed and your platform. This establishes the connection using your partner key and firm-specific credentials.

<Info>
  **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.
</Info>

```graphql theme={null}
mutation StartProviderConnection($workspaceId: ID!, $providerKey: String!, $inputs: JSON) {
  startProviderConnection(workspaceId: $workspaceId, providerKey: $providerKey, inputs: $inputs) {
    id
    workspaceId
    providerKey
    status
    action
    displayName
    createdAt
  }
}
```

## Arguments

<ParamField path="workspaceId" type="ID!" required>
  The ID of the workspace (tax firm) you're setting up the integration for.
</ParamField>

<ParamField path="providerKey" type="String!" required>
  Your partner key provided by Filed. Examples: `<partner_key>`, `qount`. Your specific partner key will be provided during partner onboarding.
</ParamField>

<ParamField path="inputs" type="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
</ParamField>

## Returns

<ResponseField name="id" type="ID!">
  Connection identifier. Save this for the collect step.
</ResponseField>

<ResponseField name="workspaceId" type="ID!">
  Workspace identifier this connection belongs to.
</ResponseField>

<ResponseField name="providerKey" type="String!">
  The partner key used to create this connection.
</ResponseField>

<ResponseField name="status" type="String!">
  Connection status. Will be `pending` until you complete the collect step.
</ResponseField>

<ResponseField name="action" type="String">
  Next action required. Typically `collect` after starting a connection.
</ResponseField>

<ResponseField name="displayName" type="String">
  Display name for the connection.
</ResponseField>

<ResponseField name="createdAt" type="Date!">
  Timestamp when the connection was created.
</ResponseField>

## Example

<RequestExample>
  ```bash cURL theme={null}
  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"
        }
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "data": {
      "startProviderConnection": {
        "id": "connection_789",
        "workspaceId": "workspace_123456",
        "providerKey": "<partner_key>",
        "status": "pending",
        "action": "collect",
        "displayName": null,
        "createdAt": "2024-01-15T10:30:00Z"
      }
    }
  }
  ```
</ResponseExample>

<Note>
  Save the `id` from the response - you'll need it for the [collect provider connection](/legacy/apis/endpoint/collect-provider-connection) step. The connection status will be `pending` until you complete the collect step.
</Note>

## 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