@simplyhomes/sos-sdk

/** * 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 type { V4ContactsCreateContactBodyDto, V4ContactsCreateContactResponseDto, V4ContactsDeleteContactResponseDto, V4ContactsGetContactColumnsResponseDto, V4ContactsGetContactResponseDto, V4ContactsGetContactsFilteredByResponseDto, V4ContactsGetContactsInViewResponseDto, V4ContactsGetContactsResponseDto, V4ContactsUpdateContactBodyDto, V4ContactsUpdateContactResponseDto } from '../models/index'; export interface V4ContactsControllerCreateContactV4Request { v4ContactsCreateContactBodyDto: V4ContactsCreateContactBodyDto; } export interface V4ContactsControllerDeleteContactV4Request { contactId: number; } export interface V4ContactsControllerGetContactColumnsV4Request { columns: string; contactId: number; } export interface V4ContactsControllerGetContactV4Request { contactId: number; viewId?: number; } export interface V4ContactsControllerGetContactsFilteredByV4Request { column: string; value: string; viewId?: number; columns?: string; limit?: number; offset?: number; countOnly?: boolean; filterOperation?: V4ContactsControllerGetContactsFilteredByV4FilterOperation; } export interface V4ContactsControllerGetContactsInViewV4Request { viewId: number; limit?: number; offset?: number; countOnly?: boolean; } export interface V4ContactsControllerGetContactsV4Request { viewId?: number; limit?: number; offset?: number; countOnly?: boolean; } export interface V4ContactsControllerUpdateContactV4Request { contactId: number; v4ContactsUpdateContactBodyDto: V4ContactsUpdateContactBodyDto; } /** * ContactsAPIV4Api - interface * * @export * @interface ContactsAPIV4ApiInterface */ export interface ContactsAPIV4ApiInterface { /** * # 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 * @summary Create a new contact * @param {V4ContactsCreateContactBodyDto} v4ContactsCreateContactBodyDto * @param {*} [options] Override http request option. * @throws {RequiredError} * @memberof ContactsAPIV4ApiInterface */ v4ContactsControllerCreateContactV4Raw(requestParameters: V4ContactsControllerCreateContactV4Request, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<V4ContactsCreateContactResponseDto>>; /** * # 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 */ v4ContactsControllerCreateContactV4(requestParameters: V4ContactsControllerCreateContactV4Request, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<V4ContactsCreateContactResponseDto>; /** * # 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 * @summary Delete a specific contact by contactId * @param {number} contactId The unique identifier of the contact * @param {*} [options] Override http request option. * @throws {RequiredError} * @memberof ContactsAPIV4ApiInterface */ v4ContactsControllerDeleteContactV4Raw(requestParameters: V4ContactsControllerDeleteContactV4Request, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<V4ContactsDeleteContactResponseDto>>; /** * # 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 */ v4ContactsControllerDeleteContactV4(requestParameters: V4ContactsControllerDeleteContactV4Request, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<V4ContactsDeleteContactResponseDto>; /** * # 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 * @summary Get specific columns of a contact by contactId * @param {string} columns Comma-separated list of column names to retrieve * @param {number} contactId The unique identifier of the contact * @param {*} [options] Override http request option. * @throws {RequiredError} * @memberof ContactsAPIV4ApiInterface */ v4ContactsControllerGetContactColumnsV4Raw(requestParameters: V4ContactsControllerGetContactColumnsV4Request, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<V4ContactsGetContactColumnsResponseDto>>; /** * # 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 */ v4ContactsControllerGetContactColumnsV4(requestParameters: V4ContactsControllerGetContactColumnsV4Request, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<V4ContactsGetContactColumnsResponseDto>; /** * # 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 * @summary Get a specific contact by contactId * @param {number} contactId The unique identifier of the contact * @param {number} [viewId] The ID of the view to use for retrieving the repository * @param {*} [options] Override http request option. * @throws {RequiredError} * @memberof ContactsAPIV4ApiInterface */ v4ContactsControllerGetContactV4Raw(requestParameters: V4ContactsControllerGetContactV4Request, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<V4ContactsGetContactResponseDto>>; /** * # 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 */ v4ContactsControllerGetContactV4(requestParameters: V4ContactsControllerGetContactV4Request, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<V4ContactsGetContactResponseDto>; /** * # 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 * @summary Get contacts filtered by a specific column and value * @param {string} column The name of the column to filter by * @param {string} value The value to filter by * @param {number} [viewId] The ID of the view to use for retrieving the repository * @param {string} [columns] The columns to select from the object * @param {number} [limit] The maximum number of objects to return * @param {number} [offset] The offset for pagination, used to skip a number of objects * @param {boolean} [countOnly] Whether to return only the count of objects instead of the objects themselves * @param {'contains' | 'does not contain' | 'is' | 'is not' | 'is any of' | 'is none of' | '=' | '!=' | '>' | '<' | '>=' | '<=' | 'contains all of' | 'contains any of' | 'contains none of' | 'is empty' | 'is not empty' | 'is before' | 'is after' | 'is on or before' | 'is on or after' | 'is between'} [filterOperation] Filters to apply to the view - Operation must be one of the following: + For string: contains, does not contain, is, is not, is any of, is none of + For number: =, !=, >, <, >=, <=, is any of, is none of + For array: contains all of, contains any of, contains none of, is empty, is not empty + For boolean: is + For date: is, is not, is before, is after, is on or before, is on or after, is between, is any of, is none of * @param {*} [options] Override http request option. * @throws {RequiredError} * @memberof ContactsAPIV4ApiInterface */ v4ContactsControllerGetContactsFilteredByV4Raw(requestParameters: V4ContactsControllerGetContactsFilteredByV4Request, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<V4ContactsGetContactsFilteredByResponseDto>>; /** * # 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 */ v4ContactsControllerGetContactsFilteredByV4(requestParameters: V4ContactsControllerGetContactsFilteredByV4Request, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<V4ContactsGetContactsFilteredByResponseDto>; /** * # 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 * @summary Get contacts with a specific viewId * @param {number} viewId The unique identifier of the view * @param {number} [limit] The maximum number of objects to return * @param {number} [offset] The offset for pagination, used to skip a number of objects * @param {boolean} [countOnly] Whether to return only the count of objects instead of the objects themselves * @param {*} [options] Override http request option. * @throws {RequiredError} * @memberof ContactsAPIV4ApiInterface */ v4ContactsControllerGetContactsInViewV4Raw(requestParameters: V4ContactsControllerGetContactsInViewV4Request, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<V4ContactsGetContactsInViewResponseDto>>; /** * # 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 */ v4ContactsControllerGetContactsInViewV4(requestParameters: V4ContactsControllerGetContactsInViewV4Request, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<V4ContactsGetContactsInViewResponseDto>; /** * # 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 * @summary Get contacts with optional viewId * @param {number} [viewId] The ID of the view to use for retrieving the repository * @param {number} [limit] The maximum number of objects to return * @param {number} [offset] The offset for pagination, used to skip a number of objects * @param {boolean} [countOnly] Whether to return only the count of objects instead of the objects themselves * @param {*} [options] Override http request option. * @throws {RequiredError} * @memberof ContactsAPIV4ApiInterface */ v4ContactsControllerGetContactsV4Raw(requestParameters: V4ContactsControllerGetContactsV4Request, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<V4ContactsGetContactsResponseDto>>; /** * # 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 */ v4ContactsControllerGetContactsV4(requestParameters: V4ContactsControllerGetContactsV4Request, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<V4ContactsGetContactsResponseDto>; /** * # PATCH /v4/contacts/{contactId} ## Overview Updates an existing contact with the provided information. This endpoint allows partial updates, meaning you only need to include the fields you want to change. ## 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 update | ## Request Body The request body should contain only the fields you want to update. All fields are optional for updates. ### Updateable Fields | Field | Type | Description | |-------|------|-------------| | `email` | string | Primary email address (must be unique) | | `name` | string | Contact\'s full name | | `phonePrimary` | string | Primary phone number | | `phoneSecondary` | string | Secondary phone number | ### Validation Rules - **Email**: Must be a valid email format and unique within the organization (if provided) - **Name**: Must be non-empty string (if provided) - **Phone Numbers**: Must follow valid phone number format (if provided) - **Partial Updates**: Only provided fields will be updated ## Request Example ```json { \"email\": \"updated.email@example.com\", \"phonePrimary\": \"+1987654321\" } ``` ## 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 updated ## Response Structure Returns confirmation that the contact was successfully updated. ## Use Cases This endpoint is ideal for: - **Contact Information Updates**: Modify contact details as information changes - **Data Correction**: Fix incorrect contact information - **Profile Management**: Allow users to update their contact information - **CRM Synchronization**: Sync contact updates from external systems - **Bulk Updates**: Update specific fields across multiple contacts ## Validation and Constraints - **Email Uniqueness**: Updated email addresses must be unique within the organization - **Data Validation**: All provided fields are validated according to their types - **Organization Scoping**: Contacts can only be updated within the user\'s organization - **Partial Updates**: Only specified fields are modified, others remain unchanged ## Error Handling Common validation errors include: - **Contact Not Found**: Contact ID does not exist or belongs to different organization - **Duplicate Email**: Updated email address already exists in the organization - **Invalid Email Format**: Email does not follow valid email format - **Invalid Phone Format**: Phone numbers do not follow expected format * @summary Update a specific contact by contactId * @param {number} contactId The unique identifier of the contact * @param {V4ContactsUpdateContactBodyDto} v4ContactsUpdateContactBodyDto * @param {*} [options] Override http request option. * @throws {RequiredError} * @memberof ContactsAPIV4ApiInterface */ v4ContactsControllerUpdateContactV4Raw(requestParameters: V4ContactsControllerUpdateContactV4Request, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<V4ContactsUpdateContactResponseDto>>; /** * # PATCH /v4/contacts/{contactId} ## Overview Updates an existing contact with the provided information. This endpoint allows partial updates, meaning you only need to include the fields you want to change. ## 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 update | ## Request Body The request body should contain only the fields you want to update. All fields are optional for updates. ### Updateable Fields | Field | Type | Description | |-------|------|-------------| | `email` | string | Primary email address (must