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

# Test CRM Connection

> Test the connection to a CRM provider using provided credentials

This endpoint tests the connection to a CRM provider (Close or Bullhorn) using the provided API key. Use this to validate credentials before saving CRM settings or to verify that existing credentials are still working.

## Authentication

<Note>
  This endpoint requires authentication. The request must include a valid
  session with an associated organization.
</Note>

## Request

### Body Parameters

<ParamField body="provider" type="string" required>
  The CRM provider to connect to. **Allowed values:** `close`, `bullhorn`
</ParamField>

<ParamField body="apiKey" type="string" required>
  The API key for authenticating with the CRM provider. Must be at least 1
  character. - For **Close**: Use your Close API key from Settings > API Keys -
  For **Bullhorn**: Use your Bullhorn REST API credentials
</ParamField>

## Response

<ResponseField name="success" type="boolean" required>
  Indicates whether the connection test was successful. - `true`: The API key is
  valid and connection was established - `false`: The connection failed (see
  `error` field for details)
</ResponseField>

<ResponseField name="error" type="string">
  Error message describing why the connection test failed. Only present when
  `success` is `false`. Common errors include: - Invalid API key - Network
  connectivity issues - CRM service unavailable
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://app.lance.so/api/v1/operations/crm/test-connection" \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "provider": "close",
      "apiKey": "api_xxxxxxxxxxxxxxxxxxxxxxxx"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("/api/v1/operations/crm/test-connection", {
    method: "POST",
    headers: {
      Authorization: "Bearer <token>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      provider: "close",
      apiKey: "api_xxxxxxxxxxxxxxxxxxxxxxxx",
    }),
  });

  const data = await response.json();
  ```

  ```typescript TypeScript theme={null}
  interface TestConnectionRequest {
    provider: "close" | "bullhorn";
    apiKey: string;
  }

  interface TestConnectionResponse {
    success: boolean;
    error?: string;
  }

  const request: TestConnectionRequest = {
    provider: "close",
    apiKey: "api_xxxxxxxxxxxxxxxxxxxxxxxx",
  };

  const response = await fetch("/api/v1/operations/crm/test-connection", {
    method: "POST",
    headers: {
      Authorization: "Bearer <token>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify(request),
  });

  const data: TestConnectionResponse = await response.json();
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "success": true
  }
  ```

  ```json Failed Connection theme={null}
  {
    "success": false,
    "error": "Invalid API key"
  }
  ```

  ```json Error Response (Missing Provider) theme={null}
  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Invalid enum value. Expected 'close' | 'bullhorn', received 'invalid'"
    }
  }
  ```

  ```json Error Response (Missing API Key) theme={null}
  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "API key is required"
    }
  }
  ```

  ```json Error Response (Unauthorized) theme={null}
  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Organization ID required"
    }
  }
  ```
</ResponseExample>

## Error Codes

| Status Code | Error Code         | Description                                                      |
| ----------- | ------------------ | ---------------------------------------------------------------- |
| `400`       | `VALIDATION_ERROR` | Missing or invalid request parameters (provider or apiKey)       |
| `401`       | `VALIDATION_ERROR` | User is not authenticated or not associated with an organization |
| `500`       | `INTERNAL_ERROR`   | Server error during connection test                              |

## Supported CRM Providers

### Close CRM

* **Provider value:** `close`
* **API Key format:** Starts with `api_` followed by alphanumeric characters
* **Documentation:** [Close API Documentation](https://developer.close.com/)

### Bullhorn CRM

* **Provider value:** `bullhorn`
* **API Key format:** REST API credentials from Bullhorn
* **Documentation:** [Bullhorn REST API](https://bullhorn.github.io/rest-api-docs/)

## Notes

* This endpoint only tests the connection; it does not save credentials
* To save CRM settings after a successful test, use the CRM settings endpoint
* The connection test verifies API key validity by making a lightweight request to the CRM provider
* Rate limiting may apply based on your CRM provider's API limits