@simplyhomes/sos-sdk
Version:
TypeScript SDK for Simply Homes SoS API v4
298 lines • 61.1 kB
JavaScript
/* tslint:disable */
/* eslint-disable */
/**
* API v4
* Swagger documentation for API v4
*
* The version of the OpenAPI document: 4.0
*
*
* NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
* https://openapi-generator.tech
* Do not edit the class manually.
*/
import * as runtime from '../runtime';
import { V4ContactsCreateContactBodyDtoToJSON, V4ContactsCreateContactResponseDtoFromJSON, V4ContactsDeleteContactResponseDtoFromJSON, V4ContactsGetContactColumnsResponseDtoFromJSON, V4ContactsGetContactResponseDtoFromJSON, V4ContactsGetContactsFilteredByResponseDtoFromJSON, V4ContactsGetContactsInViewResponseDtoFromJSON, V4ContactsGetContactsResponseDtoFromJSON, V4ContactsUpdateContactBodyDtoToJSON, V4ContactsUpdateContactResponseDtoFromJSON, } from '../models/index';
/**
*
*/
export class ContactsAPIV4Api extends runtime.BaseAPI {
/**
* # POST /v4/contacts ## Overview Creates a new contact with the provided information. This endpoint allows you to add new contacts to your organization with required and optional contact details. ## Authentication - **Required**: Yes - **Security**: - `x-api-key` header - `organization-id` header ## Request Body The request body should contain contact information to create the new contact. ### Required Fields | Field | Type | Description | |-------|------|-------------| | `email` | string | Primary email address (must be unique) | | `name` | string | Contact\'s full name | ### Optional Fields | Field | Type | Description | |-------|------|-------------| | `phonePrimary` | string | Primary phone number | | `phoneSecondary` | string | Secondary phone number | ### Validation Rules - **Email**: Must be a valid email format and unique within the organization - **Name**: Required, non-empty string - **Phone Numbers**: Must follow valid phone number format if provided ## Request Example ```json { \"email\": \"new.contact@example.com\", \"name\": \"New Contact\", \"phonePrimary\": \"+1234567890\", \"phoneSecondary\": \"+0987654321\" } ``` ## Response Structure Returns the newly created contact\'s ID and confirmation. ## Use Cases This endpoint is ideal for: - **Contact Registration**: Add new contacts to the system - **Data Import**: Bulk import contacts from external systems - **User Onboarding**: Create contacts during user registration processes - **CRM Integration**: Sync contacts from external CRM systems - **Lead Capture**: Convert leads into contact records ## Validation and Constraints - **Email Uniqueness**: Email addresses must be unique within the organization - **Data Validation**: All fields are validated according to their types - **Organization Scoping**: Contacts are automatically associated with the user\'s organization - **Required Fields**: Name and email are mandatory for contact creation ## Error Handling Common validation errors include: - **Duplicate Email**: Email address already exists in the organization - **Invalid Email Format**: Email does not follow valid email format - **Missing Required Fields**: Name or email not provided - **Invalid Phone Format**: Phone numbers do not follow expected format
* Create a new contact
*/
async v4ContactsControllerCreateContactV4Raw(requestParameters, initOverrides) {
if (requestParameters['v4ContactsCreateContactBodyDto'] == null) {
throw new runtime.RequiredError('v4ContactsCreateContactBodyDto', 'Required parameter "v4ContactsCreateContactBodyDto" was null or undefined when calling v4ContactsControllerCreateContactV4().');
}
const queryParameters = {};
const headerParameters = {};
headerParameters['Content-Type'] = 'application/json';
if (this.configuration && this.configuration.apiKey) {
headerParameters["x-api-key"] = await this.configuration.apiKey("x-api-key"); // x-api-key authentication
}
if (this.configuration && this.configuration.apiKey) {
headerParameters["organization-id"] = await this.configuration.apiKey("organization-id"); // organization-id authentication
}
let urlPath = `/v4/contacts`;
const response = await this.request({
path: urlPath,
method: 'POST',
headers: headerParameters,
query: queryParameters,
body: V4ContactsCreateContactBodyDtoToJSON(requestParameters['v4ContactsCreateContactBodyDto']),
}, initOverrides);
return new runtime.JSONApiResponse(response, (jsonValue) => V4ContactsCreateContactResponseDtoFromJSON(jsonValue));
}
/**
* # POST /v4/contacts ## Overview Creates a new contact with the provided information. This endpoint allows you to add new contacts to your organization with required and optional contact details. ## Authentication - **Required**: Yes - **Security**: - `x-api-key` header - `organization-id` header ## Request Body The request body should contain contact information to create the new contact. ### Required Fields | Field | Type | Description | |-------|------|-------------| | `email` | string | Primary email address (must be unique) | | `name` | string | Contact\'s full name | ### Optional Fields | Field | Type | Description | |-------|------|-------------| | `phonePrimary` | string | Primary phone number | | `phoneSecondary` | string | Secondary phone number | ### Validation Rules - **Email**: Must be a valid email format and unique within the organization - **Name**: Required, non-empty string - **Phone Numbers**: Must follow valid phone number format if provided ## Request Example ```json { \"email\": \"new.contact@example.com\", \"name\": \"New Contact\", \"phonePrimary\": \"+1234567890\", \"phoneSecondary\": \"+0987654321\" } ``` ## Response Structure Returns the newly created contact\'s ID and confirmation. ## Use Cases This endpoint is ideal for: - **Contact Registration**: Add new contacts to the system - **Data Import**: Bulk import contacts from external systems - **User Onboarding**: Create contacts during user registration processes - **CRM Integration**: Sync contacts from external CRM systems - **Lead Capture**: Convert leads into contact records ## Validation and Constraints - **Email Uniqueness**: Email addresses must be unique within the organization - **Data Validation**: All fields are validated according to their types - **Organization Scoping**: Contacts are automatically associated with the user\'s organization - **Required Fields**: Name and email are mandatory for contact creation ## Error Handling Common validation errors include: - **Duplicate Email**: Email address already exists in the organization - **Invalid Email Format**: Email does not follow valid email format - **Missing Required Fields**: Name or email not provided - **Invalid Phone Format**: Phone numbers do not follow expected format
* Create a new contact
*/
async v4ContactsControllerCreateContactV4(requestParameters, initOverrides) {
const response = await this.v4ContactsControllerCreateContactV4Raw(requestParameters, initOverrides);
return await response.value();
}
/**
* # DELETE /v4/contacts/{contactId} ## Overview Deletes an existing contact from the system. This is a permanent operation that removes the contact and all associated data. ## Authentication - **Required**: Yes - **Security**: - `x-api-key` header - `organization-id` header ## Request Parameters ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `contactId` | number | Yes | The unique identifier of the contact to delete | ## Access Control - **Organization Scope**: Contact must belong to the authenticated user\'s organization - **Contact Validation**: Invalid or non-existent contact IDs will return a 404 error - **Data Privacy**: Only contacts within the user\'s organization can be deleted ## Deletion Behavior The deletion operation: - **Permanent Removal**: Contact is permanently deleted from the system - **Cascade Effects**: Associated relationships and references are handled appropriately - **Immediate Effect**: Deletion is applied immediately - **Audit Trail**: Deletion is logged for audit and compliance purposes ## Response Structure Returns confirmation that the contact was successfully deleted. ## Use Cases This endpoint is ideal for: - **Contact Cleanup**: Remove outdated or duplicate contacts - **Data Management**: Maintain clean contact databases - **Compliance**: Delete contacts upon user request (GDPR, etc.) - **System Maintenance**: Remove test or invalid contact data - **Workflow Management**: Clean up contacts after workflow completion ## Important Considerations Before deleting a contact, consider: - **Associated Data**: Check if contact is referenced by other entities - **Backup Requirements**: Ensure proper backup if recovery might be needed - **Compliance**: Follow data retention and deletion policies - **User Notification**: Consider notifying relevant users of the deletion - **Alternative Actions**: Consider deactivating instead of deleting ## Error Handling Common errors include: - **Contact Not Found**: Contact ID does not exist or belongs to different organization - **Permission Denied**: User lacks permission to delete contacts - **Referential Constraints**: Contact cannot be deleted due to active references - **System Errors**: Database or system issues preventing deletion ## Recovery - **No Recovery**: Deleted contacts cannot be restored through the API - **Backup Systems**: Recovery may be possible through system backups - **Audit Logs**: Deletion events are recorded for audit purposes - **Compliance**: Follow organizational data recovery policies
* Delete a specific contact by contactId
*/
async v4ContactsControllerDeleteContactV4Raw(requestParameters, initOverrides) {
if (requestParameters['contactId'] == null) {
throw new runtime.RequiredError('contactId', 'Required parameter "contactId" was null or undefined when calling v4ContactsControllerDeleteContactV4().');
}
const queryParameters = {};
const headerParameters = {};
if (this.configuration && this.configuration.apiKey) {
headerParameters["x-api-key"] = await this.configuration.apiKey("x-api-key"); // x-api-key authentication
}
if (this.configuration && this.configuration.apiKey) {
headerParameters["organization-id"] = await this.configuration.apiKey("organization-id"); // organization-id authentication
}
let urlPath = `/v4/contacts/{contactId}`;
urlPath = urlPath.replace(`{${"contactId"}}`, encodeURIComponent(String(requestParameters['contactId'])));
const response = await this.request({
path: urlPath,
method: 'DELETE',
headers: headerParameters,
query: queryParameters,
}, initOverrides);
return new runtime.JSONApiResponse(response, (jsonValue) => V4ContactsDeleteContactResponseDtoFromJSON(jsonValue));
}
/**
* # DELETE /v4/contacts/{contactId} ## Overview Deletes an existing contact from the system. This is a permanent operation that removes the contact and all associated data. ## Authentication - **Required**: Yes - **Security**: - `x-api-key` header - `organization-id` header ## Request Parameters ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `contactId` | number | Yes | The unique identifier of the contact to delete | ## Access Control - **Organization Scope**: Contact must belong to the authenticated user\'s organization - **Contact Validation**: Invalid or non-existent contact IDs will return a 404 error - **Data Privacy**: Only contacts within the user\'s organization can be deleted ## Deletion Behavior The deletion operation: - **Permanent Removal**: Contact is permanently deleted from the system - **Cascade Effects**: Associated relationships and references are handled appropriately - **Immediate Effect**: Deletion is applied immediately - **Audit Trail**: Deletion is logged for audit and compliance purposes ## Response Structure Returns confirmation that the contact was successfully deleted. ## Use Cases This endpoint is ideal for: - **Contact Cleanup**: Remove outdated or duplicate contacts - **Data Management**: Maintain clean contact databases - **Compliance**: Delete contacts upon user request (GDPR, etc.) - **System Maintenance**: Remove test or invalid contact data - **Workflow Management**: Clean up contacts after workflow completion ## Important Considerations Before deleting a contact, consider: - **Associated Data**: Check if contact is referenced by other entities - **Backup Requirements**: Ensure proper backup if recovery might be needed - **Compliance**: Follow data retention and deletion policies - **User Notification**: Consider notifying relevant users of the deletion - **Alternative Actions**: Consider deactivating instead of deleting ## Error Handling Common errors include: - **Contact Not Found**: Contact ID does not exist or belongs to different organization - **Permission Denied**: User lacks permission to delete contacts - **Referential Constraints**: Contact cannot be deleted due to active references - **System Errors**: Database or system issues preventing deletion ## Recovery - **No Recovery**: Deleted contacts cannot be restored through the API - **Backup Systems**: Recovery may be possible through system backups - **Audit Logs**: Deletion events are recorded for audit purposes - **Compliance**: Follow organizational data recovery policies
* Delete a specific contact by contactId
*/
async v4ContactsControllerDeleteContactV4(requestParameters, initOverrides) {
const response = await this.v4ContactsControllerDeleteContactV4Raw(requestParameters, initOverrides);
return await response.value();
}
/**
* # GET /v4/contacts/columns ## Overview Retrieves the available column definitions for the contacts entity. This endpoint provides metadata about all available contact fields including their types, display names, and formatting information. ## Authentication - **Required**: Yes - **Security**: - `x-api-key` header - `organization-id` header ## Request Parameters No parameters required for this endpoint. ## Response Structure Returns an array of column definition objects describing all available contact fields. ## Use Cases This endpoint is ideal for: - **Dynamic UI Generation**: Build contact tables and forms dynamically - **View Configuration**: Provide column options for custom view creation - **Data Export**: Understand available fields for export functionality - **API Integration**: Discover available contact fields for API consumers - **Reporting Tools**: Generate reports with proper column metadata ## Column Metadata Each column definition includes: - **Field Name**: Database field identifier - **Display Name**: Human-readable column title - **Data Type**: Field data type (string, number, date, etc.) - **Formatting**: Display formatting requirements - **Validation**: Field validation rules and constraints ## Performance Benefits - **Cached Response**: Column definitions are typically cached for performance - **Lightweight**: Metadata-only response with minimal data transfer - **Client Optimization**: Enables efficient client-side UI generation
* Get specific columns of a contact by contactId
*/
async v4ContactsControllerGetContactColumnsV4Raw(requestParameters, initOverrides) {
if (requestParameters['columns'] == null) {
throw new runtime.RequiredError('columns', 'Required parameter "columns" was null or undefined when calling v4ContactsControllerGetContactColumnsV4().');
}
if (requestParameters['contactId'] == null) {
throw new runtime.RequiredError('contactId', 'Required parameter "contactId" was null or undefined when calling v4ContactsControllerGetContactColumnsV4().');
}
const queryParameters = {};
const headerParameters = {};
if (this.configuration && this.configuration.apiKey) {
headerParameters["x-api-key"] = await this.configuration.apiKey("x-api-key"); // x-api-key authentication
}
if (this.configuration && this.configuration.apiKey) {
headerParameters["organization-id"] = await this.configuration.apiKey("organization-id"); // organization-id authentication
}
let urlPath = `/v4/contacts/{contactId}/{columns}`;
urlPath = urlPath.replace(`{${"columns"}}`, encodeURIComponent(String(requestParameters['columns'])));
urlPath = urlPath.replace(`{${"contactId"}}`, encodeURIComponent(String(requestParameters['contactId'])));
const response = await this.request({
path: urlPath,
method: 'GET',
headers: headerParameters,
query: queryParameters,
}, initOverrides);
return new runtime.JSONApiResponse(response, (jsonValue) => V4ContactsGetContactColumnsResponseDtoFromJSON(jsonValue));
}
/**
* # GET /v4/contacts/columns ## Overview Retrieves the available column definitions for the contacts entity. This endpoint provides metadata about all available contact fields including their types, display names, and formatting information. ## Authentication - **Required**: Yes - **Security**: - `x-api-key` header - `organization-id` header ## Request Parameters No parameters required for this endpoint. ## Response Structure Returns an array of column definition objects describing all available contact fields. ## Use Cases This endpoint is ideal for: - **Dynamic UI Generation**: Build contact tables and forms dynamically - **View Configuration**: Provide column options for custom view creation - **Data Export**: Understand available fields for export functionality - **API Integration**: Discover available contact fields for API consumers - **Reporting Tools**: Generate reports with proper column metadata ## Column Metadata Each column definition includes: - **Field Name**: Database field identifier - **Display Name**: Human-readable column title - **Data Type**: Field data type (string, number, date, etc.) - **Formatting**: Display formatting requirements - **Validation**: Field validation rules and constraints ## Performance Benefits - **Cached Response**: Column definitions are typically cached for performance - **Lightweight**: Metadata-only response with minimal data transfer - **Client Optimization**: Enables efficient client-side UI generation
* Get specific columns of a contact by contactId
*/
async v4ContactsControllerGetContactColumnsV4(requestParameters, initOverrides) {
const response = await this.v4ContactsControllerGetContactColumnsV4Raw(requestParameters, initOverrides);
return await response.value();
}
/**
* # GET /v4/contacts/{contactId} ## Overview Retrieves detailed information for a specific contact by its unique identifier. This endpoint returns complete contact data including all available fields and metadata. ## Authentication - **Required**: Yes - **Security**: - `x-api-key` header - `organization-id` header ## Request Parameters ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `contactId` | number | Yes | The unique identifier of the contact to retrieve | ## Access Control - **Organization Scope**: Contact must belong to the authenticated user\'s organization - **Contact Validation**: Invalid or non-existent contact IDs will return a 404 error - **Data Privacy**: Only contacts within the user\'s organization are accessible ## Response Structure Returns a complete contact object with all available fields and metadata. ## Use Cases This endpoint is ideal for: - **Contact Detail Views**: Display full contact information in detail pages - **Contact Editing**: Retrieve current data before updates - **Contact Verification**: Validate contact existence and data - **Integration Workflows**: Get complete contact data for external system sync - **Contact Analytics**: Access detailed contact information for reporting ## Performance Considerations - **Single Record Fetch**: Optimized for retrieving individual contacts - **Complete Data**: Returns all available contact fields - **Real-time Data**: Always returns current contact state - **Organization Filtering**: Automatic organization scoping ensures security
* Get a specific contact by contactId
*/
async v4ContactsControllerGetContactV4Raw(requestParameters, initOverrides) {
if (requestParameters['contactId'] == null) {
throw new runtime.RequiredError('contactId', 'Required parameter "contactId" was null or undefined when calling v4ContactsControllerGetContactV4().');
}
const queryParameters = {};
if (requestParameters['viewId'] != null) {
queryParameters['viewId'] = requestParameters['viewId'];
}
const headerParameters = {};
if (this.configuration && this.configuration.apiKey) {
headerParameters["x-api-key"] = await this.configuration.apiKey("x-api-key"); // x-api-key authentication
}
if (this.configuration && this.configuration.apiKey) {
headerParameters["organization-id"] = await this.configuration.apiKey("organization-id"); // organization-id authentication
}
let urlPath = `/v4/contacts/{contactId}`;
urlPath = urlPath.replace(`{${"contactId"}}`, encodeURIComponent(String(requestParameters['contactId'])));
const response = await this.request({
path: urlPath,
method: 'GET',
headers: headerParameters,
query: queryParameters,
}, initOverrides);
return new runtime.JSONApiResponse(response, (jsonValue) => V4ContactsGetContactResponseDtoFromJSON(jsonValue));
}
/**
* # GET /v4/contacts/{contactId} ## Overview Retrieves detailed information for a specific contact by its unique identifier. This endpoint returns complete contact data including all available fields and metadata. ## Authentication - **Required**: Yes - **Security**: - `x-api-key` header - `organization-id` header ## Request Parameters ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `contactId` | number | Yes | The unique identifier of the contact to retrieve | ## Access Control - **Organization Scope**: Contact must belong to the authenticated user\'s organization - **Contact Validation**: Invalid or non-existent contact IDs will return a 404 error - **Data Privacy**: Only contacts within the user\'s organization are accessible ## Response Structure Returns a complete contact object with all available fields and metadata. ## Use Cases This endpoint is ideal for: - **Contact Detail Views**: Display full contact information in detail pages - **Contact Editing**: Retrieve current data before updates - **Contact Verification**: Validate contact existence and data - **Integration Workflows**: Get complete contact data for external system sync - **Contact Analytics**: Access detailed contact information for reporting ## Performance Considerations - **Single Record Fetch**: Optimized for retrieving individual contacts - **Complete Data**: Returns all available contact fields - **Real-time Data**: Always returns current contact state - **Organization Filtering**: Automatic organization scoping ensures security
* Get a specific contact by contactId
*/
async v4ContactsControllerGetContactV4(requestParameters, initOverrides) {
const response = await this.v4ContactsControllerGetContactV4Raw(requestParameters, initOverrides);
return await response.value();
}
/**
* # GET /v4/contacts/filteredBy/{column}/{value} ## Overview Retrieves contacts filtered by a specific column and value combination. This endpoint allows you to filter contacts based on any contact field with customizable filter operations, optional view configurations, and pagination support. ## Authentication - **Required**: Yes - **Security**: - `x-api-key` header - `organization-id` header ## Request Parameters ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `column` | string | Yes | The contact column/field to filter by (e.g., \"email\", \"name\", \"phonePrimary\") | | `value` | string | Yes | The value to filter the column by (e.g., \"john@example.com\", \"John Doe\", \"555-0123\") | ### Query Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `filterOperation` | string | No | Filter operation to apply (default: \"is\"). Options: is, isNot, contains, startsWith, endsWith, greaterThan, lessThan, etc. | | `viewId` | number | No | Optional view ID to apply additional filters, sorts, and column selections | | `columns` | string | No | Specific columns to return, formatted as \"column1&column2&column3\" | | `limit` | number | No | Maximum number of contacts to return (default: 20, max: 100) | | `offset` | number | No | Number of contacts to skip for pagination (default: 0) | | `countOnly` | boolean | No | Whether to return only the count of matching contacts instead of the full objects | ## Filter Operations The `filterOperation` parameter supports different operations based on data type: ### String Operations - **is**: Exact match (default) - **isNot**: Not equal to - **contains**: Contains substring - **startsWith**: Starts with value - **endsWith**: Ends with value ### Number Operations - **is**: Exact match - **isNot**: Not equal to - **greaterThan**: Greater than value - **lessThan**: Less than value - **greaterThanOrEqual**: Greater than or equal to value - **lessThanOrEqual**: Less than or equal to value ### Boolean Operations - **is**: Exact match - **isNot**: Opposite value ### Array Operations - **contains**: Array contains value - **doesNotContain**: Array does not contain value ## Access Control - **Organization Scope**: Contacts are automatically filtered by organization - **Contact Ownership**: Only contacts within the organization can be accessed - **Data Privacy**: Contact data is isolated between organizations ## View Integration When a `viewId` is provided: - **Additional Filters**: View filters are combined with the column/value filter - **Sorts**: View sort configurations determine result ordering - **Columns**: View column selections override the columns parameter - **Validation**: View must exist and belong to the authenticated user ## Response Structure The response contains an array of contact objects matching the filter criteria with pagination metadata. ## Use Cases This endpoint is ideal for: - **Contact Search**: Filter contacts by specific criteria (email, name, phone) - **Dynamic Filtering**: Build custom search interfaces with user-defined filters - **Data Analysis**: Query contacts matching specific characteristics - **Report Generation**: Extract subsets of contacts for reporting - **Integration**: Provide filtered contact data to external systems ## Examples ### Filter by Email `GET /v4/contacts/filteredBy/email/john@example.com` ### Filter by Name with Contains Operation `GET /v4/contacts/filteredBy/name/John?filterOperation=contains` ### Filter with View and Pagination `GET /v4/contacts/filteredBy/phonePrimary/555?viewId=view123&limit=50&offset=0&filterOperation=contains` ### Count Only Results `GET /v4/contacts/filteredBy/email/gmail.com?countOnly=true&filterOperation=contains` ## Performance Considerations - **Index Usage**: Filtering on indexed columns improves query performance - **Pagination**: Use appropriate limit values to balance performance and data needs - **View Optimization**: Well-designed views with targeted filters improve response times - **Column Selection**: Limit returned columns through views or columns parameter for better performance ## Integration Patterns **Basic Filtering:** - Simple column/value filtering with default \"is\" operation - Useful for dropdown-based filters and category selection **Advanced Filtering:** - Combine with filter operations for complex queries - Use with views for consistent, reusable filter combinations **Search Interfaces:** - Build dynamic search forms where users select columns and values - Support multiple filter operations for flexible searching
* Get contacts filtered by a specific column and value
*/
async v4ContactsControllerGetContactsFilteredByV4Raw(requestParameters, initOverrides) {
if (requestParameters['column'] == null) {
throw new runtime.RequiredError('column', 'Required parameter "column" was null or undefined when calling v4ContactsControllerGetContactsFilteredByV4().');
}
if (requestParameters['value'] == null) {
throw new runtime.RequiredError('value', 'Required parameter "value" was null or undefined when calling v4ContactsControllerGetContactsFilteredByV4().');
}
const queryParameters = {};
if (requestParameters['viewId'] != null) {
queryParameters['viewId'] = requestParameters['viewId'];
}
if (requestParameters['columns'] != null) {
queryParameters['columns'] = requestParameters['columns'];
}
if (requestParameters['limit'] != null) {
queryParameters['limit'] = requestParameters['limit'];
}
if (requestParameters['offset'] != null) {
queryParameters['offset'] = requestParameters['offset'];
}
if (requestParameters['countOnly'] != null) {
queryParameters['countOnly'] = requestParameters['countOnly'];
}
if (requestParameters['filterOperation'] != null) {
queryParameters['filterOperation'] = requestParameters['filterOperation'];
}
const headerParameters = {};
if (this.configuration && this.configuration.apiKey) {
headerParameters["x-api-key"] = await this.configuration.apiKey("x-api-key"); // x-api-key authentication
}
if (this.configuration && this.configuration.apiKey) {
headerParameters["organization-id"] = await this.configuration.apiKey("organization-id"); // organization-id authentication
}
let urlPath = `/v4/contacts/filteredBy/{column}/{value}`;
urlPath = urlPath.replace(`{${"column"}}`, encodeURIComponent(String(requestParameters['column'])));
urlPath = urlPath.replace(`{${"value"}}`, encodeURIComponent(String(requestParameters['value'])));
const response = await this.request({
path: urlPath,
method: 'GET',
headers: headerParameters,
query: queryParameters,
}, initOverrides);
return new runtime.JSONApiResponse(response, (jsonValue) => V4ContactsGetContactsFilteredByResponseDtoFromJSON(jsonValue));
}
/**
* # GET /v4/contacts/filteredBy/{column}/{value} ## Overview Retrieves contacts filtered by a specific column and value combination. This endpoint allows you to filter contacts based on any contact field with customizable filter operations, optional view configurations, and pagination support. ## Authentication - **Required**: Yes - **Security**: - `x-api-key` header - `organization-id` header ## Request Parameters ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `column` | string | Yes | The contact column/field to filter by (e.g., \"email\", \"name\", \"phonePrimary\") | | `value` | string | Yes | The value to filter the column by (e.g., \"john@example.com\", \"John Doe\", \"555-0123\") | ### Query Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `filterOperation` | string | No | Filter operation to apply (default: \"is\"). Options: is, isNot, contains, startsWith, endsWith, greaterThan, lessThan, etc. | | `viewId` | number | No | Optional view ID to apply additional filters, sorts, and column selections | | `columns` | string | No | Specific columns to return, formatted as \"column1&column2&column3\" | | `limit` | number | No | Maximum number of contacts to return (default: 20, max: 100) | | `offset` | number | No | Number of contacts to skip for pagination (default: 0) | | `countOnly` | boolean | No | Whether to return only the count of matching contacts instead of the full objects | ## Filter Operations The `filterOperation` parameter supports different operations based on data type: ### String Operations - **is**: Exact match (default) - **isNot**: Not equal to - **contains**: Contains substring - **startsWith**: Starts with value - **endsWith**: Ends with value ### Number Operations - **is**: Exact match - **isNot**: Not equal to - **greaterThan**: Greater than value - **lessThan**: Less than value - **greaterThanOrEqual**: Greater than or equal to value - **lessThanOrEqual**: Less than or equal to value ### Boolean Operations - **is**: Exact match - **isNot**: Opposite value ### Array Operations - **contains**: Array contains value - **doesNotContain**: Array does not contain value ## Access Control - **Organization Scope**: Contacts are automatically filtered by organization - **Contact Ownership**: Only contacts within the organization can be accessed - **Data Privacy**: Contact data is isolated between organizations ## View Integration When a `viewId` is provided: - **Additional Filters**: View filters are combined with the column/value filter - **Sorts**: View sort configurations determine result ordering - **Columns**: View column selections override the columns parameter - **Validation**: View must exist and belong to the authenticated user ## Response Structure The response contains an array of contact objects matching the filter criteria with pagination metadata. ## Use Cases This endpoint is ideal for: - **Contact Search**: Filter contacts by specific criteria (email, name, phone) - **Dynamic Filtering**: Build custom search interfaces with user-defined filters - **Data Analysis**: Query contacts matching specific characteristics - **Report Generation**: Extract subsets of contacts for reporting - **Integration**: Provide filtered contact data to external systems ## Examples ### Filter by Email `GET /v4/contacts/filteredBy/email/john@example.com` ### Filter by Name with Contains Operation `GET /v4/contacts/filteredBy/name/John?filterOperation=contains` ### Filter with View and Pagination `GET /v4/contacts/filteredBy/phonePrimary/555?viewId=view123&limit=50&offset=0&filterOperation=contains` ### Count Only Results `GET /v4/contacts/filteredBy/email/gmail.com?countOnly=true&filterOperation=contains` ## Performance Considerations - **Index Usage**: Filtering on indexed columns improves query performance - **Pagination**: Use appropriate limit values to balance performance and data needs - **View Optimization**: Well-designed views with targeted filters improve response times - **Column Selection**: Limit returned columns through views or columns parameter for better performance ## Integration Patterns **Basic Filtering:** - Simple column/value filtering with default \"is\" operation - Useful for dropdown-based filters and category selection **Advanced Filtering:** - Combine with filter operations for complex queries - Use with views for consistent, reusable filter combinations **Search Interfaces:** - Build dynamic search forms where users select columns and values - Support multiple filter operations for flexible searching
* Get contacts filtered by a specific column and value
*/
async v4ContactsControllerGetContactsFilteredByV4(requestParameters, initOverrides) {
const response = await this.v4ContactsControllerGetContactsFilteredByV4Raw(requestParameters, initOverrides);
return await response.value();
}
/**
* # GET /v4/contacts/viewId/{viewId} ## Overview Retrieves contacts filtered by a specific view configuration. This endpoint applies the filters, sorts, and column selections defined in the specified view to return a customized dataset of contacts. ## Authentication - **Required**: Yes - **Security**: - `x-api-key` header - `organization-id` header ## Request Parameters ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `viewId` | number | Yes | The unique identifier of the view to apply | ### Query Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | number | No | Maximum number of contacts to return (default: 20, max: 100) | | `offset` | number | No | Number of contacts to skip for pagination (default: 0) | | `countOnly` | boolean | No | Return only the count of contacts without the actual data | ## View Application The specified view configuration is applied automatically: - **Filters**: All view filters are applied to narrow the contact dataset - **Sorts**: View sort criteria determine the order of returned contacts - **Columns**: View column selection determines which fields are returned - **Validation**: View must exist and belong to the authenticated user ## Access Control - **User Ownership**: Only views created by the authenticated user can be used - **Organization Scope**: Contacts are automatically filtered by organization - **View Validation**: Invalid or non-existent views will return an error ## Response Structure The response contains contacts matching the view criteria with pagination metadata. ## Use Cases This endpoint is ideal for: - **Saved Searches**: Quickly access frequently used contact filters - **Custom Dashboards**: Display contacts using predefined view configurations - **Report Generation**: Generate consistent reports using saved view criteria - **User Workflows**: Provide quick access to personalized contact subsets - **Contact Management**: Apply complex filter combinations saved in views ## Performance Benefits Using views provides several performance advantages: - **Pre-validated Filters**: View filters are validated once during creation - **Consistent Queries**: Same view produces optimized, consistent database queries - **Reduced Complexity**: Complex filter logic is encapsulated in the view - **Caching Opportunities**: Results can be cached based on view configuration ## Pagination Standard pagination is supported: - **Consistent Results**: Pagination maintains view filter consistency - **Stable Ordering**: View sort configuration ensures stable result ordering - **Performance**: Large filtered datasets benefit from pagination
* Get contacts with a specific viewId
*/
async v4ContactsControllerGetContactsInViewV4Raw(requestParameters, initOverrides) {
if (requestParameters['viewId'] == null) {
throw new runtime.RequiredError('viewId', 'Required parameter "viewId" was null or undefined when calling v4ContactsControllerGetContactsInViewV4().');
}
const queryParameters = {};
if (requestParameters['limit'] != null) {
queryParameters['limit'] = requestParameters['limit'];
}
if (requestParameters['offset'] != null) {
queryParameters['offset'] = requestParameters['offset'];
}
if (requestParameters['countOnly'] != null) {
queryParameters['countOnly'] = requestParameters['countOnly'];
}
const headerParameters = {};
if (this.configuration && this.configuration.apiKey) {
headerParameters["x-api-key"] = await this.configuration.apiKey("x-api-key"); // x-api-key authentication
}
if (this.configuration && this.configuration.apiKey) {
headerParameters["organization-id"] = await this.configuration.apiKey("organization-id"); // organization-id authentication
}
let urlPath = `/v4/contacts/viewId/{viewId}`;
urlPath = urlPath.replace(`{${"viewId"}}`, encodeURIComponent(String(requestParameters['viewId'])));
const response = await this.request({
path: urlPath,
method: 'GET',
headers: headerParameters,
query: queryParameters,
}, initOverrides);
return new runtime.JSONApiResponse(response, (jsonValue) => V4ContactsGetContactsInViewResponseDtoFromJSON(jsonValue));
}
/**
* # GET /v4/contacts/viewId/{viewId} ## Overview Retrieves contacts filtered by a specific view configuration. This endpoint applies the filters, sorts, and column selections defined in the specified view to return a customized dataset of contacts. ## Authentication - **Required**: Yes - **Security**: - `x-api-key` header - `organization-id` header ## Request Parameters ### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `viewId` | number | Yes | The unique identifier of the view to apply | ### Query Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | number | No | Maximum number of contacts to return (default: 20, max: 100) | | `offset` | number | No | Number of contacts to skip for pagination (default: 0) | | `countOnly` | boolean | No | Return only the count of contacts without the actual data | ## View Application The specified view configuration is applied automatically: - **Filters**: All view filters are applied to narrow the contact dataset - **Sorts**: View sort criteria determine the order of returned contacts - **Columns**: View column selection determines which fields are returned - **Validation**: View must exist and belong to the authenticated user ## Access Control - **User Ownership**: Only views created by the authenticated user can be used - **Organization Scope**: Contacts are automatically filtered by organization - **View Validation**: Invalid or non-existent views will return an error ## Response Structure The response contains contacts matching the view criteria with pagination metadata. ## Use Cases This endpoint is ideal for: - **Saved Searches**: Quickly access frequently used contact filters - **Custom Dashboards**: Display contacts using predefined view configurations - **Report Generation**: Generate consistent reports using saved view criteria - **User Workflows**: Provide quick access to personalized contact subsets - **Contact Management**: Apply complex filter combinations saved in views ## Performance Benefits Using views provides several performance advantages: - **Pre-validated Filters**: View filters are validated once during creation - **Consistent Queries**: Same view produces optimized, consistent database queries - **Reduced Complexity**: Complex filter logic is encapsulated in the view - **Caching Opportunities**: Results can be cached based on view configuration ## Pagination Standard pagination is supported: - **Consistent Results**: Pagination maintains view filter consistency - **Stable Ordering**: View sort configuration ensures stable result ordering - **Performance**: Large filtered datasets benefit from pagination
* Get contacts with a specific viewId
*/
async v4ContactsControllerGetContactsInViewV4(requestParameters, initOverrides) {
const response = await this.v4ContactsControllerGetContactsInViewV4Raw(requestParameters, initOverrides);
return await response.value();
}
/**
* # GET /v4/contacts ## Overview Retrieves a list of contacts with optional filtering, sorting, and pagination capabilities. This endpoint allows you to query contacts using view configurations or direct parameters to get customized contact datasets. ## Authentication - **Required**: Yes - **Security**: - `x-api-key` header - `organization-id` header ## Request Parameters ### Query Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `viewId` | number | No | Optional view ID to apply filters, sorts, and column selections | | `limit` | number | No | Maximum number of contacts to return (default: 20, max: 100) | | `offset` | number | No | Number of contacts to skip for pagination (default: 0) | | `countOnly` | boolean | No | Return only the count of contacts without the actual data | ### View Integration When a `viewId` is provided: - **Filters**: View filters are automatically applied to the query - **Sorts**: View sort configurations determine result ordering - **Columns**: View column selections determine returned fields - **Validation**: View must exist and belong to the authenticated user ### Pagination The endpoint supports offset-based pagination: - **Default Limit**: 20 contacts per request - **Maximum Limit**: 100 contacts per request - **Offset Calculation**: Use `offset = page * limit` for page-based pagination ## Response Structure The response contains an array of contact objects with pagination metadata. ## Use Cases This endpoint is ideal for: - Building contact listing interfaces - Implementing contact search and filtering - Creating contact dashboards and analytics - Generating contact reports and exports - Providing contact data for mobile applications - Managing customer and vendor relationships ## Performance Considerations - **Pagination**: Use appropriate limit values to balance performance and data needs - **View Optimization**: Well-designed views with targeted filters improve response times - **Column Selection**: Limit returned columns through views for better performance - **Caching**: Consider implementing client-side caching for frequently accessed data ## Integration Patterns **Standard Listing:** - No viewId: Returns all organization contacts with default columns - Basic pagination: Use limit/offset for page navigation **Filtered Views:** - With viewId: Returns contacts matching view criteria - Consistent Results: Same view always returns same filtered dataset - User Personalization: Each user can have custom views for different purposes
* Get contacts with optional viewId
*/
async v4ContactsControllerGetContactsV4Raw(requestParameters, initOverrides) {
const queryParameters = {};
if (requestParameters['viewId'] != null) {
queryParameters['viewId'] = requestParameters['viewId'];
}
if (requestParameters['limit'] != null) {
queryParameters['limit'] = requestParameters['limit'];
}
if (requestParameters['offset'] != null) {
queryParameters['offset'] = requestParameters['offset'];
}
if (requestParameters['countOnly'] != null) {
queryParameters['countOnly'] = requestParameters['countOnly'];
}
const headerParameters = {};
if (this.configuration && this.configuration.apiKey) {
headerParameters["x-api-key"] = await this.configuration.apiKey("x-api-key"); // x-api-key authentication
}
if (this.configuration && this.configuration.apiKey) {
headerParameters["organization-id"] = await this.configuration.apiKey("organization-id"); // organization-id authentication
}
let urlPath = `/v4/contacts`;
const response = await this.request({
path: urlPath,
method: 'GET',
headers: headerParameters,
query: queryParameters,
}, initOverrides);
return new runtime.JSONApiResponse(response, (jsonValue) => V4ContactsGetContactsResponseDtoFromJSON(jsonValue));
}
/**
* # GET /v4/contacts ## Overview Retrieves a list of contacts with optional filtering, sorting, and pagination capabilities. This endpoint allows you to query contacts using view configurations or direct parameters to get customized contact datasets. ## Authentication - **Required**: Yes - **Security**: - `x-api-key` header - `organization-id` header ## Request Parameters ### Query Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `viewId` | number | No | Optional view ID to apply filters, sorts, and column selections | | `limit` | number | No | Maximum number of contacts to return (default: 20, max: 100) | | `offset` | number | No | Number of contacts to skip for pagination (default: 0) | | `countOnly` | boolean | No | Return only the count of contacts without the actual data | ### View Integration When a `viewId` is provided: - **Filters**: View filters are automatically applied to the query - **Sorts**: View sort configurations determine result ordering - **Columns**: View column selections determine returned fields - **Validation**: View must exist and belong to the authenticated user ### Pagination The endpoint supports offset-based pagination: - **Default Limit**: 20 contacts per request - **Maximum Limit**: 100 contacts per request - **Offset Calculation**: Use `offset = page * limit` for page-based pagination ## Response Structure The response contains an array of contact objects with pagination metadata. ## Use Cases This endpoint is ideal for: - Building contact listing interfaces - Implementing contact search and filtering - Creating contact dashboards and analytics - Generating contact reports and exports - Providing contact data for mobile applications - Managing customer and vendor relationships ## Performance Considerations - **Pagination**: Use appropriate limit values to balance performance and data needs - **View Optimization**: Well-designed views wit