curl -X GET "https://app.lance.so/api/v1/operations/crm/settings" \
-H "Authorization: Bearer <token>"
const response = await fetch("/api/v1/operations/crm/settings", {
method: "GET",
headers: {
Authorization: "Bearer <token>",
},
});
const data = await response.json();
interface CrmSettingsResponse {
connected: boolean;
provider: "close" | "bullhorn" | null;
connectedAt?: string;
apiKeyMasked?: string | null;
}
const response = await fetch("/api/v1/operations/crm/settings", {
method: "GET",
headers: {
Authorization: "Bearer <token>",
},
});
const data: CrmSettingsResponse = await response.json();
{
"connected": true,
"provider": "bullhorn",
"connectedAt": "2024-01-15T10:30:00.000Z",
"apiKeyMasked": "********************abc1"
}
{
"connected": false,
"provider": null
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Organization ID required"
}
}
CRM Integration
CRM Settings
Manage CRM integration settings for your organization
GET
/
api
/
v1
/
operations
/
crm
/
settings
curl -X GET "https://app.lance.so/api/v1/operations/crm/settings" \
-H "Authorization: Bearer <token>"
const response = await fetch("/api/v1/operations/crm/settings", {
method: "GET",
headers: {
Authorization: "Bearer <token>",
},
});
const data = await response.json();
interface CrmSettingsResponse {
connected: boolean;
provider: "close" | "bullhorn" | null;
connectedAt?: string;
apiKeyMasked?: string | null;
}
const response = await fetch("/api/v1/operations/crm/settings", {
method: "GET",
headers: {
Authorization: "Bearer <token>",
},
});
const data: CrmSettingsResponse = await response.json();
{
"connected": true,
"provider": "bullhorn",
"connectedAt": "2024-01-15T10:30:00.000Z",
"apiKeyMasked": "********************abc1"
}
{
"connected": false,
"provider": null
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Organization ID required"
}
}
This endpoint allows you to manage CRM integration settings for your organization. You can retrieve current settings, connect a new CRM provider, or disconnect an existing CRM integration.
Authentication
All endpoints require authentication. TheorgId must be present in the authenticated session.
Requests without valid authentication will receive a
400 Bad Request
response with the message “Organization ID required”.Get CRM Settings
Retrieve the current CRM settings for your organization. Returns connection status, provider type, and a masked API key for security.Response
boolean
required
Indicates whether a CRM is currently connected and enabled for the
organization.
string | null
required
The CRM provider currently configured. Returns
null if no CRM is connected.Allowed values:close- Close CRMbullhorn- Bullhorn CRMnull- No CRM connected
string
ISO-8601 timestamp of when the CRM was connected. Only present if a CRM is
connected. Example:
2024-01-15T10:30:00.000Zstring | null
A masked version of the API key showing only the last 4 characters for
verification purposes. Returns
null if no API key is configured.
Example: ********************abc1curl -X GET "https://app.lance.so/api/v1/operations/crm/settings" \
-H "Authorization: Bearer <token>"
const response = await fetch("/api/v1/operations/crm/settings", {
method: "GET",
headers: {
Authorization: "Bearer <token>",
},
});
const data = await response.json();
interface CrmSettingsResponse {
connected: boolean;
provider: "close" | "bullhorn" | null;
connectedAt?: string;
apiKeyMasked?: string | null;
}
const response = await fetch("/api/v1/operations/crm/settings", {
method: "GET",
headers: {
Authorization: "Bearer <token>",
},
});
const data: CrmSettingsResponse = await response.json();
{
"connected": true,
"provider": "bullhorn",
"connectedAt": "2024-01-15T10:30:00.000Z",
"apiKeyMasked": "********************abc1"
}
{
"connected": false,
"provider": null
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Organization ID required"
}
}
Save CRM Settings
Connect a CRM provider to your organization by saving the provider type and API credentials.Request
string
required
The CRM provider to connect. Allowed values: -
close - Close CRM -
bullhorn - Bullhorn CRMstring
required
The API key or authentication token for the CRM provider. Must be a non-empty string.
Store API keys securely. They are stored in Clerk organization metadata and only the masked version is returned in GET responses.
Response
boolean
required
Indicates the settings were saved successfully. Always
true for successful
responses.string
required
The CRM provider that was configured. Allowed values:
close, bullhornstring
required
ISO-8601 timestamp of when the CRM was connected. Example:
2024-01-15T10:30:00.000Zcurl -X POST "https://app.lance.so/api/v1/operations/crm/settings" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <token>" \
-d '{
"provider": "bullhorn",
"apiKey": "your-api-key-here"
}'
const response = await fetch("/api/v1/operations/crm/settings", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: "Bearer <token>",
},
body: JSON.stringify({
provider: "bullhorn",
apiKey: "your-api-key-here",
}),
});
const data = await response.json();
interface SaveCrmSettingsRequest {
provider: "close" | "bullhorn";
apiKey: string;
}
interface SaveCrmSettingsResponse {
success: boolean;
provider: "close" | "bullhorn";
connectedAt: string;
}
const response = await fetch("/api/v1/operations/crm/settings", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: "Bearer <token>",
},
body: JSON.stringify({
provider: "bullhorn",
apiKey: "your-api-key-here",
} satisfies SaveCrmSettingsRequest),
});
const data: SaveCrmSettingsResponse = await response.json();
{
"success": true,
"provider": "bullhorn",
"connectedAt": "2024-01-15T10:30:00.000Z"
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "API key is required"
}
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid enum value. Expected 'close' | 'bullhorn', received 'salesforce'"
}
}
Disconnect CRM
Disconnect the CRM integration from your organization. This removes all CRM settings including the stored API key.Response
boolean
required
Indicates the CRM was successfully disconnected. Always
true for successful
responses.boolean
required
Confirms the CRM has been disconnected. Always
true for successful
responses.curl -X DELETE "https://app.lance.so/api/v1/operations/crm/settings" \
-H "Authorization: Bearer <token>"
const response = await fetch("/api/v1/operations/crm/settings", {
method: "DELETE",
headers: {
Authorization: "Bearer <token>",
},
});
const data = await response.json();
interface DisconnectCrmResponse {
success: boolean;
disconnected: boolean;
}
const response = await fetch("/api/v1/operations/crm/settings", {
method: "DELETE",
headers: {
Authorization: "Bearer <token>",
},
});
const data: DisconnectCrmResponse = await response.json();
{
"success": true,
"disconnected": true
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Organization ID required"
}
}
Error Codes
| Status Code | Error Code | Description |
|---|---|---|
400 | VALIDATION_ERROR | Invalid request body, missing required fields, or missing authentication |
500 | INTERNAL_ERROR | Server error while processing the request |
Supported CRM Providers
| Provider | Value | Description |
|---|---|---|
| Close | close | Close CRM - Sales communication platform |
| Bullhorn | bullhorn | Bullhorn CRM - Staffing and recruiting software |
Notes
- CRM settings are stored in Clerk organization private metadata
- API keys are never returned in full - only masked versions are available via the GET endpoint
- Disconnecting a CRM removes all settings; you’ll need to reconfigure if reconnecting
- Each organization can only have one CRM provider connected at a time