openapi: 3.0.4 info: title: Evolution Foundation - CRM Service - Contacts description: Management of contacts, conversations, inboxes, labels and macros version: 1.1.0 servers: - url: https://api.evoai.app description: Production server - url: http://localhost:3000 description: Development server variables: port: default: '3000' - url: '{customUrl}' description: Custom server variables: customUrl: default: https://your-instance.com description: Enter your server URL paths: /api/v1/contacts: get: operationId: contactList description: Listing all the resolved contacts with pagination (Page size = 15). Resolved contacts are the ones with a value for identifier, email or phone number summary: List Contacts security: - userApiKey: [] parameters: - $ref: '#/components/parameters/contact_sort_param' responses: '200': description: Contacts retrieved successfully content: application/json: schema: type: object properties: success: type: boolean example: true data: type: array items: $ref: '#/components/schemas/extended_contact' description: Array of contacts meta: type: object properties: pagination: type: object properties: page: type: integer description: Current page number example: 1 pageSize: type: integer description: Number of items per page example: 20 total: type: integer description: Total number of contacts example: 336 totalPages: type: integer description: Total number of pages example: 17 hasNextPage: type: boolean description: Whether there is a next page example: true hasPreviousPage: type: boolean nullable: true description: Whether there is a previous page example: null timestamp: type: string format: date-time description: Response timestamp example: '2026-01-29T17:22:49Z' message: type: string description: Success message example: Contacts retrieved successfully example: success: true data: - id: 550e8400-e29b-41d4-a716-446655440000 name: John Doe email: null phone_number: '+5574999999999' identifier: null blocked: false type: person tax_id: null website: null industry: null additional_attributes: city: '' country: '' location: city: '' country: '' country_code: '' description: '' company_name: '' country_code: '' social_profiles: github: '' twitter: '' facebook: '' linkedin: '' instagram: '' custom_attributes: {} created_at: 1704067200 last_activity_at: null labels: [] contact_inboxes: [] - id: 660e8400-e29b-41d4-a716-446655440001 name: Jane Smith email: jane.smith@example.com phone_number: null identifier: null blocked: false type: person tax_id: null website: null industry: null additional_attributes: source_id: email:example-source-id-123 custom_attributes: {} created_at: 1704153600 last_activity_at: 1704153700 labels: [] contact_inboxes: - source_id: jane.smith@example.com inbox: id: 770e8400-e29b-41d4-a716-446655440002 name: support-inbox channel_type: Channel::Email meta: pagination: page: 1 pageSize: 20 total: 100 totalPages: 5 hasNextPage: true hasPreviousPage: null timestamp: '2024-01-15T10:30:00Z' message: Contacts retrieved successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts method: GET '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts method: GET '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Access forbidden value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts method: GET '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: not_found: summary: Resource not found value: success: false error: code: NOT_FOUND message: Resource not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts method: GET '500': description: Internal Server Error (internal server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: Internal server error meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts method: GET post: operationId: contactCreate description: Create a new Contact summary: Create Contact security: - userApiKey: [] parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/contact_create_payload' example: name: Maria Santos identifier: maria-external-123 email: maria@empresa.com.br phone_number: '+5521987654321' type: person blocked: false tax_id: '12345678901' website: https://empresa.com.br industry: Technology avatar_url: https://example.com/avatar.jpg additional_attributes: company: Tech Solutions Ltda city: São Paulo country: Brazil country_code: BR description: Lead from website campaign social_profiles: linkedin: mariasantos instagram: maria.santos custom_attributes: lead_source: website interest: premium_plan labels: - lead - premium company_ids: - 550e8400-e29b-41d4-a716-446655440000 inbox_id: 550e8400-e29b-41d4-a716-446655440001 source_id: '+5521987654321' responses: '200': description: Contact created successfully content: application/json: schema: $ref: '#/components/schemas/contact_create_response' example: success: true data: contact: id: 3b49511b-c35c-429c-85c3-a83feb87cbef name: Maria Santos email: maria@empresa.com.br phone_number: '+5521987654321' identifier: maria-external-123 blocked: false type: person tax_id: '12345678901' website: https://empresa.com.br industry: Technology additional_attributes: city: São Paulo company: Tech Solutions Ltda country: Brazil country_code: BR description: Lead from website campaign social_profiles: github: '' twitter: '' facebook: '' linkedin: mariasantos instagram: maria.santos custom_attributes: lead_source: website interest: premium_plan created_at: 1765200698 last_activity_at: null labels: - id: 550e8400-e29b-41d4-a716-446655440002 title: lead color: '#4CAF50' - id: 550e8400-e29b-41d4-a716-446655440003 title: premium color: '#2196F3' contact_inboxes: - source_id: '+5521987654321' inbox: id: 550e8400-e29b-41d4-a716-446655440001 name: WhatsApp Business channel_type: whatsapp companies: - id: 550e8400-e29b-41d4-a716-446655440000 name: Tech Solutions Ltda type: company contact_inbox: inbox: id: 550e8400-e29b-41d4-a716-446655440001 name: WhatsApp Business channel_type: whatsapp source_id: '+5521987654321' message: Contact created successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts method: POST '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts method: POST '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Access forbidden value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts method: POST '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: not_found: summary: Resource not found value: success: false error: code: NOT_FOUND message: Resource not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts method: POST '500': description: Internal Server Error (internal server error) content: application/json: schema: $ref: '#/components/schemas/bad_request_error' example: success: false error: Bad Request message: Validation failed details: name: - can't be blank /api/v1/contacts/bulk_transfer: post: operationId: bulkTransferContacts summary: Bulk Transfer Contacts description: Transfer multiple contacts to different account or assignee security: - userApiKey: [] requestBody: required: true content: application/json: schema: type: object required: - contact_ids properties: contact_ids: type: array items: type: integer description: Array of contact IDs to transfer example: - 1 - 2 - 3 assignee_id: type: string format: uuid description: ID of new assignee example: 111e2222-e33b-44d5-a666-777888999000 responses: '200': description: Contacts transferred successfully content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object nullable: true description: Transfer operation result (null for bulk operations) example: null meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Contacts transferred successfully example: success: true data: null meta: timestamp: '2024-01-15T10:30:00Z' message: Contacts transferred successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/bulk_transfer method: POST '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/bulk_transfer method: POST '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Access forbidden value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/bulk_transfer method: POST '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: contacts_not_found: summary: Contacts not found value: success: false error: code: NOT_FOUND message: One or more contacts not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/bulk_transfer method: POST '422': description: Unprocessable Entity (validation errors) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_failed: summary: Validation failed value: success: false error: code: VALIDATION_ERROR message: Validation failed details: contact_ids: Contact IDs array is required assignee_id: Assignee ID must be a valid UUID meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/bulk_transfer method: POST '500': description: Internal Server Error (internal server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: Internal server error meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/bulk_transfer method: POST /api/v1/contacts/filter: parameters: [] post: operationId: contactFilter description: Filter contacts with custom filter options and pagination summary: Contact Filter security: - userApiKey: [] parameters: - name: page in: query schema: type: number requestBody: required: true content: application/json: schema: type: object properties: payload: type: array items: type: object properties: attribute_key: type: string description: filter attribute name filter_operator: type: string description: filter operator name enum: - equal_to - not_equal_to - contains - does_not_contain values: type: array items: type: string description: array of the attribute values to filter query_operator: type: string description: query operator name enum: - AND - OR example: - attribute_key: name filter_operator: equal_to values: - en query_operator: AND - attribute_key: country_code filter_operator: equal_to values: - us query_operator: null responses: '200': description: Contacts retrieved successfully content: application/json: schema: type: object properties: success: type: boolean example: true data: type: array items: $ref: '#/components/schemas/extended_contact' description: Array of contacts meta: type: object properties: pagination: type: object properties: page: type: integer description: Current page number example: 1 pageSize: type: integer description: Number of items per page example: 15 total: type: integer description: Total number of contacts example: 50 totalPages: type: integer description: Total number of pages example: 4 hasNextPage: type: boolean description: Whether there is a next page example: true hasPreviousPage: type: boolean nullable: true description: Whether there is a previous page example: null timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Contacts retrieved successfully example: success: true data: - id: 550e8400-e29b-41d4-a716-446655440000 name: John Doe email: john@example.com phone_number: '+5574999999999' identifier: john-doe-123 account_id: 123e4567-e89b-12d3-a456-426614174000 custom_attributes: {} created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' meta: pagination: page: 1 pageSize: 15 total: 50 totalPages: 4 hasNextPage: true hasPreviousPage: null timestamp: '2024-01-15T10:30:00Z' message: Contacts retrieved successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/filter method: POST '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/filter method: POST '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Access forbidden value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/filter method: POST '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: not_found: summary: No contacts found value: success: false error: code: NOT_FOUND message: No contacts found matching the filter criteria meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/filter method: POST '500': description: Internal Server Error (internal server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: Internal server error meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/filter method: POST /api/v1/contacts/search: parameters: [] get: operationId: contactSearch description: Search the resolved contacts using a search key, currently supports email search (Page size = 15). Resolved contacts are the ones with a value for identifier, email or phone number summary: Search Contacts security: - userApiKey: [] parameters: - name: q in: query schema: type: string description: Search using contact `name`, `identifier`, `email` or `phone number` - $ref: '#/components/parameters/contact_sort_param' responses: '200': description: Contacts retrieved successfully content: application/json: schema: type: object properties: success: type: boolean example: true data: type: array items: $ref: '#/components/schemas/extended_contact' description: Array of contacts meta: type: object properties: pagination: type: object properties: page: type: integer description: Current page number example: 1 pageSize: type: integer description: Number of items per page example: 15 total: type: integer description: Total number of contacts example: 50 totalPages: type: integer description: Total number of pages example: 4 hasNextPage: type: boolean description: Whether there is a next page example: true hasPreviousPage: type: boolean nullable: true description: Whether there is a previous page example: null timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Contacts retrieved successfully example: success: true data: - id: 550e8400-e29b-41d4-a716-446655440000 name: John Doe email: john@example.com phone_number: '+5574999999999' identifier: john-doe-123 account_id: 123e4567-e89b-12d3-a456-426614174000 custom_attributes: {} created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' meta: pagination: page: 1 pageSize: 15 total: 50 totalPages: 4 hasNextPage: true hasPreviousPage: null timestamp: '2024-01-15T10:30:00Z' message: Contacts retrieved successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/search method: GET '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/search method: GET '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Access forbidden value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/search method: GET '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: not_found: summary: No contacts found value: success: false error: code: NOT_FOUND message: No contacts found matching the search criteria meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/search method: GET '500': description: Internal Server Error (internal server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: Internal server error meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/search method: GET /api/v1/contacts/{contact_id}/notes/{id}: parameters: - name: contact_id in: path required: true schema: type: string format: uuid description: ID of the contact - name: id in: path required: true schema: type: string format: uuid description: ID of the note patch: operationId: updateContactNote summary: Update Contact Note description: Updates an existing contact note security: - userApiKey: [] requestBody: required: true content: application/json: schema: type: object required: - content properties: content: type: string description: Updated note content responses: '200': description: Contact note updated successfully content: application/json: schema: type: object required: - success - data - meta - message properties: success: type: boolean example: true data: type: object description: Updated note data properties: id: type: string format: uuid content: type: string user_id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Contact note updated successfully example: success: true data: id: 550e8400-e29b-41d4-a716-446655440000 content: Updated note content - follow up scheduled user_id: 660e8400-e29b-41d4-a716-446655440001 created_at: '2024-01-15T10:00:00Z' updated_at: '2024-01-15T10:30:00Z' meta: timestamp: '2024-01-15T10:30:00Z' message: Contact note updated successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{contact_id}/notes/{id} method: PATCH '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{contact_id}/notes/{id} method: PATCH '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Insufficient permissions value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{contact_id}/notes/{id} method: PATCH '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: note_not_found: summary: Contact or note not found value: success: false error: code: NOT_FOUND message: Contact or note not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{contact_id}/notes/{id} method: PATCH '422': description: Unprocessable Entity (validation error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Validation failed value: success: false error: code: VALIDATION_ERROR message: Validation failed details: content: - Content is required meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{contact_id}/notes/{id} method: PATCH '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: An internal server error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{contact_id}/notes/{id} method: PATCH delete: operationId: deleteContactNote summary: Delete Contact Note description: Deletes a contact note security: - userApiKey: [] responses: '200': description: Contact note deleted successfully content: application/json: schema: type: object required: - success - data - meta - message properties: success: type: boolean example: true data: type: object nullable: true description: Deleted note data (null for delete operations) example: null meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Contact note deleted successfully example: success: true data: null meta: timestamp: '2024-01-15T10:30:00Z' message: Contact note deleted successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{contact_id}/notes/{id} method: DELETE '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{contact_id}/notes/{id} method: DELETE '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Insufficient permissions value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{contact_id}/notes/{id} method: DELETE '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: note_not_found: summary: Contact or note not found value: success: false error: code: NOT_FOUND message: Contact or note not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{contact_id}/notes/{id} method: DELETE '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: An internal server error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{contact_id}/notes/{id} method: DELETE /api/v1/contacts/{id}: parameters: - name: id in: path required: true schema: type: string format: uuid description: ID of the contact get: operationId: contactDetails summary: Show Contact security: - userApiKey: [] description: Get a contact belonging to the account using ID responses: '200': description: Contact retrieved successfully content: application/json: schema: type: object properties: success: type: boolean example: true data: $ref: '#/components/schemas/extended_contact' meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Contact retrieved successfully example: success: true data: id: 550e8400-e29b-41d4-a716-446655440000 name: John Doe email: john@example.com phone_number: '+5574999999999' identifier: john-doe-123 account_id: 123e4567-e89b-12d3-a456-426614174000 custom_attributes: {} created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' meta: timestamp: '2024-01-15T10:30:00Z' message: Contact retrieved successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id} method: GET '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id} method: GET '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Access forbidden value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id} method: GET '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: contact_not_found: summary: Contact not found value: success: false error: code: NOT_FOUND message: Contact not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id} method: GET '500': description: Internal Server Error (internal server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: Internal server error meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id} method: GET put: operationId: contactUpdate summary: Update Contact security: - userApiKey: [] description: Update a contact belonging to the account using ID requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/contact_update_payload' responses: '200': description: Contact updated successfully content: application/json: schema: type: object properties: success: type: boolean example: true data: $ref: '#/components/schemas/extended_contact' meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Contact updated successfully example: success: true data: id: 550e8400-e29b-41d4-a716-446655440000 name: John Doe Updated email: john.updated@example.com phone_number: '+5574999999999' identifier: john-doe-123 account_id: 123e4567-e89b-12d3-a456-426614174000 custom_attributes: {} created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T11:00:00Z' meta: timestamp: '2024-01-15T11:00:00Z' message: Contact updated successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id} method: PUT '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id} method: PUT '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Access forbidden value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id} method: PUT '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: contact_not_found: summary: Contact not found value: success: false error: code: NOT_FOUND message: Contact not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id} method: PUT '500': description: Internal Server Error (internal server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: Internal server error meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id} method: PUT delete: operationId: contactDelete summary: Delete Contact security: - userApiKey: [] description: Delete a contact belonging to the account using ID responses: '200': description: Contact deleted successfully content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object nullable: true description: Deleted contact data (null for delete operations) example: null meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Contact deleted successfully example: success: true data: null meta: timestamp: '2024-01-15T10:30:00Z' message: Contact deleted successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id} method: DELETE '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id} method: DELETE '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Access forbidden value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id} method: DELETE '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: contact_not_found: summary: Contact not found value: success: false error: code: NOT_FOUND message: Contact not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id} method: DELETE '500': description: Internal Server Error (internal server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: Internal server error meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id} method: DELETE /api/v1/contacts/{id}/avatar: delete: operationId: deleteContactAvatar summary: Delete Contact Avatar description: Removes the avatar image from a contact security: - userApiKey: [] parameters: - name: id in: path required: true schema: type: string format: uuid description: ID of the contact responses: '200': description: Avatar deleted successfully content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object nullable: true description: Updated contact data (null for delete operations) example: null meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Avatar deleted successfully example: success: true data: null meta: timestamp: '2024-01-15T10:30:00Z' message: Avatar deleted successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/avatar method: DELETE '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/avatar method: DELETE '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Access forbidden value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/avatar method: DELETE '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: contact_not_found: summary: Contact not found value: success: false error: code: NOT_FOUND message: Contact not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/avatar method: DELETE '500': description: Internal Server Error (internal server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: Internal server error meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/avatar method: DELETE /api/v1/contacts/{id}/contact_inboxes: parameters: [] post: operationId: contactInboxCreation description: Create a contact inbox record for an inbox summary: Create contact inbox parameters: - name: id in: path schema: type: string format: uuid description: ID of the contact required: true security: - userApiKey: [] requestBody: required: true content: application/json: schema: type: object required: - inbox_id properties: inbox_id: type: string format: uuid description: The ID of the inbox example: 222e3333-e44b-55d6-a777-888999000111 source_id: type: string description: Contact Inbox Source Id responses: '200': description: Contact inbox created successfully content: application/json: schema: type: object properties: success: type: boolean example: true data: $ref: '#/components/schemas/contact_inboxes' meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Contact inbox created successfully example: success: true data: id: 550e8400-e29b-41d4-a716-446655440000 contact_id: 660e8400-e29b-41d4-a716-446655440001 inbox_id: 770e8400-e29b-41d4-a716-446655440002 source_id: example-source-id-123 created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' meta: timestamp: '2024-01-15T10:30:00Z' message: Contact inbox created successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/contact_inboxes method: POST '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/contact_inboxes method: POST '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Access forbidden value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/contact_inboxes method: POST '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: contact_not_found: summary: Contact or inbox not found value: success: false error: code: NOT_FOUND message: Contact or inbox not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/contact_inboxes method: POST '422': description: Unprocessable Entity (validation errors) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_failed: summary: Validation failed value: success: false error: code: VALIDATION_ERROR message: Validation failed details: inbox_id: Inbox ID is required meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/contact_inboxes method: POST '500': description: Internal Server Error (internal server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: Internal server error meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/contact_inboxes method: POST /api/v1/contacts/{id}/contactable_inboxes: parameters: [] get: operationId: contactableInboxesGet description: Get List of contactable Inboxes summary: Get Contactable Inboxes security: - userApiKey: [] parameters: - name: id in: path schema: type: string format: uuid description: ID of the contact required: true responses: '200': description: Contactable inboxes retrieved successfully content: application/json: schema: type: object properties: success: type: boolean example: true data: type: array description: Array of contactable inboxes items: $ref: '#/components/schemas/inbox' meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Contactable inboxes retrieved successfully example: success: true data: - id: 550e8400-e29b-41d4-a716-446655440000 name: Support Inbox channel_type: website created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' meta: timestamp: '2024-01-15T10:30:00Z' message: Contactable inboxes retrieved successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/contactable_inboxes method: GET '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/contactable_inboxes method: GET '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Access forbidden value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/contactable_inboxes method: GET '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: contact_not_found: summary: Contact not found value: success: false error: code: NOT_FOUND message: Contact not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/contactable_inboxes method: GET '500': description: Internal Server Error (internal server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: Internal server error meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/contactable_inboxes method: GET /api/v1/contacts/{id}/conversations: parameters: - name: id in: path required: true schema: type: string format: uuid description: ID of the contact get: operationId: contactConversations summary: Contact Conversations description: Get conversations associated with that contact parameters: - name: id in: path required: true schema: type: string format: uuid description: ID of the contact security: - userApiKey: [] responses: '200': description: Conversations retrieved successfully content: application/json: schema: type: object properties: success: type: boolean example: true data: type: array description: Array of conversations items: $ref: '#/components/schemas/conversation' meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Conversations retrieved successfully example: success: true data: - id: 550e8400-e29b-41d4-a716-446655440000 display_id: 550e8400-e29b-41d4-a716-446655440000 status: open created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' meta: timestamp: '2024-01-15T10:30:00Z' message: Conversations retrieved successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/conversations method: GET '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/conversations method: GET '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Access forbidden value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/conversations method: GET '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: contact_not_found: summary: Contact not found value: success: false error: code: NOT_FOUND message: Contact not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/conversations method: GET '500': description: Internal Server Error (internal server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: Internal server error meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/conversations method: GET /api/v1/contacts/{id}/notes: parameters: - name: id in: path required: true schema: type: string format: uuid description: ID of the contact get: operationId: listContactNotes summary: List Contact Notes description: Returns all notes for a contact security: - userApiKey: [] responses: '200': description: Contact notes retrieved successfully content: application/json: schema: type: object required: - success - data - meta - message properties: success: type: boolean example: true data: type: array description: List of notes for the contact items: type: object properties: id: type: string format: uuid content: type: string user_id: type: string format: uuid created_at: type: string format: date-time meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Contact notes retrieved successfully example: success: true data: - id: 550e8400-e29b-41d4-a716-446655440000 content: Follow up with customer next week user_id: 660e8400-e29b-41d4-a716-446655440001 created_at: '2024-01-15T10:30:00Z' - id: 550e8400-e29b-41d4-a716-446655440002 content: Customer interested in premium plan user_id: 660e8400-e29b-41d4-a716-446655440001 created_at: '2024-01-14T09:15:00Z' meta: timestamp: '2024-01-15T10:30:00Z' message: Contact notes retrieved successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/notes method: GET '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/notes method: GET '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Insufficient permissions value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/notes method: GET '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: contact_not_found: summary: Contact not found value: success: false error: code: NOT_FOUND message: Contact not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/notes method: GET '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: An internal server error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/notes method: GET post: operationId: createContactNote summary: Create Contact Note description: Creates a new note for the contact security: - userApiKey: [] requestBody: required: true content: application/json: schema: type: object required: - content properties: content: type: string description: Note content example: Follow up with customer next week responses: '200': description: Contact note created successfully content: application/json: schema: type: object required: - success - data - meta - message properties: success: type: boolean example: true data: type: object description: Created note data properties: id: type: string format: uuid content: type: string user_id: type: string format: uuid created_at: type: string format: date-time meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Contact note created successfully example: success: true data: id: 550e8400-e29b-41d4-a716-446655440000 content: Follow up with customer next week user_id: 660e8400-e29b-41d4-a716-446655440001 created_at: '2024-01-15T10:30:00Z' meta: timestamp: '2024-01-15T10:30:00Z' message: Contact note created successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/notes method: POST '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/notes method: POST '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Insufficient permissions value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/notes method: POST '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: contact_not_found: summary: Contact not found value: success: false error: code: NOT_FOUND message: Contact not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/notes method: POST '422': description: Unprocessable Entity (validation error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Validation failed value: success: false error: code: VALIDATION_ERROR message: Validation failed details: content: - Content is required meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/notes method: POST '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: An internal server error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/notes method: POST /api/v1/contacts/{id}/pipelines: get: operationId: getContactPipelines summary: Get Contact Pipelines description: Returns all pipeline items (deals) associated with the contact security: - userApiKey: [] parameters: - name: id in: path required: true schema: type: string format: uuid description: ID of the contact responses: '200': description: Contact pipelines retrieved successfully content: application/json: schema: type: object required: - success - data - meta - message properties: success: type: boolean example: true data: type: array description: List of pipeline items (deals) associated with the contact items: type: object properties: id: type: string format: uuid name: type: string pipeline_id: type: string format: uuid pipeline_stage_id: type: string format: uuid amount: type: number status: type: string meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Contact pipelines retrieved successfully example: success: true data: - id: 550e8400-e29b-41d4-a716-446655440000 name: Deal Example 1 pipeline_id: 660e8400-e29b-41d4-a716-446655440001 pipeline_stage_id: 770e8400-e29b-41d4-a716-446655440002 amount: 5000.0 status: open - id: 550e8400-e29b-41d4-a716-446655440003 name: Deal Example 2 pipeline_id: 660e8400-e29b-41d4-a716-446655440001 pipeline_stage_id: 770e8400-e29b-41d4-a716-446655440004 amount: 3000.0 status: won meta: timestamp: '2024-01-15T10:30:00Z' message: Contact pipelines retrieved successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/pipelines method: GET '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/pipelines method: GET '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Insufficient permissions value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/pipelines method: GET '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: contact_not_found: summary: Contact not found value: success: false error: code: NOT_FOUND message: Contact not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/pipelines method: GET '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: An internal server error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/contacts/{id}/pipelines method: GET components: schemas: ErrorResponse: type: object required: - success - error - meta properties: success: type: boolean example: false error: type: object required: - code - message properties: code: type: string example: VALIDATION_ERROR message: type: string example: Validation failed details: type: object additionalProperties: true nullable: true meta: type: object required: - timestamp - path - method properties: timestamp: type: string format: date-time example: '2024-01-15T10:30:00Z' path: type: string example: /public/api/v1/inboxes/{inbox_identifier}/contacts method: type: string example: POST bad_request_error: type: object properties: success: type: boolean example: false error: type: string example: Bad Request message: type: string example: Validation failed details: type: object additionalProperties: type: array items: type: string example: name: - can't be blank email: - is invalid contact: type: object properties: id: type: string format: uuid name: type: string email: type: string nullable: true phone_number: type: string nullable: true account_id: type: string format: uuid custom_attributes: type: object created_at: type: string format: date-time updated_at: type: string format: date-time contact_create_payload: type: object required: - name properties: name: type: string description: Name of the contact example: Maria Santos identifier: type: string description: Unique identifier for the contact (e.g., external ID) example: maria-santos-123 email: type: string format: email description: Email address of the contact example: maria@empresa.com.br phone_number: type: string description: Phone number with country code example: '+5521987654321' blocked: type: boolean description: Whether the contact is blocked default: false example: false avatar_url: type: string format: uri description: URL to download and set as contact's avatar example: https://example.com/avatar.jpg type: type: string enum: - person - company default: person description: Type of contact example: person tax_id: type: string description: Tax ID (CPF/CNPJ) example: '12345678901' website: type: string format: uri description: Contact's website URL example: https://empresa.com.br industry: type: string description: Industry/sector of the contact or company example: Technology additional_attributes: type: object description: Additional attributes for the contact additionalProperties: true example: company: Tech Solutions Ltda city: São Paulo country: Brazil country_code: BR description: Lead from website social_profiles: linkedin: mariasantos instagram: maria.santos custom_attributes: type: object description: Custom attributes as key-value pairs additionalProperties: true example: lead_source: website interest: premium_plan labels: type: array description: Labels to assign to the contact items: type: string example: - lead - premium company_ids: type: array description: Array of company IDs to associate with this contact (only for person type) items: type: string format: uuid example: - 550e8400-e29b-41d4-a716-446655440000 inbox_id: type: string format: uuid description: Inbox ID to create a contact_inbox association example: 550e8400-e29b-41d4-a716-446655440001 source_id: type: string description: Source ID for the contact_inbox (e.g., WhatsApp number, email address) example: '+5521987654321' contact_create_response: type: object required: - success - data - message properties: success: type: boolean example: true data: type: object required: - contact properties: contact: allOf: - $ref: '#/components/schemas/contact_full' - type: object properties: companies: type: array description: Companies associated with this contact items: type: object properties: id: type: string format: uuid name: type: string type: type: string enum: - company contact_inbox: type: object nullable: true description: Contact inbox created (if inbox_id was provided) properties: inbox: type: object properties: id: type: string format: uuid name: type: string channel_type: type: string source_id: type: string description: Source ID for the contact in this inbox message: type: string example: Contact created successfully contact_full: type: object properties: id: type: string format: uuid example: 3b49511b-c35c-429c-85c3-a83feb87cbef name: type: string example: Maria Santos email: type: string nullable: true example: maria@empresa.com.br phone_number: type: string nullable: true example: '+5521987654321' identifier: type: string nullable: true example: DavidsonGomes blocked: type: boolean example: false type: type: string enum: - person - company example: person tax_id: type: string nullable: true website: type: string nullable: true industry: type: string nullable: true additional_attributes: type: object properties: city: type: string company: type: string example: Tech Solutions Ltda country: type: string location: type: object properties: city: type: string country: type: string country_code: type: string description: type: string company_name: type: string country_code: type: string language_code: type: string example: pt-br username: type: string social_profiles: type: object properties: github: type: string twitter: type: string facebook: type: string linkedin: type: string instagram: type: string social_telegram_user_id: type: integer social_telegram_user_name: type: string custom_attributes: type: object additionalProperties: true created_at: type: integer description: Unix timestamp example: 1765200698 last_activity_at: type: integer nullable: true description: Unix timestamp of last activity example: 1768597854 labels: type: array items: type: object properties: id: type: string format: uuid title: type: string color: type: string contact_inboxes: type: array items: type: object properties: source_id: type: string inbox: type: object properties: id: type: string format: uuid name: type: string channel_type: type: string conversation: type: object properties: id: type: string format: uuid display_id: type: string format: uuid status: type: string enum: - open - resolved - pending - snoozed contact_id: type: string format: uuid inbox_id: type: string format: uuid assignee_id: type: string format: uuid nullable: true team_id: type: string format: uuid nullable: true account_id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time last_activity_at: type: string format: date-time contact: $ref: '#/components/schemas/contact' assignee: $ref: '#/components/schemas/user' nullable: true inbox: type: object properties: id: type: string format: uuid channel_id: type: string format: uuid name: type: string channel_type: type: string enable_auto_assignment: type: boolean greeting_enabled: type: boolean greeting_message: type: string nullable: true working_hours_enabled: type: boolean out_of_office_message: type: string nullable: true timezone: type: string enable_email_collect: type: boolean csat_survey_enabled: type: boolean allow_messages_after_resolved: type: boolean auto_assignment_config: type: object additionalProperties: true lock_to_single_conversation: type: boolean csat_config: type: object additionalProperties: true sender_name_type: type: string business_name: type: string nullable: true display_name: type: string default_conversation_status: type: string nullable: true avatar_url: type: string working_hours: type: array items: type: object properties: day_of_week: type: integer closed_all_day: type: boolean open_hour: type: integer nullable: true open_minutes: type: integer nullable: true close_hour: type: integer nullable: true close_minutes: type: integer nullable: true open_all_day: type: boolean created_at: type: integer updated_at: type: integer provider: type: string extended_contact: allOf: - $ref: '#/components/schemas/contact_full' - type: object description: Extended contact with full details (alias for contact_full) user: type: object properties: id: type: string format: uuid name: type: string email: type: string avatar_url: type: string nullable: true available_name: type: string description: Display name for the user contacts_list_response: type: object required: - success - data - meta properties: success: type: boolean example: true data: type: array items: $ref: '#/components/schemas/contact_full' meta: type: object properties: pagination: type: object properties: page: type: integer example: 1 pageSize: type: integer example: 20 total: type: integer example: 2 totalPages: type: integer example: 1 hasNextPage: type: boolean nullable: true hasPreviousPage: type: boolean nullable: true timestamp: type: string format: date-time example: '2026-01-28T13:00:02Z' message: type: string example: Contacts retrieved successfully securitySchemes: userApiKey: type: apiKey in: header name: api_access_token ApiAccessToken: type: apiKey in: header name: api_access_token description: API access token for user authentication parameters: contact_sort_param: name: sort in: query required: false description: Field for sorting results schema: type: string enum: - name - email - created_at - updated_at example: created_at page: name: page in: query required: false description: Page number for pagination schema: type: integer minimum: 1 default: 1 example: 1