> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Convenia as a data source
> Bring data from Convenia to Nekt.
Convenia is an HR management platform designed for Brazilian companies. It offers tools for managing employee records, payroll, benefits, vacations, and HR processes, helping organizations streamline their human resources operations with eSocial compliance.
## Configuring Convenia as a Source
In the [Sources](https://app.nekt.ai/sources) tab, click on the "Add source" button located on the top right of your screen. Then, select the Convenia option from the list of connectors.
Click **Next** and you'll be prompted to add your access.
### 1. Add account access
You'll need an API Token to connect to Convenia:
* **API Token**: Your Convenia API access token. You can generate this in your Convenia account settings under the API integrations section.
### 2. Select streams
Choose which data streams you want to sync - you can select all streams or pick specific ones that matter most to you. The available streams include employees, employee details, dismissed employees, vacation solicitations, and salary history.
> Tip: The stream can be found more easily by typing its name.
Select the streams and click **Next**.
### 3. Configure data streams
Customize how you want your data to appear in your catalog. Select a name for each table (which will contain the fetched data) and the type of sync.
* **Table name**: we suggest a name, but feel free to customize it. You have the option to add a **prefix** and make this process faster!
* **Sync Type**: you can choose between INCREMENTAL and FULL\_TABLE.
* Incremental: every time the extraction happens, we'll get only the new data - which is good if, for example, you want to keep every record ever fetched.
* Full table: every time the extraction happens, we'll get the current state of the data - which is good if, for example, you don't want to have deleted data in your catalog.
Once you are done configuring, click **Next**.
### 4. Configure data source
Describe your data source for easy identification within your organization, not exceeding 140 characters.
To define your [Trigger](https://docs.nekt.com/runs/scheduling-and-triggers), consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times).
Optionally, you can determine when to execute a [full sync](https://docs.nekt.com/get-started/core-concepts/types-of-sync#additional-full-sync). This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while.
Once you are ready, click **Next** to finalize the setup.
### 5. Check your new source
You can view your new source on the [Sources](https://app.nekt.ai/sources) page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.
For you to be able to see it on your [Catalog](https://app.nekt.ai/catalog), you need at least one successful source run.
# Streams and Fields
Below you'll find all available data streams from Convenia and their corresponding fields:
Stream containing the main employee list with comprehensive employee data.
**Basic Information:**
* `id` - Unique employee identifier
* `name` - First name
* `last_name` - Last name
* `social_name` - Social/preferred name
* `email` - Corporate email
* `status` - Employee status
* `registration` - Employee registration number
* `hiring_date` - Hiring date
* `birth_date` - Birth date
* `salary` - Current salary
**Documents:**
* `document` - Main documents:
* `cpf` - CPF number
* `pis` - PIS number
* `cpf` - CPF details (`id`, `cpf`)
* `rg` - Identity document:
* `id`, `number`, `emission_date`
* `issuing_agency`, `issuing_state_id`
* `ctps` - Work card (Carteira de Trabalho):
* `id`, `number`, `serial_number`
* `emission_date`, `pis`, `issuing_state_id`
* `driver_license` - Driver's license:
* `id`, `number`, `category`
* `emission_date`, `validate_date`
* `electoral_card` - Voter registration:
* `id`, `number`, `section`
* `electoral_ward`, `state_id`, `city_id`
* `reservist` - Military service:
* `id`, `reservist`, `ra_number`, `series`
**Address:**
* `address` - Employee address:
* `id`, `zip_code`, `address`, `number`
* `complement`, `district`, `state`, `city`
**Organization:**
* `department` - Department (`id`, `name`)
* `cost_center` - Cost center (`id`, `name`)
* `job` - Job position (`id`, `name`)
* `supervisor` - Direct supervisor (`id`, `name`, `last_name`)
**Contact Information:**
* `contact_information` - Contact details:
* `id`, `residential_phone`, `personal_phone`, `personal_email`
**Bank Accounts:**
* `bank_accounts` - Array of bank accounts:
* `id`, `bank`, `account_type`
* `account`, `agency`, `digit`
* `pix`, `modality`
**Emergency Contacts:**
* `emergency_contacts` - Array of emergency contacts:
* `id`, `name`, `phone`, `email`
* `cellphone`, `work_phone`
* `emergency_contact_relation`
**Internship (if applicable):**
* `intern` - Internship information:
* `id`, `initial_at`, `finish_at`
* `internship_category`, `is_mandatory`
* `occupation_area`, `college`, `cnpj`
* Address fields
* `internship_supervisor` - Supervisor info
**Education:**
* `educations` - Array of education records:
* `id`, `course`, `institution`
* `graduation_year`, `education_type`
**Nationalities:**
* `nationalities` - Array of nationalities:
* `id`, `nationality`
**Foreign Employee:**
* `foreign` - Foreign employee information:
* `id`, `arrival_date`, `naturalization_date`
* `married_to_brazilian`, `has_brazilian_offspring`
* `visa`, `country`
**Disability:**
* `disability` - Disability information:
* `id`, `observations`, `disability_type`
**Experience Period:**
* `experience_period` - Trial period info:
* `id`, `first_end`, `second_end`
* `total_days`, `experience_period_type`
**Health Exams (ASO):**
* `aso` - Array of occupational health exams:
* `id`, `status`, `exam_date`
* `observation`, `aso_motive`
**Annotations:**
* `annotations` - Array of employee annotations:
* `id`, `title`, `notes`, `date`
Stream with extended employee information (child of Employees stream).
**Additional Personal Information:**
* `mother_name` - Mother's name
* `father_name` - Father's name
* `gender` - Gender
* `gender_identity_id` - Gender identity ID
* `gender_identity` - Gender identity (`id`, `name`)
* `ethnicity_id` - Ethnicity ID
* `ethnicity` - Ethnicity (`id`, `name`)
* `marital_status_id` - Marital status ID
* `natural_from_state_uf` - Birth state
* `natural_from_city_name` - Birth city
* `first_job` - Whether this is their first job
**Contact:**
* `alternative_email` - Alternative email
* `phone` - Phone number
* `cellphone` - Mobile phone
**Employment:**
* `relationship_id` - Employment relationship ID
* `relationship` - Employment relationship (`id`, `name`)
* `salary_type` - Salary type (`id`, `name`)
* `team` - Team assignment (`id`, `name`)
* `time_tracking` - Whether time tracking is enabled
* `work_period` - Work period info:
* `journey` - Journey details (`monthly_hours`)
* `dismissal` - Dismissal info if applicable (`id`, `date`)
**Documents (Extended):**
* `documents` - Consolidated document information:
* `cpf`, `rg`, `rg_expedition`, `rg_emission`, `rg_uf`
* `pis`, `ctps`, `ctps_serial`, `ctps_emission_date`, `ctps_uf`
* `voter_card`, `voter_card_zone`, `voter_card_section`
**Benefits:**
* `benefits` - Array of employee benefits:
* `id`, `benefit_id`, `name`
* `operator`, `type`, `payment_method`
* `employee_value` - Employee contribution
* `company_value` - Company contribution
**Custom Fields:**
* `custom_fields` - Array of custom fields:
* `id`, `custom_field_id`, `name`, `value`
*Plus all fields from the Employees stream.*
Stream containing terminated employees with dismissal details.
**Key Fields:**
* `id` - Employee ID
* `corporate_email` - Corporate email
**Dismissal Information:**
* `dismissal` - Dismissal details:
* `id` - Dismissal record ID
* `date` - Dismissal date
* `dismissal_type_id` - Dismissal type ID
* `type` - Dismissal type (`id`, `title`)
* `termination_notice` - Termination notice details:
* `id`, `date`
* `termination_notice_type_id`
* `termination_notice_type` - Type info (`id`, `name`)
* `dismissal_step_id` - Dismissal step ID
* `dismissal_step` - Dismissal step (`id`, `name`)
* `breaking_contract` - Contract break flag
* `remove_acess_date` - Access removal date
* `accountancy_date` - Accountancy date
* `remove_benefit` - Benefit removal flag
* `motive` - Dismissal motive
* `comments` - Additional comments
* `finished_at` - Dismissal completion date
* `newSupervisorId` - New supervisor ID (for team reassignment)
* `supervisor` - New supervisor (`id`, `name`)
Stream for vacation requests and approvals (child of Employees stream).
**Request Information:**
* `id` - Solicitation ID
* `employee_id` - Employee ID
* `period_id` - Vacation period ID
* `collective_id` - Collective vacation ID (if applicable)
* `justification` - Request justification
* `status` - Request status
**Vacation Details:**
* `starts_at` - Vacation start date
* `finishes_at` - Vacation end date
* `requested_days` - Number of requested days
* `spent_balance` - Balance spent
* `paid_leave` - Paid leave days
* `allowance` - Vacation allowance
* `thirteenth` - Include 13th salary advance
**Approval Workflow:**
* `available_steps` - Available workflow steps:
* `supervisor_approval` - Supervisor approval required
* `hr_approval` - HR approval required
* `accounting` - Accounting step required
* `signature` - Signature required
* `supervisor_approvals` - Array of supervisor approvals:
* `id`, `status`, `supervisor_id`
* `action_date`, `updated_at`, `created_at`
* `hr_approvals` - Array of HR approvals:
* `id`, `status`, `employee_id`
* `action_date`, `updated_at`, `created_at`
* `sent_to_accountant` - Sent to accountant flag
* `accounting_started_at` - Accounting start date
* `hr_approvals_started_at` - HR approval start date
* `supervisor_approvals_started_at` - Supervisor approval start date
* `signature_started_at` - Signature start date
**Documents:**
* `files` - Array of attached files:
* `id`, `name`, `signable`
* `status`, `updated_at`, `created_at`
**Cancellation:**
* `canceled` - Cancellation info:
* `employee_id`, `created_at`, `updated_at`
**Timestamps:**
* `created_at` - Request creation date
* `updated_at` - Last update date
Stream for salary change history (child of Employees stream).
**Key Fields:**
* `id` - Salary history record ID
* `salary` - Salary value
* `description` - Change description
* `is_active` - Whether this is the active salary
* `date_from` - Effective start date
* `date_to` - Effective end date
**Position at Time:**
* `relationship_id` - Employment relationship ID
* `relationship` - Employment relationship (`id`, `name`)
* `department_id` - Department ID
* `department` - Department (`id`, `name`)
* `team_id` - Team ID
* `team` - Team (`id`, `name`)
* `job_description_id` - Job description ID
* `job` - Job position (`id`, `name`)
* `cost_center_id` - Cost center ID
* `cost_center` - Cost center (`id`, `name`)
**Change Reason:**
* `motive_id` - Change motive ID
* `motive` - Change motive (`id`, `name`)
**Timestamps:**
* `created_at` - Record creation date
* `updated_at` - Last update date
## Data Model
The following diagram illustrates the relationships between the Convenia data streams:
```mermaid theme={null}
graph TD;
subgraph "Employee Data"
Employees("Employees");
EmployeeDetails("Employee Details");
DismissedEmployees("Dismissed Employees");
end
subgraph "HR Processes"
VacationsSolicitations("Vacation Solicitations");
SalaryHistory("Salary History");
end
Employees -- "id" --> EmployeeDetails;
Employees -- "id" --> VacationsSolicitations;
Employees -- "id" --> SalaryHistory;
DismissedEmployees -- "id" --> Employees;
```
## Notes
* **Employee Details** is a child stream of **Employees** and provides extended information for each employee
* **Vacation Solicitations** and **Salary History** are also child streams, fetched per employee
* **Dismissed Employees** contains only terminated employees with their dismissal details
* All dates follow Brazilian format conventions
## Skills for agents
Convenia connector documentation as plain markdown, for use in AI agent contexts.