Lance

https://docs.lance.so
Admin
Lance is a sales prospecting platform that helps you find, enrich, and manage leads for your sales...
Tokens:136,737
Snippets:704
Trust Score:5.1
Update:3 months ago
Show doc for...
Tokens:
Raw
### Get Credits Balance using TypeScript

Source: https://docs.lance.so/api-reference/operations/credits-balance

This TypeScript example shows how to fetch the credit balance and defines an interface for the response data. Remember to replace `<token>` with your authentication token.

```typescript
interface CreditBalance {
    balance: number;
    organizationId: string;
  }

  const response = await fetch("/api/v1/operations/credits/balance", {
    method: "GET",
    headers: {
      Authorization: "Bearer <token>",
    },
  });

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

--------------------------------

### Create Lead List Response Examples

Source: https://docs.lance.so/api-reference/entities/leadlists-create

Examples of successful and unsuccessful responses when creating a lead list.

```APIDOC
## POST /leadlists

### Description
Creates a new lead list with the provided details.

### Method
POST

### Endpoint
/leadlists

### Request Body
- **name** (string) - Required - The name of the lead list.
- **type** (string) - Required - The type of the lead list (e.g., 'person', 'company').
- **startDate** (string) - Optional - The start date for the lead list.
- **endDate** (string) - Optional - The end date for the lead list.
- **personIds** (array of strings) - Optional - IDs of people to include in the list.
- **companyIds** (array of strings) - Optional - IDs of companies to include in the list.
- **userIds** (array of strings) - Optional - IDs of users associated with the list.

### Request Example
```json
{
  "name": "Q1 2024 Tech Startups",
  "type": "person",
  "startDate": "2024-01-01T00:00:00.000Z",
  "endDate": "2024-03-31T23:59:59.000Z",
  "personIds": ["lead_abc123", "lead_def456"],
  "userIds": ["user_xyz789"]
}
```

### Response
#### Success Response (201)
- **id** (string) - The unique identifier for the created lead list.
- **icpId** (string) - The ICP ID associated with the lead list.
- **name** (string) - The name of the lead list.
- **type** (string) - The type of the lead list.
- **startDate** (string) - The start date of the lead list.
- **endDate** (string) - The end date of the lead list.
- **personIds** (array of strings) - IDs of people included in the list.
- **companyIds** (array of strings) - IDs of companies included in the list.
- **userIds** (array of strings) - IDs of users associated with the list.
- **createdAt** (string) - Timestamp when the lead list was created.
- **updatedAt** (string) - Timestamp when the lead list was last updated.

#### Response Example (201)
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "icpId": "660e8400-e29b-41d4-a716-446655440001",
  "name": "Q1 2024 Tech Startups",
  "type": "person",
  "startDate": "2024-01-01T00:00:00.000Z",
  "endDate": "2024-03-31T23:59:59.000Z",
  "personIds": ["lead_abc123", "lead_def456"],
  "companyIds": [],
  "userIds": ["user_xyz789"],
  "createdAt": "2024-01-02T10:30:00.000Z",
  "updatedAt": "2024-01-02T10:30:00.000Z"
}
```

#### Error Response (400)
- **error.code** (string) - The error code (e.g., `BAD_REQUEST`).
- **error.message** (string) - A description of the error.
- **error.details** (array) - Specific details about validation errors.

#### Response Example (400)
```json
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request body",
    "details": [
      {
        "path": ["name"],
        "message": "Required"
      }
    ]
  }
}
```

#### Error Response (401)
- **error.code** (string) - The error code (`UNAUTHORIZED`).
- **error.message** (string) - A description of the error.

#### Response Example (401)
```json
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Unauthorized"
  }
}
```
```

--------------------------------

### Get Credits Balance using JavaScript

Source: https://docs.lance.so/api-reference/operations/credits-balance

Fetch the current credit balance for your organization using JavaScript. This example demonstrates how to make the request and log the balance to the console. Replace `<token>` with your authentication token.

```javascript
const response = await fetch("/api/v1/operations/credits/balance", {
    method: "GET",
    headers: {
      Authorization: "Bearer <token>",
    },
  });

  const data = await response.json();
  console.log(`Balance: ${data.balance} credits`);
```

--------------------------------

### List Users - Success Response Example

Source: https://docs.lance.so/api-reference/entities/users-list

This example shows a successful response when retrieving a list of users. It includes user details like ID, name, email, and organization ID.

```json
[
  {
    "id": "user_abc123",
    "firstName": "John",
    "lastName": "Smith",
    "email": "john.smith@company.com",
    "profilePictureUrl": "https://img.clerk.com/user_abc123.jpg",
    "createdAt": "2024-01-10T08:00:00.000Z",
    "updatedAt": "2024-01-15T14:30:00.000Z",
    "clerkId": "user_abc123",
    "clerkOrgId": "org_xyz789"
  },
  {
    "id": "user_def456",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane.doe@company.com",
    "profilePictureUrl": null,
    "createdAt": "2024-01-12T10:15:00.000Z",
    "updatedAt": "2024-01-12T10:15:00.000Z",
    "clerkId": "user_def456",
    "clerkOrgId": "org_xyz789"
  }
]
```

--------------------------------

### Success Response Example

Source: https://docs.lance.so/api-reference/operations/payment-plans

An example of a successful response when retrieving payment plans. It includes details for starter, growth, and enterprise plans.

```json
[
    {
      "id": "prod_starter123",
      "productId": "prod_starter123",
      "label": "Starter",
      "price": "€ 29",
      "interval": "month",
      "amount": 500,
      "currency": "€",
      "description": "Perfect for individuals",
      "features": [
        "500 credits per month",
        "Email enrichment",
        "Basic support"
      ]
    },
    {
      "id": "prod_growth456",
      "productId": "prod_growth456",
      "label": "Growth",
      "price": "€ 79",
      "interval": "month",
      "amount": 2000,
      "currency": "€",
      "description": "For growing teams",
      "features": [
        "2000 credits per month",
        "Email & phone enrichment",
        "Priority support",
        "CRM integration"
      ]
    },
    {
      "id": "prod_enterprise789",
      "productId": "prod_enterprise789",
      "label": "Enterprise",
      "price": "€ 199",
      "interval": "month",
      "amount": 10000,
      "currency": "€",
      "description": "For large organizations",
      "features": [
        "10000 credits per month",
        "All enrichment features",
        "Dedicated support",
        "Custom integrations"
      ]
    }
  ]
```

--------------------------------

### Error Response Example (Server Error)

Source: https://docs.lance.so/api-reference/operations/payment-plans

An example of an error response indicating a server-side issue.

```json
{
    "error": {
      "code": "INTERNAL_ERROR",
      "message": "An unexpected error occurred"
    }
  }
```

--------------------------------

### Error: Missing Key Parameter

Source: https://docs.lance.so/api-reference/operations/autocomplete-classifications

Example response when the required 'key' parameter is missing.

```APIDOC
## GET /autocomplete/classifications

### Description
Error response when the mandatory 'key' query parameter is not provided.

### Method
GET

### Endpoint
/autocomplete/classifications

### Response
#### Error Response (400)
- **error** (object)
  - **code** (string) - "VALIDATION_ERROR".
  - **message** (string) - "Missing required parameter: key".

### Response Example
```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Missing required parameter: key"
  }
}
```
```

--------------------------------

### Skills Search

Source: https://docs.lance.so/api-reference/operations/autocomplete-classifications

Example response for a successful skills search query.

```APIDOC
## GET /autocomplete/classifications

### Description
Retrieves a list of classifications that match the provided query, used for autocomplete functionality.

### Method
GET

### Endpoint
/autocomplete/classifications

### Query Parameters
- **key** (string) - Required - The search term or classification to autocomplete.
- **type** (string) - Optional - The type of classification to search for (e.g., "SKILL", "INDUSTRY").

### Response
#### Success Response (200)
- **content** (array) - An array of classification objects matching the search query.
  - **id** (string) - Unique identifier for the classification.
  - **key** (string) - The type of classification (e.g., "SKILL").
  - **value** (string) - The name of the classification (e.g., "Python").
  - **index** (integer) - The order of the classification in the results.
  - **metadata** (object) - Additional metadata about the classification (e.g., category).
- **totalElements** (integer) - The total number of elements available.
- **totalPages** (integer) - The total number of pages.
- **size** (integer) - The number of elements per page.
- **number** (integer) - The current page number.
- **first** (boolean) - Indicates if this is the first page.
- **last** (boolean) - Indicates if this is the last page.
- **empty** (boolean) - Indicates if the response is empty.
- **numberOfElements** (integer) - The number of elements on the current page.

### Response Example
```json
{
  "content": [
    {
      "id": "skill_001",
      "key": "SKILL",
      "value": "Python",
      "index": 0,
      "metadata": {
        "category": "Programming Languages"
      }
    },
    {
      "id": "skill_002",
      "key": "SKILL",
      "value": "Python Django",
      "index": 1,
      "metadata": {
        "category": "Web Frameworks"
      }
    },
    {
      "id": "skill_003",
      "key": "SKILL",
      "value": "Python Flask",
      "index": 2,
      "metadata": {
        "category": "Web Frameworks"
      }
    }
  ],
  "totalElements": 45,
  "totalPages": 2,
  "size": 25,
  "number": 0,
  "first": true,
  "last": false,
  "empty": false,
  "numberOfElements": 25
}
```
```

--------------------------------

### Export Leads (Manual Selection)

Source: https://docs.lance.so/api-reference/operations/export

This example shows how to export a specific list of leads by their IDs. You can select which fields to include in the export.

```APIDOC
## POST /api/v1/operations/export

### Description
Exports a list of leads based on a manual selection of IDs. Allows specifying custom fields for the export.

### Method
POST

### Endpoint
/api/v1/operations/export

### Parameters
#### Request Body
- **selection** (object) - Required - Defines the selection criteria for leads.
  - **mode** (string) - Required - Must be "manual".
  - **includedIds** (array of strings) - Required - A list of lead IDs to include in the export.
- **exportFields** (array of strings) - Required - A list of field IDs to include in the CSV export. Available fields are listed in the documentation.

### Request Example
```bash
curl -X POST "https://app.lance.so/api/v1/operations/export" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -o "leads-export.csv" \
  -d '{
    "selection": {
      "mode": "manual",
      "includedIds": [
        "550e8400-e29b-41d4-a716-446655440000",
        "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
      ]
    },
    "exportFields": ["name", "emails", "phones", "jobTitle", "companyName"]
  }'
```

### Response
#### Success Response (200)
- **Content-Type**: `text/csv; charset=utf-8`
- **Content-Disposition**: `attachment; filename="lance-prospects-{YYYY - MM - DD}.csv"`
- **X-Export-Count**: The number of records exported (as a string).

The response body is a CSV file containing the exported lead data.
```

--------------------------------

### Get Ivy League schools (example with Harvard)

Source: https://docs.lance.so/api-reference/operations/autocomplete-schools

Demonstrates searching for a specific school like 'harvard'.

```APIDOC
## GET /api/v1/operations/autocomplete/schools

### Description
Searches for schools based on a provided search term. This endpoint is useful for type-ahead or autocomplete functionality.

### Method
GET

### Endpoint
/api/v1/operations/autocomplete/schools

### Query Parameters
- **search** (string) - Optional - The text to search for. Filters results that match the search text.
- **size** (integer) - Optional - The number of results to return per page. Defaults to 10.
- **page** (integer) - Optional - The page number for pagination. Defaults to 0.

### Request Example
```bash
curl -X GET "https://api.lance.work/api/v1/operations/autocomplete/schools?search=harvard" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Response
#### Success Response (200)
- **schools** (array) - A list of school objects matching the search criteria.
  - **name** (string) - The name of the school.
  - **id** (string) - The unique identifier for the school.
  - **logo** (string) - URL to the school's logo, if available.

#### Response Example
```json
{
  "schools": [
    {
      "name": "Harvard University",
      "id": "harvard-university",
      "logo": "https://example.com/harvard-logo.png"
    }
  ]
}
```
```

--------------------------------

### Create Person Lead List

Source: https://docs.lance.so/api-reference/entities/leadlists-create

Use this example to create a lead list of type 'person'. Ensure 'personIds' are provided and 'companyIds' are empty.

```json
{
    "name": "Q1 2024 Tech Startups",
    "type": "person",
    "icpId": "660e8400-e29b-41d4-a716-446655440001",
    "startDate": "2024-01-01T00:00:00.000Z",
    "endDate": "2024-03-31T23:59:59.000Z",
    "personIds": ["lead_abc123", "lead_def456"],
    "companyIds": []
  }
```

--------------------------------

### Get Enrichment Status with TypeScript

Source: https://docs.lance.so/api-reference/operations/enrichment-person

This TypeScript example shows how to retrieve enrichment status, defining the personId and field variables beforehand. Remember to include your API token in the headers.

```typescript
const personId = "550e8400-e29b-41d4-a716-446655440000";
  const field = "emails";

  const response = await fetch(
    `/api/v1/operations/enrichment/${personId}?field=${field}`,
    {
      method: "GET",
      headers: {
        Authorization: "Bearer <token>",
      },
    }
  );

  const enrichment: Enrichment = await response.json();
```

--------------------------------

### Create Company Lead List

Source: https://docs.lance.so/api-reference/entities/leadlists-create

Use this example to create a lead list of type 'company'. Ensure 'companyIds' are provided and 'personIds' are empty.

```json
{
    "name": "Enterprise Accounts Q2",
    "type": "company",
    "icpId": null,
    "startDate": "2024-04-01T00:00:00.000Z",
    "endDate": "2024-06-30T23:59:59.000Z",
    "personIds": [],
    "companyIds": ["770e8400-e29b-41d4-a716-446655440001"]
  }
```

--------------------------------

### Create Person Lead List

Source: https://docs.lance.so/api-reference/entities/leadlists-create

Example of creating a lead list for individuals. Requires `name`, `type` set to 'person', `icpId`, `startDate`, `endDate`, and `personIds`.

```APIDOC
## POST /leadlists

### Description
Creates a new lead list.

### Method
POST

### Endpoint
/leadlists

### Request Body
- **name** (string) - Required - The display name of the lead list.
- **type** (string) - Required - The type of leads in this list (`"person"` or `"company"`).
- **icpId** (string (UUID) | null) - Optional - The ID of the associated Ideal Customer Profile.
- **startDate** (string) - Required - ISO 8601 timestamp for the campaign start date.
- **endDate** (string) - Required - ISO 8601 timestamp for the campaign end date.
- **personIds** (array) - Optional - Array of person/lead IDs in the list.
- **companyIds** (array) - Optional - Array of company UUIDs in the list.

### Request Example
```json
{
  "name": "Q1 2024 Tech Startups",
  "type": "person",
  "icpId": "660e8400-e29b-41d4-a716-446655440001",
  "startDate": "2024-01-01T00:00:00.000Z",
  "endDate": "2024-03-31T23:59:59.000Z",
  "personIds": ["lead_abc123", "lead_def456"],
  "companyIds": []
}
```

### Response
#### Success Response (200)
- **id** (string (UUID)) - Unique identifier for the newly created lead list.
- **icpId** (string (UUID) | null) - The ID of the associated Ideal Customer Profile.
- **name** (string) - The display name of the lead list.
- **type** (string) - The type of leads in this list (`"person"` or `"company"`).
- **startDate** (string) - ISO 8601 timestamp for the campaign start date.
- **endDate** (string) - ISO 8601 timestamp for the campaign end date.
- **personIds** (array) - Array of person/lead IDs in the list.
- **companyIds** (array) - Array of company UUIDs in the list.
- **userIds** (array) - Array of user IDs with access (includes the creator).
- **createdAt** (string) - ISO 8601 timestamp of when the lead list was created.
- **updatedAt** (string) - ISO 8601 timestamp of when the lead list was last updated.

#### Response Example
```json
{
  "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "icpId": "660e8400-e29b-41d4-a716-446655440001",
  "name": "Q1 2024 Tech Startups",
  "type": "person",
  "startDate": "2024-01-01T00:00:00.000Z",
  "endDate": "2024-03-31T23:59:59.000Z",
  "personIds": ["lead_abc123", "lead_def456"],
  "companyIds": [],
  "userIds": ["user_xyz789"],
  "createdAt": "2024-01-15T10:00:00.000Z",
  "updatedAt": "2024-01-15T10:00:00.000Z"
}
```
```

--------------------------------

### Create Minimal Lead List

Source: https://docs.lance.so/api-reference/entities/leadlists-create

This is a minimal request example. Only 'name', 'startDate', and 'endDate' are required fields for creating a lead list.

```json
{
    "name": "New Campaign",
    "icpId": null,
    "startDate": "2024-01-01T00:00:00.000Z",
    "endDate": "2024-12-31T23:59:59.000Z"
  }
```

--------------------------------

### API Error Response Example

Source: https://docs.lance.so/api-reference/introduction

This is an example of a JSON response when an API request fails due to validation errors.

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid parameter: email"
  }
}
```

--------------------------------

### Get largest companies first

Source: https://docs.lance.so/api-reference/operations/autocomplete-companies

Sort companies by employee count in descending order to get the largest companies first.

```APIDOC
## GET /api/v1/operations/autocomplete/companies

### Description
Retrieves a list of companies sorted by employee count in descending order.

### Method
GET

### Endpoint
/api/v1/operations/autocomplete/companies

### Query Parameters
- **employeeCount** (string) - Required - Sort order for employee count. Use 'desc' for largest first.
- **size** (integer) - Optional - The number of results to return per page.

### Request Example
```bash
curl -X GET "https://api.lance.work/api/v1/operations/autocomplete/companies?employeeCount=desc&size=20" \
  -H "Authorization: Bearer YOUR_TOKEN"
```
```

--------------------------------

### Create Minimal Lead List

Source: https://docs.lance.so/api-reference/entities/leadlists-create

Example of creating a lead list with only the required fields: `name`, `icpId`, `startDate`, and `endDate`. The `type` will default based on context or be inferred if possible.

```APIDOC
## POST /leadlists

### Description
Creates a new lead list.

### Method
POST

### Endpoint
/leadlists

### Request Body
- **name** (string) - Required - The display name of the lead list.
- **type** (string) - Required - The type of leads in this list (`"person"` or `"company"`).
- **icpId** (string (UUID) | null) - Optional - The ID of the associated Ideal Customer Profile.
- **startDate** (string) - Required - ISO 8601 timestamp for the campaign start date.
- **endDate** (string) - Required - ISO 8601 timestamp for the campaign end date.
- **personIds** (array) - Optional - Array of person/lead IDs in the list.
- **companyIds** (array) - Optional - Array of company UUIDs in the list.

### Request Example
```json
{
  "name": "New Campaign",
  "icpId": null,
  "startDate": "2024-01-01T00:00:00.000Z",
  "endDate": "2024-12-31T23:59:59.000Z"
}
```

### Response
#### Success Response (200)
- **id** (string (UUID)) - Unique identifier for the newly created lead list.
- **icpId** (string (UUID) | null) - The ID of the associated Ideal Customer Profile.
- **name** (string) - The display name of the lead list.
- **type** (string) - The type of leads in this list (`"person"` or `"company"`).
- **startDate** (string) - ISO 8601 timestamp for the campaign start date.
- **endDate** (string) - ISO 8601 timestamp for the campaign end date.
- **personIds** (array) - Array of person/lead IDs in the list.
- **companyIds** (array) - Array of company UUIDs in the list.
- **userIds** (array) - Array of user IDs with access (includes the creator).
- **createdAt** (string) - ISO 8601 timestamp of when the lead list was created.
- **updatedAt** (string) - ISO 8601 timestamp of when the lead list was last updated.

#### Response Example
```json
{
  "id": "c3d4e5f6-a7b8-9012-3456-7890abcdef12",
  "icpId": null,
  "name": "New Campaign",
  "type": "person",
  "startDate": "2024-01-01T00:00:00.000Z",
  "endDate": "2024-12-31T23:59:59.000Z",
  "personIds": [],
  "companyIds": [],
  "userIds": ["user_xyz789"],
  "createdAt": "2024-01-20T12:00:00.000Z",
  "updatedAt": "2024-01-20T12:00:00.000Z"
}
```
```

--------------------------------

### Link to Customer Portal in React

Source: https://docs.lance.so/api-reference/operations/payment-customer-portal

This React example shows how to create a link that directs users to the Customer Portal. The `href` attribute points to the API endpoint, initiating the redirect when clicked.

```jsx
// Usage in a React component
function BillingButton() {
  return (
    <a href="/api/v1/operations/payment/customer-portal">Manage Billing</a>
  );
}
```

--------------------------------

### List Users - Validation Error Response Example

Source: https://docs.lance.so/api-reference/entities/users-list

This example demonstrates a validation error response, typically occurring when the user does not belong to an organization.

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "User Org Id missing"
  }
}
```

--------------------------------

### Create Company Lead List

Source: https://docs.lance.so/api-reference/entities/leadlists-create

Example of creating a lead list for companies. Requires `name`, `type` set to 'company', `icpId`, `startDate`, `endDate`, and `companyIds`.

```APIDOC
## POST /leadlists

### Description
Creates a new lead list.

### Method
POST

### Endpoint
/leadlists

### Request Body
- **name** (string) - Required - The display name of the lead list.
- **type** (string) - Required - The type of leads in this list (`"person"` or `"company"`).
- **icpId** (string (UUID) | null) - Optional - The ID of the associated Ideal Customer Profile.
- **startDate** (string) - Required - ISO 8601 timestamp for the campaign start date.
- **endDate** (string) - Required - ISO 8601 timestamp for the campaign end date.
- **personIds** (array) - Optional - Array of person/lead IDs in the list.
- **companyIds** (array) - Optional - Array of company UUIDs in the list.

### Request Example
```json
{
  "name": "Enterprise Accounts Q2",
  "type": "company",
  "icpId": null,
  "startDate": "2024-04-01T00:00:00.000Z",
  "endDate": "2024-06-30T23:59:59.000Z",
  "personIds": [],
  "companyIds": ["770e8400-e29b-41d4-a716-446655440001"]
}
```

### Response
#### Success Response (200)
- **id** (string (UUID)) - Unique identifier for the newly created lead list.
- **icpId** (string (UUID) | null) - The ID of the associated Ideal Customer Profile.
- **name** (string) - The display name of the lead list.
- **type** (string) - The type of leads in this list (`"person"` or `"company"`).
- **startDate** (string) - ISO 8601 timestamp for the campaign start date.
- **endDate** (string) - ISO 8601 timestamp for the campaign end date.
- **personIds** (array) - Array of person/lead IDs in the list.
- **companyIds** (array) - Array of company UUIDs in the list.
- **userIds** (array) - Array of user IDs with access (includes the creator).
- **createdAt** (string) - ISO 8601 timestamp of when the lead list was created.
- **updatedAt** (string) - ISO 8601 timestamp of when the lead list was last updated.

#### Response Example
```json
{
  "id": "b2c3d4e5-f6a7-8901-2345-67890abcdef1",
  "icpId": null,
  "name": "Enterprise Accounts Q2",
  "type": "company",
  "startDate": "2024-04-01T00:00:00.000Z",
  "endDate": "2024-06-30T23:59:59.000Z",
  "personIds": [],
  "companyIds": ["770e8400-e29b-41d4-a716-446655440001"],
  "userIds": ["user_xyz789"],
  "createdAt": "2024-04-10T11:00:00.000Z",
  "updatedAt": "2024-04-10T11:00:00.000Z"
}
```
```

--------------------------------

### Get Default Person Metadata

Source: https://docs.lance.so/api-reference/operations/autocomplete-person-metadata

Fetches the default set of person metadata statistics using a GET request. Ensure you replace 'YOUR_TOKEN' with your actual API token.

```bash
curl -X GET "https://api.lance.work/api/v1/operations/autocomplete/person-metadata" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

--------------------------------

### Get User

Source: https://docs.lance.so/llms.txt

Retrieves a user by their Clerk user ID.

```APIDOC
## Get User

### Description
Retrieves a user by their Clerk user ID.

### Method
GET

### Endpoint
/api/v1/entities/users/{clerkUserId}

### Parameters
#### Path Parameters
- **clerkUserId** (string) - Required - The Clerk user ID of the user to retrieve.

### Response
#### Success Response (200 OK)
- **id** (string) - The unique identifier of the user.
- **clerkUserId** (string) - The Clerk user ID.
- **email** (string) - The email address of the user.
- **organizationId** (string) - The ID of the organization the user belongs to.
```

--------------------------------

### Error: Server Error

Source: https://docs.lance.so/api-reference/operations/autocomplete-classifications

Example response for an unexpected server-side error.

```APIDOC
## GET /autocomplete/classifications

### Description
Error response indicating an internal server error occurred during request processing.

### Method
GET

### Endpoint
/autocomplete/classifications

### Response
#### Error Response (500)
- **error** (object)
  - **code** (string) - "INTERNAL_ERROR".
  - **message** (string) - "An unexpected error occurred".

### Response Example
```json
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred"
  }
}
```
```

--------------------------------

### Export Leads (Bulk Selection)

Source: https://docs.lance.so/api-reference/operations/export

This example demonstrates exporting leads based on bulk selection criteria, including filters and pagination. You can specify filters for contact location and other attributes.

```APIDOC
## POST /api/v1/operations/export

### Description
Exports leads based on bulk selection criteria, allowing for filters and pagination. Useful for exporting large sets of leads matching specific conditions.

### Method
POST

### Endpoint
/api/v1/operations/export

### Parameters
#### Request Body
- **selection** (object) - Required - Defines the selection criteria for leads.
  - **mode** (string) - Required - Must be "bulk".
  - **startIndex** (integer) - Optional - The starting index for pagination.
  - **targetCount** (integer) - Optional - The number of records to export.
  - **excludedIds** (array of strings) - Optional - A list of lead IDs to exclude from the export.
  - **filters** (object) - Optional - Criteria to filter the leads.
    - **contact** (object) - Optional - Filters related to contact information.
      - **location** (object) - Optional - Filters based on location.
        - **any** (object) - Optional - Matches any of the provided locations.
          - **include** (array of strings) - Required - List of locations to include (e.g., "San Francisco, CA").

### Request Example
```bash
curl -X POST "https://app.lance.so/api/v1/operations/export" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -o "leads-export.csv" \
  -d '{
    "selection": {
      "mode": "bulk",
      "startIndex": 0,
      "targetCount": 100,
      "excludedIds": ["excluded-id-1"],
      "filters": {
        "contact": {
          "location": {
            "any": {
              "include": ["San Francisco, CA"]
            }
          }
        }
      }
    }
  }'
```

### Response
#### Success Response (200)
- **Content-Type**: `text/csv; charset=utf-8`
- **Content-Disposition**: `attachment; filename="lance-prospects-{YYYY - MM - DD}.csv"`
- **X-Export-Count**: The number of records exported (as a string).

The response body is a CSV file containing the exported lead data.
```

--------------------------------

### Basic ICP Creation

Source: https://docs.lance.so/api-reference/entities/icps-create

Use this example to create a basic ICP with lead provider criteria and custom filters for location and company size.

```json
{
    "name": "DACH Tech Leaders",
    "description": "Technology leaders in German-speaking regions",
    "leadProviderCriteria": [
      {
        "provider": "baseProvider",
        "type": "person",
        "filters": {
          "job_title": ["CTO", "VP Engineering", "Head of Technology"],
          "location": {
            "country": ["Germany", "Austria", "Switzerland"]
          },
          "company": {
            "employee_size": {
              "min": 100,
              "max": 5000
            }
          }
        }
      }
    ],
    "customFilterCriteria": [
      {
        "type": "maxPeoplePerCompany",
        "value": 2
      }
    ],
    "crmFilters": null,
    "userIds": [],
    "leadsPerList": 20,
    "activeUntil": null
  }
```

--------------------------------

### Empty Results

Source: https://docs.lance.so/api-reference/operations/autocomplete-classifications

Example response when no classifications match the search query.

```APIDOC
## GET /autocomplete/classifications

### Description
Response indicating that no classifications were found matching the search criteria.

### Method
GET

### Endpoint
/autocomplete/classifications

### Response
#### Success Response (200)
- **content** (array) - An empty array.
- **totalElements** (integer) - 0.
- **totalPages** (integer) - 0.
- **size** (integer) - The requested page size.
- **number** (integer) - 0.
- **first** (boolean) - true.
- **last** (boolean) - true.
- **empty** (boolean) - true.
- **numberOfElements** (integer) - 0.

### Response Example
```json
{
  "content": [],
  "totalElements": 0,
  "totalPages": 0,
  "size": 25,
  "number": 0,
  "first": true,
  "last": true,
  "empty": true,
  "numberOfElements": 0
}
```
```

--------------------------------

### Industry Search

Source: https://docs.lance.so/api-reference/operations/autocomplete-classifications

Example response for a successful industry search query.

```APIDOC
## GET /autocomplete/classifications?type=INDUSTRY

### Description
Retrieves a list of industries that match the provided query, used for autocomplete functionality.

### Method
GET

### Endpoint
/autocomplete/classifications

### Query Parameters
- **key** (string) - Required - The search term or industry to autocomplete.
- **type** (string) - Required - Set to "INDUSTRY" to search for industries.

### Response
#### Success Response (200)
- **content** (array) - An array of industry objects matching the search query.
  - **id** (string) - Unique identifier for the industry.
  - **key** (string) - The type of classification, "INDUSTRY".
  - **value** (string) - The name of the industry (e.g., "Software Development").
  - **index** (integer) - The order of the industry in the results.
  - **metadata** (object | null) - Additional metadata about the industry.
- **totalElements** (integer) - The total number of elements available.
- **totalPages** (integer) - The total number of pages.
- **size** (integer) - The number of elements per page.
- **number** (integer) - The current page number.
- **first** (boolean) - Indicates if this is the first page.
- **last** (boolean) - Indicates if this is the last page.
- **empty** (boolean) - Indicates if the response is empty.
- **numberOfElements** (integer) - The number of elements on the current page.

### Response Example
```json
{
  "content": [
    {
      "id": "ind_001",
      "key": "INDUSTRY",
      "value": "Software Development",
      "index": 0,
      "metadata": null
    },
    {
      "id": "ind_002",
      "key": "INDUSTRY",
      "value": "Software as a Service (SaaS)",
      "index": 1,
      "metadata": null
    }
  ],
  "totalElements": 2,
  "totalPages": 1,
  "size": 25,
  "number": 0,
  "first": true,
  "last": true,
  "empty": false,
  "numberOfElements": 2
}
```
```

--------------------------------

### cURL: Export Leads (Bulk Selection with Filters)

Source: https://docs.lance.so/api-reference/operations/export

This cURL command demonstrates bulk lead export using filters. Specify `startIndex` and `targetCount` for pagination and `filters` to narrow down the selection. `excludedIds` can be used to omit specific leads.

```bash
curl -X POST "https://app.lance.so/api/v1/operations/export" \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -o "leads-export.csv" \
    -d '{
      "selection": {
        "mode": "bulk",
        "startIndex": 0,
        "targetCount": 100,
        "excludedIds": ["excluded-id-1"],
        "filters": {
          "contact": {
            "location": {
              "any": {
                "include": ["San Francisco, CA"]
              }
            }
          }
        }
      }
    }'
```

--------------------------------

### Fetch Credits History (TypeScript)

Source: https://docs.lance.so/api-reference/operations/credits-history

This TypeScript example demonstrates how to fetch credit history using the fetch API. It includes setting the Authorization header and parsing the JSON response.

```typescript
const response = await fetch(
    "/api/v1/operations/credits/history?limit=10&startDate=2025-01-01T00:00:00.000Z",
    {
      headers: {
        Authorization: `Bearer ${token}`,
      },
    }
  );

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

--------------------------------

### Get ICP

Source: https://docs.lance.so/llms.txt

Retrieves a single ICP (Ideal Customer Profile) by its ID.

```APIDOC
## Get ICP

### Description
Retrieves a single ICP (Ideal Customer Profile) by its ID.

### Method
GET

### Endpoint
/api/v1/entities/icps/{icpId}

### Parameters
#### Path Parameters
- **icpId** (string) - Required - The ID of the ICP to retrieve.

### Response
#### Success Response (200 OK)
- **id** (string) - The unique identifier of the ICP.
- **name** (string) - The name of the ICP.
- **description** (string) - The description of the ICP.
- **created_at** (string) - The timestamp when the ICP was created.
- **updated_at** (string) - The timestamp when the ICP was last updated.
```

--------------------------------

### Get Credits Balance

Source: https://docs.lance.so/api-reference/operations/credits-balance

Retrieve the current credit balance for the authenticated organization.

```APIDOC
## GET /api/v1/operations/credits/balance

### Description
Retrieve the current credit balance for the organization associated with the authenticated user.

### Method
GET

### Endpoint
/api/v1/operations/credits/balance

### Parameters
This endpoint does not require any parameters. The organization is identified automatically from the authentication context.

### Request Example
```bash
curl -X GET "https://app.lance.so/api/v1/operations/credits/balance" \
  -H "Authorization: Bearer <token>"
```

```javascript
const response = await fetch("/api/v1/operations/credits/balance", {
  method: "GET",
  headers: {
    Authorization: "Bearer <token>",
  },
});

const data = await response.json();
console.log(`Balance: ${data.balance} credits`);
```

### Response
#### Success Response (200)
- **balance** (integer) - The current credit balance for the organization. This is a non-negative integer representing the total available credits.
- **organizationId** (string) - The unique identifier of the organization whose balance was retrieved.

#### Response Example
```json
{
  "balance": 1500,
  "organizationId": "org_2abc123def456"
}
```

### Error Codes
- **400** - `VALIDATION_ERROR`: User is not authenticated or not associated with an organization.
- **500** - `INTERNAL_ERROR`: Server error while retrieving balance.
```
Tokens:
Raw