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

# Collect provider connection

> Verify a provider connection and provide additional configuration

Verify the provider connection by allowing Filed to test the credentials you provided. Filed will make an API call to your platform using the credentials from the start step. You can also provide additional configuration parameters during this step.

<Info>
  **Implementation Details**: The specific implementation of what happens on Filed's side when this mutation is called, including how Filed verifies the connection and makes API calls to your platform, will be discussed and coordinated between your team and Filed's engineering team during the integration process.
</Info>

```graphql theme={null}
mutation CollectProviderConnection($connectionId: ID!, $inputs: JSON) {
  collectProviderConnection(connectionId: $connectionId, inputs: $inputs) {
    id
    workspaceId
    providerKey
    status
    displayName
    settings
    updatedAt
  }
}
```

## Arguments

<ParamField path="connectionId" type="ID!" required>
  The connection ID returned from the [start provider connection](/legacy/apis/endpoint/start-provider-connection) mutation.
</ParamField>

<ParamField path="inputs" type="JSON">
  Optional JSON object containing additional configuration. Common fields include:

  * `firmReferenceId`: Your internal reference ID for the tax firm (useful for correlation)
  * Any other parameters you want Filed to store for this tax firm
  * Configuration that helps Filed communicate with your platform
</ParamField>

## Returns

<ResponseField name="id" type="ID!">
  Connection identifier.
</ResponseField>

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

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

<ResponseField name="status" type="String!">
  Connection status. Will be `active` if the verification succeeds, or an error state if it fails.
</ResponseField>

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

<ResponseField name="updatedAt" type="Date!">
  Timestamp when the connection was last updated.
</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 CollectProviderConnection($connectionId: ID!, $inputs: JSON) { collectProviderConnection(connectionId: $connectionId, inputs: $inputs) { id workspaceId providerKey status displayName settings updatedAt } }",
      "variables": {
        "connectionId": "connection_789",
        "inputs": {
          "firmReferenceId": "firm-ref-12345",
          "additionalConfig": {
            "timezone": "America/New_York",
            "region": "US"
          }
        }
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "data": {
      "collectProviderConnection": {
        "id": "connection_789",
        "workspaceId": "workspace_123456",
        "providerKey": "<partner_key>",
        "status": "active",
        "displayName": "Canopy Integration",
        "settings": {
          "firmReferenceId": "firm-ref-12345",
          "additionalConfig": {
            "timezone": "America/New_York",
            "region": "US"
          }
        },
        "updatedAt": "2024-01-15T10:35:00Z"
      }
    }
  }
  ```
</ResponseExample>

<Note>
  Filed will use the credentials from the [start provider connection](/legacy/apis/endpoint/start-provider-connection) step to make an API call to your platform. If the API call succeeds, Filed marks the connection as `active`. If it fails, the connection status will reflect the error state.
</Note>

## Troubleshooting

**Problem**: Connection status remains `pending` or shows an error after collect

**Solutions**:

* Verify the credentials provided in the start step are valid and have the necessary permissions
* Ensure your platform's API is accessible and responding correctly
* Check that the API endpoint URLs are correct
* Verify the API keys and tokens haven't expired
* Review Filed's API call logs (contact support if needed)

**Problem**: `connectionId` not found

**Solutions**:

* Ensure you're using the `connectionId` from the start provider connection response
* Check that you're using the correct workspace's connection ID