# Retrieve employment metrics Retrieve employment metrics for an individual. > Before requesting employment metrics, make sure to first make a POST Retrieve employment record details request. Endpoint: POST /api/employment-metrics/ Version: 1.222.0 Security: basicAuth ## Query parameters: - `omit` (string) Omit certain fields from being returned in the response. For more information, see our Filtering responses DevPortal article. - `fields` (string) Return only the specified fields in the response. For more information, see our Filtering responses DevPortal article. ## Request fields (application/json): - `link` (string, required) The you want to retrieve information for. Example: "c81a1dea-6dd6-4999-8b9f-541ee8197058" - `reference_date` (string) The date until which you want the employment metrics to be calculated, in format. For example, if you do not want to calculate employment metrics for all of 2023, the add as the . If you do not provide a , we perform calcualtions up until the date you make the request. All calculations will be relative to this date. Example: "2023-03-01" - `save_data` (boolean) Indicates whether or not to persist the data in Belvo. By default, this is set to and we return a 201 Created response. When set to , the data won't be persisted and we return a 200 OK response. Example: true ## Response 200 fields (application/json): - `id` (string, required) Belvo's unique identifier for the current item. Example: "0d3ffb69-f83b-456e-ad8e-208d0998d71d" - `link` (string,null, required) The the data belongs to. Example: "30cb4806-6e00-48a4-91c9-ca55968576c8" - `collected_at` (string, required) The ISO-8601 timestamp when the data point was collected. Example: "2022-02-09T08:45:50.406032Z" - `created_at` (string, required) The ISO-8601 timestamp of when the data point was created in Belvo's database. Example: "2022-02-09T08:45:50.406032Z" - `updated_at` (string,null, required) The ISO-8601 timestamp of when the employment metrics calculation was last updated. Example: "2023-08-30T15:31:35.728607Z" - `reference_date` (string,null, required) The reference_date your provided in your request. If you didn't provide one, this field will return , indicating that the calculations are performed up until the date of the request. All calculations are relative to this date. Example: "2023-06-01" - `age` (integer, required) The age of the individual. Example: 32 - `current_status` (string, required) Indicates the employment status of the individual. We return one of the following responses: - - - - Enum: "EMPLOYED", "RETIRED", "UNEMPLOYED", "null" - `current_employer_count` (integer,null, required) The number of employers the individual has right now. Example: 1 - `base_salary_last` (number,null, required) The user's latest base salary. If is , this is the user's current base salary. Example: 42.17 - `weeks_employed_last_job` (number,null, required) The number of weeks the user was employed in their last job. If is , then this field indicates the number of weeks the user has been employed with his current job. Example: 327.1429 - `weeks_since_last_job` (number,null, required) The number of weeks since their last job. If the value of this field is , this indicates that the user is currently employed. - `weeks_employed_total` (number,null, required) The total number of weeks the user has been employed, according to the institution. > > > In the case that the user is employed at two or more places at the same time, we still calculate those weeks as one week. For example, if a user has three concurrent jobs for a month, this is calculated as 4 weeks. Example: 148.2 - `weeks_with_multiple_employers` (number,null, required) The number of the weeks that the individual has had more than one employer at the same time. - `employer_count` (integer,null, required) The total number of employers the user has had. Useful to indicate employment stability over the course of their lifetime. Example: 14 - `unique_employer_count` (integer,null, required) The number of unique employers that the individual has had. > > > If the user left one company and returned, for example, six months later to the same company, this is counted as one employer. Example: 3 - `employers_per_year` (number,null, required) Number of employers per year. Useful to indicate employment stability over the course of a year. > > > If the user left one company and returned, for example, six months later to the same company, this is counted as one employer. Example: 0.6326 - `weeks_between_jobs` (number,null, required) The total number of weeks the individual was unemployed. Example: 687.2865 - `max_weeks_between_jobs` (number,null, required) The maximum number of weeks that the individual was unemployed. Example: 249.8571 - `increases_last_job` (integer,null, required) The total number of salary increases the user had in their last job. If is , this refers to the user's current job. > > > For all salary increases or decreases, we only take into account those where the change in salary is greater than 2%. - `decreases_last_job` (integer,null, required) The total number of salary increases the user had in their last job. If is , this refers to the user's current job. - `increases_after_change` (integer,null, required) The total number of salary increases between the individual's penultimate job and the last (or current) job. - `decreases_after_change` (integer,null, required) The total number of salary decreases between the individual's penultimate job and the last (or current) job. - `increases_overall` (integer,null, required) The total number of salary increases throughout the individual's working career. - `decreases_overall` (integer,null, required) The total number of salary decreases throughout the individual's working career. - `increases_1y` (integer,null, required) The total number of salary increases throughout the individual's last year (YTD). - `decreases_1y` (integer,null, required) The total number of salary decreases throughout the individual's last year (YTD). - `increases_3y` (integer,null, required) The total number of salary increases throughout the individual's last three years. > > > If the individual's working career is less than three years, we return . - `decreases_3y` (integer,null, required) The total number of salary decreases throughout the individual's last three years. > > > If the individual's working career is less than three years, we return . - `increases_5y` (integer,null, required) The total number of salary increases throughout the individual's last five years. > > > If the individual's working career is less than five years, we return . - `decreases_5y` (integer,null, required) The total number of salary decreases throughout the individual's last five years. > > > If the individual's working career is less than five years, we return . - `yearly_change_1y` (number,null, required) The individual's salary percentage change for the last year (YTD). - `yearly_change_3y` (number,null, required) The individual's salary percentage change for the last three years. > > > If the individual's working career is less than three years, we return . - `yearly_change_5y` (number,null, required) The individual's salary percentage change for the last five years. > > > If the individual's working career is less than five years, we return . - `min_monthly_salary_1y` (number,null, required) The individual's minimum monthly salary for the last year. Example: 3402.88 - `min_monthly_salary_3y` (number,null, required) The individual's minimum monthly salary for the last three years. Example: 3402.88 - `min_monthly_salary_5y` (number,null, required) The individual's minimum monthly salary for the last five years. Example: 3402.88 - `average_monthly_salary_1y` (number,null, required) The individual's average monthly salary for the last year. Example: 3402.88 - `average_monthly_salary_3y` (number,null, required) The individual's average monthly salary for the last three years. Example: 3402.88 - `average_monthly_salary_5y` (number,null, required) The individual's average monthly salary for the last five years. Example: 3402.88 - `max_monthly_salary_1y` (number,null, required) The individual's maximum monthly salary for the last year. Example: 3402.88 - `max_monthly_salary_3y` (number,null, required) The individual's maximum monthly salary for the last three years. Example: 3402.88 - `max_monthly_salary_5y` (number,null, required) The individual's maximum monthly salary for the last five years. Example: 3402.88 ## Response 201 fields (application/json): - `id` (string, required) Belvo's unique identifier for the current item. Example: "0d3ffb69-f83b-456e-ad8e-208d0998d71d" - `link` (string,null, required) The the data belongs to. Example: "30cb4806-6e00-48a4-91c9-ca55968576c8" - `collected_at` (string, required) The ISO-8601 timestamp when the data point was collected. Example: "2022-02-09T08:45:50.406032Z" - `created_at` (string, required) The ISO-8601 timestamp of when the data point was created in Belvo's database. Example: "2022-02-09T08:45:50.406032Z" - `updated_at` (string,null, required) The ISO-8601 timestamp of when the employment metrics calculation was last updated. Example: "2023-08-30T15:31:35.728607Z" - `reference_date` (string,null, required) The reference_date your provided in your request. If you didn't provide one, this field will return , indicating that the calculations are performed up until the date of the request. All calculations are relative to this date. Example: "2023-06-01" - `age` (integer, required) The age of the individual. Example: 32 - `current_status` (string, required) Indicates the employment status of the individual. We return one of the following responses: - - - - Enum: "EMPLOYED", "RETIRED", "UNEMPLOYED", "null" - `current_employer_count` (integer,null, required) The number of employers the individual has right now. Example: 1 - `base_salary_last` (number,null, required) The user's latest base salary. If is , this is the user's current base salary. Example: 42.17 - `weeks_employed_last_job` (number,null, required) The number of weeks the user was employed in their last job. If is , then this field indicates the number of weeks the user has been employed with his current job. Example: 327.1429 - `weeks_since_last_job` (number,null, required) The number of weeks since their last job. If the value of this field is , this indicates that the user is currently employed. - `weeks_employed_total` (number,null, required) The total number of weeks the user has been employed, according to the institution. > > > In the case that the user is employed at two or more places at the same time, we still calculate those weeks as one week. For example, if a user has three concurrent jobs for a month, this is calculated as 4 weeks. Example: 148.2 - `weeks_with_multiple_employers` (number,null, required) The number of the weeks that the individual has had more than one employer at the same time. - `employer_count` (integer,null, required) The total number of employers the user has had. Useful to indicate employment stability over the course of their lifetime. Example: 14 - `unique_employer_count` (integer,null, required) The number of unique employers that the individual has had. > > > If the user left one company and returned, for example, six months later to the same company, this is counted as one employer. Example: 3 - `employers_per_year` (number,null, required) Number of employers per year. Useful to indicate employment stability over the course of a year. > > > If the user left one company and returned, for example, six months later to the same company, this is counted as one employer. Example: 0.6326 - `weeks_between_jobs` (number,null, required) The total number of weeks the individual was unemployed. Example: 687.2865 - `max_weeks_between_jobs` (number,null, required) The maximum number of weeks that the individual was unemployed. Example: 249.8571 - `increases_last_job` (integer,null, required) The total number of salary increases the user had in their last job. If is , this refers to the user's current job. > > > For all salary increases or decreases, we only take into account those where the change in salary is greater than 2%. - `decreases_last_job` (integer,null, required) The total number of salary increases the user had in their last job. If is , this refers to the user's current job. - `increases_after_change` (integer,null, required) The total number of salary increases between the individual's penultimate job and the last (or current) job. - `decreases_after_change` (integer,null, required) The total number of salary decreases between the individual's penultimate job and the last (or current) job. - `increases_overall` (integer,null, required) The total number of salary increases throughout the individual's working career. - `decreases_overall` (integer,null, required) The total number of salary decreases throughout the individual's working career. - `increases_1y` (integer,null, required) The total number of salary increases throughout the individual's last year (YTD). - `decreases_1y` (integer,null, required) The total number of salary decreases throughout the individual's last year (YTD). - `increases_3y` (integer,null, required) The total number of salary increases throughout the individual's last three years. > > > If the individual's working career is less than three years, we return . - `decreases_3y` (integer,null, required) The total number of salary decreases throughout the individual's last three years. > > > If the individual's working career is less than three years, we return . - `increases_5y` (integer,null, required) The total number of salary increases throughout the individual's last five years. > > > If the individual's working career is less than five years, we return . - `decreases_5y` (integer,null, required) The total number of salary decreases throughout the individual's last five years. > > > If the individual's working career is less than five years, we return . - `yearly_change_1y` (number,null, required) The individual's salary percentage change for the last year (YTD). - `yearly_change_3y` (number,null, required) The individual's salary percentage change for the last three years. > > > If the individual's working career is less than three years, we return . - `yearly_change_5y` (number,null, required) The individual's salary percentage change for the last five years. > > > If the individual's working career is less than five years, we return . - `min_monthly_salary_1y` (number,null, required) The individual's minimum monthly salary for the last year. Example: 3402.88 - `min_monthly_salary_3y` (number,null, required) The individual's minimum monthly salary for the last three years. Example: 3402.88 - `min_monthly_salary_5y` (number,null, required) The individual's minimum monthly salary for the last five years. Example: 3402.88 - `average_monthly_salary_1y` (number,null, required) The individual's average monthly salary for the last year. Example: 3402.88 - `average_monthly_salary_3y` (number,null, required) The individual's average monthly salary for the last three years. Example: 3402.88 - `average_monthly_salary_5y` (number,null, required) The individual's average monthly salary for the last five years. Example: 3402.88 - `max_monthly_salary_1y` (number,null, required) The individual's maximum monthly salary for the last year. Example: 3402.88 - `max_monthly_salary_3y` (number,null, required) The individual's maximum monthly salary for the last three years. Example: 3402.88 - `max_monthly_salary_5y` (number,null, required) The individual's maximum monthly salary for the last five years. Example: 3402.88 ## Response 403 fields (application/json): - `code` (string) A unique error code () that allows you to classify and handle the error programmatically. ℹ️ Check our DevPortal for more information on how to handle 403 access_to_resource_denied. Example: "access_to_resource_denied" - `message` (string) A short description of the error. For errors, the description is: - . Example: "You don't have access to this resource." - `request_id` (string) A 32-character unique ID of the request (matching a regex pattern of: ). Provide this ID when contacting the Belvo support team to accelerate investigations. Example: "9e7b283c6efa449c9c028a16b5c249fb" ## Response 404 fields (application/json): - `code` (string) A unique error code () that allows you to classify and handle the error programmatically. Example: "not_found" - `message` (string) A short description of the error. For errors, the description is: - Example: "Not found" - `request_id` (string) A 32-character unique ID of the request (matching a regex pattern of: ). Provide this ID when contacting the Belvo support team to accelerate investigations. Example: "9e7b283c6efa449c9c028a16b5c249fb" ## Response 408 fields (application/json): - `code` (string) A unique error code () that allows you to classify and handle the error programmatically. ℹ️ Check our DevPortal for more information on how to handle 408 request_timeout errors. Example: "request_timeout" - `message` (string) A short description of the error. For errors, the description is: - . Example: "The request timed out, you can retry asking for less data by changing your query parameters" - `request_id` (string) A 32-character unique ID of the request (matching a regex pattern of: ). Provide this ID when contacting the Belvo support team to accelerate investigations. Example: "9e7b283c6efa449c9c028a16b5c249fb" ## Response 500 fields (application/json): - `code` (string) A unique error code () that allows you to classify and handle the error programmatically. ℹ️ Check our DevPortal for more information on how to handle 500 unexpected_error errors. Example: "unexpected_error" - `message` (string) A short description of the error. For errors, the description is: - . Example: "Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution" - `request_id` (string) A 32-character unique ID of the request (matching a regex pattern of: ). Provide this ID when contacting the Belvo support team to accelerate investigations. Example: "9e7b283c6efa449c9c028a16b5c249fb"