> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://www.truework.com/docs/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://www.truework.com/docs/_mcp/server. # Create a Verification POST https://api.truework-sandbox.com/verification-requests Content-Type: application/json Creates a new Verification and return a JSON object representing the newly created Verification. ## Verification Processing ### Controlling Processing with the `Request-Sync` Header Verifications are generally processed *asynchronously*: they will be created and returned in the response body without any [reports](api.yaml/paths/~1verification-requests~1\{verification_id}~1report/get). Truework will then send a webhook when the request has finished processing, and the reports can be retrieved. However, **Instant** verifications (those which are created without a target company) can also be executed *synchronously* by using the `Request-Sync` header. When processing synchronously, Truework will attempt to process the verification during the initial POST request. If successful, the `201` response will include a `reports` key, which will contain the requested data. This header can take one of the following values. If the header is not defined, the request will default to asynchronous execution. | VALUE | DESCRIPTION | | ----- | --------------------------------------- | | sync | The request will execute synchronously | | async | The request will execute asynchronously | It is recommended to set a timeout on synchronous requests, to account for potential latency when calling our partners. Synchronous requests generally take only a few seconds to complete, but in rare cases they may take longer. Synchronous execution is only valid for requests that do not include a target company. Other requests that pass this header will return a `400` response. ### Controlling Processing with Request Parameters Request parameters allow you to configure how you use Truework by selecting only the verification methods and features you need. If the `request_parameters` field is left blank, the default behavior is: * If `target.company` is included: * Enable all verification methods * Set `automated_underwriting_system_eligibility` to `not-required` * Set `employer_filter` to `target-employer` * If `target.company` is omitted: * Only enable Truework Instant * Set `automated_underwriting_system_eligibility` to `not-required` * Set `employer_filter` to `all-employers` or `previous-employers` Reference: https://www.truework.com/docs/api-reference/previous-versions/2022-08-01/create-new-verification ## Authentication - `Authorization` header (bearer token, required) — Bearer tokens conform to the [RFC6750](https://datatracker.ietf.org/doc/html/rfc6750#section-2.1) spec. Production API keys (secret keys) are prefixed with `tw_sk_` and sandbox keys are prefixed with `tw_sk_test_`. If your secret key is published, you should rotate your API keys. Truework.JS publishable keys are prefixed with `tw_pk_` and `tw_pk_test` respectively. **Examples** - For Authorization Headers: `Authorization: Bearer tw_sk_test_e508eb797edb95ade85284bcb54dd49ed45db1be` - For the "try it now" `token` field, input only the token itself, omitting `Bearer `. ## Servers - `https://api.truework-sandbox.com` (Sandbox, default) - `https://api.truework.com` (Production) ## Request ### Query parameters - `fields` (string, optional, nullable) — Comma-separated names of fields to include in the response. If omitted, all fields are included - `income_analytics` (boolean, optional, default: false) — Whether to calculate income analytics for the nested reports in each verification. ### Headers - `Accept` (enum, optional, default: application/json) — Specify the content type and version that the API should use. It's recommended to include this to avoid breaking changes. - Allowed values: `application/json`, `application/json; version=2022-08-01` - `Request-Sync` (enum, optional, default: async) — A header that defines if a request should be executed synchronously. `sync` can only return completed or canceled verification responses, not pending. `async` will return only pending. - Allowed values: `sync`, `async` ### Body (application/json) This endpoint expects a VerificationRequestPostV20220801. - `permissible_purpose` (enum, required) — A valid purpose is required for Truework to process the verification request. Throughout the API, this is signified by the `permissible_purpose` field. | VALUE | DESCRIPTION | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | child-support | Determine child support payments (available to verifiers that represent a state or local child support enforcement agencies) | | credit-application | The target's application for credit | | employee-eligibility | Employee's eligibility for a benefit granted by a governmental agency required by law to consider the employee's financial responsibility or status | | employee-request | The target has issued the verifier written instruction to obtain this information | | employee-review-or-collection | Performing a review or collection of the target's account | | employment | Employment purposes where the target has given prior written consent | | insurance-underwriting-application | Underwriting insurance in response to the target's application | | legitimate-reason-initiated | Legitimate business need for the information in connection with a business transaction initiated by the target | | legitimate-reason-review | Legitimate business need to review the target's account to determine whether the employee continues to meet the terms of the account | | risk-assessment | To assess the credit or prepayment risks associated with an existing credit obligation of the target | | subpoena | For a court order or a federal grand jury subpoena - Allowed values: `child-support`, `credit-application`, `employee-eligibility`, `employee-request`, `employee-review-or-collection`, `employment`, `insurance-underwriting-application`, `legitimate-reason-initiated`, `legitimate-reason-review`, `risk-assessment`, `subpoena` - `target` (SubmissionTargetInputVMinimumVersion, required) — Information on the individual who is being verified - `type` (enum, required) - Allowed values: `employment-income`, `employment`, `tenant-screening`, `assets` - `use_case` (enum, required) — The verification request use case describes the type of product the verification request is originating from. If omitted, the verifier type in account settings will be used as a default | VALUE | DESCRIPTION | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------ | | mortgage | Verification for a mortgage | | home-equity | Verification for home equity | background | Verification for a background check | | tenant | Verification for a rental property | | government | Verification for government/social services | | auto | Verification for auto lending | | lending | Verification for personal loans or consumer lending | | credit | Verification for credit cards | | identity | Verification for identity or fraud | | insurance | Verification for insurance | | health | Verification for health services | | offers | Verification for offers | | account-management | Verification for account management | | preapproval | Verification for preapprovals | - Allowed values: `mortgage`, `home-equity`, `background`, `tenant`, `government`, `auto`, `lending`, `credit`, `identity`, `insurance`, `health`, `offers`, `account-management`, `preapproval` - `additional_information` (string, optional, nullable) — Any additional information about the target that can help expedite the completion of the verification request - `branch_id` (string, optional, nullable) — The branch id associated with the verification request - `documents` (list of _VerificationRequestPostDocument, optional, nullable) — Supporting documentation files provided by the verifier for the verification - `loan_id` (string, optional, nullable) — The loan id associated with the verification request - `metadata` (map from string to string, optional, nullable) — A single level key-value JSON object that can be used to store custom data on the verification request; keys and values must be strings - `request_parameters` (RequestParametersWriteVMinimumVersion, optional, nullable) - `reseller_originating_party` (ResellerOriginatingPartyInputV20220801, optional, nullable) — The originating party that requested the verification via a reseller. `reseller_originating_party` is required for for companies that resell data provided by Truework. ## Response ### 201 Verification Request Created. - `additional_information` (string, required, nullable) — Any additional information about the target that can help expedite the completion of the verification request - `branch_id` (string, required, nullable) — The branch id associated with the verification request. - `cancellation_details` (string, required, nullable) — The details for the cancellation; only present when state is canceled - `cancellation_reason` (enum, required, nullable) — | VALUE | DESCRIPTION | | -------------------- | ---------------------------------------------------------------------------------------------------- | | immediate | Can be used to cancel a request directly after submitting, before Truework has started processing it | | high-turnaround-time | The request is taking longer than expected | | competitor | You preferred a competitor for this request | | wrong-info | The request that is submitted contains information that is wrong | | no-match | No record was located for the given target and request parameters | | other | No other reason in the list fits the cancellation reason | - Allowed values: `immediate`, `high-turnaround-time`, `competitor`, `wrong-info`, `no-match`, `other` - `created` (datetime, required) - `date_of_completion` (datetime, required, nullable) — The date when this verification was completed in ISO 8601 format - `documents` (list of DocumentOutputResourceV20220801, required, nullable) — Supporting documentation files provided by the verifier for the verification - `id` (string, required) - `loan_id` (string, required, nullable) — The loan id associated with the verification request - `metadata` (map from string to string, required, nullable) — A single level key-value JSON object that can be used to store custom data on the verification request; keys and values must be strings - `permissible_purpose` (enum, required) — A valid purpose is required for Truework to process the verification request. Throughout the API, this is signified by the `permissible_purpose` field. | VALUE | DESCRIPTION | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | child-support | Determine child support payments (available to verifiers that represent a state or local child support enforcement agencies) | | credit-application | The target's application for credit | | employee-eligibility | Employee's eligibility for a benefit granted by a governmental agency required by law to consider the employee's financial responsibility or status | | employee-request | The target has issued the verifier written instruction to obtain this information | | employee-review-or-collection | Performing a review or collection of the target's account | | employment | Employment purposes where the target has given prior written consent | | insurance-underwriting-application | Underwriting insurance in response to the target's application | | legitimate-reason-initiated | Legitimate business need for the information in connection with a business transaction initiated by the target | | legitimate-reason-review | Legitimate business need to review the target's account to determine whether the employee continues to meet the terms of the account | | risk-assessment | To assess the credit or prepayment risks associated with an existing credit obligation of the target | | subpoena | For a court order or a federal grand jury subpoena | other | No other value fits the permissible purpose of this verification request | - Allowed values: `child-support`, `credit-application`, `employee-eligibility`, `employee-request`, `employee-review-or-collection`, `employment`, `insurance-underwriting-application`, `legitimate-reason-initiated`, `legitimate-reason-review`, `risk-assessment`, `subpoena`, `other` - `price` (MoneyAmountVMinimumVersion, required) — Currently we only support USD as currency. Currency amounts are represented as strings with two decimal precision, e.g. "34.95". - `reports` (list of VerificationReportResourceV20220801, required, nullable) — Applicable reports belonging to this request, if the request has been completed - `request_parameters` (RequestParametersReadVMinimumVersion, required, nullable) - `reseller_originating_party` (ResellerOriginatingPartyOutputV20220801, required, nullable) — The originating party that requested the verification via a reseller. `reseller_originating_party` is required for for companies that resell data provided by Truework. - `state` (enum, required) — The state helps convey where the verification request is in the Truework process. It will be returned in the JSON objects returned from this endpoint. The initial state of all Schemas is pending-approval, and will switch to processing once Truework begins to process the request. However, it may switch back to pending-approval if it is pending approval by the target. The states completed, canceled, invalid are all terminal states of a Verification. A Report is only available when it is in the completed state. A Verification will enter the state canceled when either Truework or an API user cancels the request. The invalid state indicates that there are issues with the data e.g. we could not locate the employee at a given employer, or could not find the employer itself. | VALUE | DESCRIPTION | | ---------------- | ------------------------------------------------------------------------------------------------------- | | pending-approval | The initial state after creation; the Truework team has not started working on this request yet | | action-required | A user action is required to continue processing this request; visit the dashboard for more information | | invalid | Contains invalid information that prevents the verification request from being processed by Truework | | processing | The Truework team is currently working on the verification request | | completed | The verification request has been completed and a report can be found from the reports endpoint | | canceled | Truework denied processing of the request or the verifier no longer wants the request to be processed | | other | No other value fits the state of this verification request | - Allowed values: `pending-approval`, `action-required`, `invalid`, `processing`, `completed`, `canceled`, `other` - `target` (SubmissionTargetOutputVMinimumVersion, required) - `turnaround_time` (TurnaroundTimeV20220801, required) — We use data from thousands of verification requests to estimate the duration between creation and completion of a request. For a provided company, upper_bound and lower_bound are the time estimates (in hours) that this particular request will take to be fully processed by Truework. May be an empty if an estimate does not exist for the verification request. - `type` (enum, required) - Allowed values: `employment-income`, `employment`, `tenant-screening`, `assets` - `use_case` (enum, required) — The verification request use case describes the type of product the verification request is originating from. If omitted, the verifier type in account settings will be used as a default | VALUE | DESCRIPTION | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------ | | mortgage | Verification for a mortgage | | home-equity | Verification for home equity | background | Verification for a background check | | tenant | Verification for a rental property | | government | Verification for government/social services | | auto | Verification for auto lending | | lending | Verification for personal loans or consumer lending | | credit | Verification for credit cards | | identity | Verification for identity or fraud | | insurance | Verification for insurance | | health | Verification for health services | | offers | Verification for offers | | account-management | Verification for account management | | preapproval | Verification for preapprovals | | other | Verification for other products. This exists for historical compatibility, no new Schemas can be created with this value | - Allowed values: `mortgage`, `home-equity`, `background`, `tenant`, `government`, `auto`, `lending`, `credit`, `identity`, `insurance`, `health`, `offers`, `account-management`, `preapproval`, `other` ## Errors ### 400 Bad Request Error Bad Request - `error` (_InvalidRequestError, required) ### 401 Unauthorized Error The request's authorization is missing, invalid, or expired - `error` (Error, required) ### 403 Forbidden Error Forbidden - `error` (Error, required) ### 406 Not Acceptable Error An invalid API version was requested - `error` (Error, required) ### 429 Too Many Requests Error Too Many Requests - `error` (Error, required) ### 451 Unavailable for Legal Reasons Error Frozen SSN - `error` (Error, required) ### 500 Internal Server Error Internal Server Error - `error` (Error, required) ### 501 Not Implemented Error Not Implemented - `error` (Error, required) ## Types ### SubmissionTargetInputVMinimumVersion - `first_name` (string, required) - `last_name` (string, required) - `social_security_number` (string, required) — The target's social security number - `company` (SubmissionTargetInputVMinimumVersionCompany, optional, nullable) - `contact_email` (string, optional, nullable) - `date_of_birth` (date, optional, nullable) — Target's date of birth in format YYYY-MM-DD. `date_of_birth` is required for employer search/synchronous requests - `phone_number` (string, optional, nullable) ### _VerificationRequestPostDocument Supporting documentation for the verification in PDF format - `content` (string, required) — base64 representation of the PDF file - `filename` (string, required) ### RequestParametersWriteVMinimumVersion - `verification_methods` (_VerificationMethodsWrite, required) - `automated_underwriting_system_eligibility` (enum, optional) — Automated Underwriting System (AUS) eligibility - Allowed values: `not-required` - `employer_filter` (enum, optional) - Allowed values: `target-employer`, `all-employers`, `current-employer`, `previous-employers` ### ResellerOriginatingPartyInputV20220801 - `originating_party` (string, required) - `permissible_purpose` (enum, required) — A valid purpose is required for Truework to process the verification request. Throughout the API, this is signified by the `permissible_purpose` field. | VALUE | DESCRIPTION | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | child-support | Determine child support payments (available to verifiers that represent a state or local child support enforcement agencies) | | credit-application | The target's application for credit | | employee-eligibility | Employee's eligibility for a benefit granted by a governmental agency required by law to consider the employee's financial responsibility or status | | employee-request | The target has issued the verifier written instruction to obtain this information | | employee-review-or-collection | Performing a review or collection of the target's account | | employment | Employment purposes where the target has given prior written consent | | insurance-underwriting-application | Underwriting insurance in response to the target's application | | legitimate-reason-initiated | Legitimate business need for the information in connection with a business transaction initiated by the target | | legitimate-reason-review | Legitimate business need to review the target's account to determine whether the employee continues to meet the terms of the account | | risk-assessment | To assess the credit or prepayment risks associated with an existing credit obligation of the target | | subpoena | For a court order or a federal grand jury subpoena - Allowed values: `child-support`, `credit-application`, `employee-eligibility`, `employee-request`, `employee-review-or-collection`, `employment`, `insurance-underwriting-application`, `legitimate-reason-initiated`, `legitimate-reason-review`, `risk-assessment`, `subpoena` - `use_case` (enum, required) — The verification request use case describes the type of product the verification request is originating from. If omitted, the verifier type in account settings will be used as a default | VALUE | DESCRIPTION | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------ | | mortgage | Verification for a mortgage | | home-equity | Verification for home equity | background | Verification for a background check | | tenant | Verification for a rental property | | government | Verification for government/social services | | auto | Verification for auto lending | | lending | Verification for personal loans or consumer lending | | credit | Verification for credit cards | | identity | Verification for identity or fraud | | insurance | Verification for insurance | | health | Verification for health services | | offers | Verification for offers | | account-management | Verification for account management | | preapproval | Verification for preapprovals | - Allowed values: `mortgage`, `home-equity`, `background`, `tenant`, `government`, `auto`, `lending`, `credit`, `identity`, `insurance`, `health`, `offers`, `account-management`, `preapproval` ### DocumentOutputResourceV20220801 - `filename` (string, required, nullable) ### MoneyAmountVMinimumVersion - `amount` (string, required, nullable) - `currency` (enum, required, nullable) - Allowed values: `USD` ### VerificationReportResourceV20220801 - `additional_notes` (string, required, nullable) - `created` (datetime, required) - `current_as_of` (date, required) - `d1c_eligible` (boolean, required, nullable) — Returns true if this report is eligible for Day 1 Certainty - `disputes` (list of DisputeV20220801, required) — Disputes that are currently open and relevant to this report - `du_reference_id` (string, required, nullable) — This is the reference ID to submit to Fannie Mae for purposes of getting Day 1 Certainty - `employee` (EmployeeV20220801, required) - `employer` (EmployerV20220801, required) - `id` (string, required) - `income_analytics` (ReportIncomeAnalyticsVMinimumVersion, required, nullable) — Calculated income features. Only returned if the `income_analytics` query parameter is provided and is `true` and the employee status on the report is active. - `paid_through_date` (date, required, nullable) — The pay period end date of the most recent paystub (falling back to the pay date if no pay period end is set). This field is only populated for VOIE reports and will be null for non-VOIE reports or when no paystubs exist. - `paystubs` (list of PaystubV20220801, required, nullable) — Individual paystubs for each pay period. Paystubs are returned sorted in descending order from most recent to least recent pay date. - `pricing_tier` (enum, required, nullable) - Allowed values: `instant`, `credentials`, `smart-outreach`, `third-party-providers`, `other` - `respondent` (RespondentV20220801, required, nullable) - `verification_request` (VerificationRequestV20220801, required) ### RequestParametersReadVMinimumVersion - `employer_filter` (enum, required) - Allowed values: `target-employer`, `all-employers`, `current-employer`, `previous-employers` - `verification_methods` (_VerificationMethodsRead, required) ### ResellerOriginatingPartyOutputV20220801 - `originating_party` (string, required) - `permissible_purpose` (enum, required) — A valid purpose is required for Truework to process the verification request. Throughout the API, this is signified by the `permissible_purpose` field. | VALUE | DESCRIPTION | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | child-support | Determine child support payments (available to verifiers that represent a state or local child support enforcement agencies) | | credit-application | The target's application for credit | | employee-eligibility | Employee's eligibility for a benefit granted by a governmental agency required by law to consider the employee's financial responsibility or status | | employee-request | The target has issued the verifier written instruction to obtain this information | | employee-review-or-collection | Performing a review or collection of the target's account | | employment | Employment purposes where the target has given prior written consent | | insurance-underwriting-application | Underwriting insurance in response to the target's application | | legitimate-reason-initiated | Legitimate business need for the information in connection with a business transaction initiated by the target | | legitimate-reason-review | Legitimate business need to review the target's account to determine whether the employee continues to meet the terms of the account | | risk-assessment | To assess the credit or prepayment risks associated with an existing credit obligation of the target | | subpoena | For a court order or a federal grand jury subpoena | other | No other value fits the permissible purpose of this verification request | - Allowed values: `child-support`, `credit-application`, `employee-eligibility`, `employee-request`, `employee-review-or-collection`, `employment`, `insurance-underwriting-application`, `legitimate-reason-initiated`, `legitimate-reason-review`, `risk-assessment`, `subpoena`, `other` - `use_case` (enum, required) — The verification request use case describes the type of product the verification request is originating from. If omitted, the verifier type in account settings will be used as a default | VALUE | DESCRIPTION | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------ | | mortgage | Verification for a mortgage | | home-equity | Verification for home equity | background | Verification for a background check | | tenant | Verification for a rental property | | government | Verification for government/social services | | auto | Verification for auto lending | | lending | Verification for personal loans or consumer lending | | credit | Verification for credit cards | | identity | Verification for identity or fraud | | insurance | Verification for insurance | | health | Verification for health services | | offers | Verification for offers | | account-management | Verification for account management | | preapproval | Verification for preapprovals | | other | Verification for other products. This exists for historical compatibility, no new Schemas can be created with this value | - Allowed values: `mortgage`, `home-equity`, `background`, `tenant`, `government`, `auto`, `lending`, `credit`, `identity`, `insurance`, `health`, `offers`, `account-management`, `preapproval`, `other` ### SubmissionTargetOutputVMinimumVersion - `company` (CompanyOutputVMinimumVersion, required, nullable) - `contact_email` (string, required, nullable) - `date_of_birth` (date, required, nullable) — Target's date of birth in format YYYY-MM-DD. `date_of_birth` is required for employer search/synchronous requests - `first_name` (string, required) - `last_name` (string, required) - `phone_number` (string, required, nullable) - `social_security_number` (string, required, nullable) — The target's obfuscated social security number ### TurnaroundTimeV20220801 - `best_estimate` (string, required, nullable) — The best estimate of turnaround time in hours - `lower_bound` (string, required, nullable) — The estimated lower bound in hours - `upper_bound` (string, required, nullable) — The estimated upper bound in hours ### _InvalidRequestError - `message` (string, required, default: Invalid field values provided) ### Error - `message` (string, required) ### SubmissionTargetInputVMinimumVersionCompany ### _VerificationMethodsWrite - `credentials` (_RequestMethod, optional, nullable) - `instant` (_RequestMethod, optional, nullable) - `smart_outreach` (_RequestMethod, optional, nullable) ### DisputeV20220801 - `created` (datetime, required) - `description` (string, required) — Description of dispute - `id` (string, required) — ID for this dispute in Truework - `reference_id` (string, required) — ID for this dispute to be displayed and referenced outside of this API ### EmployeeV20220801 - `address` (AddressV20220801, required, nullable) - `earnings` (list of EarningsV20220801, required, nullable) - `email` (string, required, nullable) - `first_name` (string, required) - `hired_date` (date, required, nullable) - `last_name` (string, required) - `on_leave_date` (date, required, nullable) - `positions` (list of PositionV20220801, required) - `salary` (SalaryV20220801, required, nullable) - `social_security_number` (string, required, nullable) — The employee's obfuscated social security number - `status` (enum, required) — There are five employment statuses available on the `status` field in `Employee`: | VALUE | DESCRIPTION | VERSION INTRODUCED | OLDER VERSION VALUE | | ---------------- | ------------------------------------------------------------------- | ------------------ | ------------------- | | active | The employee is currently employed and working for this employer | | | | inactive | The employee is not employed at this employer anymore | | | | unknown | Truework could not determine the employment status of this employee | | | | furloughed-covid | The employee was furloughed due to COVID-19 | `2020-12-07` | inactive | | non-employee | Truework could not find record of this employee | `2020-12-07` | unknown | | other | No other value exemplifies the Verification Report Status | `2022-08-01` | | - Allowed values: `active`, `inactive`, `unknown`, `furloughed-covid`, `non-employee`, `other` - `status_detail` (enum, required) — The `status_detail` provides more granular information for some `status` values: | VALUE | DESCRIPTION | `Status` | | ------------------ | ------------------------------------------------------------------- | ---------------- | | active | The employee is currently employed and working for this employer | active | | int-assignment | The employee is on international assignment | active | | casual | The employee is employed casually | active | | long-term-dis | The employee is on long term disability | active | | sick-leave | The employee is on sick leave | active | | surviving-spouse | The employee is a surviving spouse | inactive | | inactive | The employee is not employed at this employer anymore | inactive | | on-leave | The employee is on leave | active | | multiple-positions | The employee has multiple active positions | active | | new-employee | The employee is new | active | | lay-off | The employee was laid off | inactive | | part-time | The employee is currently employed on a part time basis | active | | retired | The employee is retired | inactive | | separated | The employee is separated | inactive | | season | The employee is seasonal | active | | temporary | The employee is temporary | active | | intern | The employee is an intern | active | | transferred | The employee has been transferred | active | | deceased | The employee is deceased | inactive | | severed-pay | The employee has been severed with pay | inactive | | on-sabbatical | The employee is on sabbatical | active | | divested | The employee is part of a divested population | active | | temp-inactive | The employee is temporarily inactive | inactive | | full-time | The employee is full time | active | | non-emp-ben | The employee is a non employee beneficiary | inactive | | not-assignment | The employee is not currently on assignment | inactive | | not-payroll | The employee is not currently on payroll | inactive | | active-as-needed | The employee is active as needed | active | | unknown | Truework could not determine the employment status of this employee | unknown | | furloughed-covid | The employee was furloughed due to COVID-19 | furloughed-covid | | non-employee | Truework could not find record of this employee | non-employee | | other | No other value exemplifies Verification Status Detail | other | - Allowed values: `active`, `int-assignment`, `casual`, `long-term-dis`, `sick-leave`, `surviving-spouse`, `inactive`, `on-leave`, `multiple-positions`, `new-employee`, `lay-off`, `part-time`, `retired`, `separated`, `season`, `temporary`, `intern`, `transferred`, `deceased`, `severed-pay`, `on-sabbatical`, `divested`, `temp-inactive`, `full-time`, `non-emp-ben`, `not-assignment`, `not-payroll`, `active-as-needed`, `unknown`, `furloughed-covid`, `non-employee`, `other`, `future-employee` - `termination_date` (date, required, nullable) ### EmployerV20220801 - `address` (AddressV20220801, required, nullable) - `government_ids` (list of _GovernmentId, required, nullable) - `name` (string, required) ### ReportIncomeAnalyticsVMinimumVersion - `annualized_income` (_AnnualizedIncome, required, nullable) - `income_volatility` (_IncomeVolatility, required, nullable) ### PaystubV20220801 - `base` (string, required, nullable) — Pre-deduction base pay - `bonus` (string, required, nullable) — Pre-deduction bonus pay - `commission` (string, required, nullable) — Pre-deduction commission pay - `gross` (string, required, nullable) — Total pre-deduction earnings for this pay period - `id` (string, required) — ID for this paystub in Truework - `net` (string, required, nullable) — Total post-deduction earnings for this pay period - `other` (string, required, nullable) — Pre-deduction other pay - `overtime` (string, required, nullable) — Pre-deduction overtime pay - `pay_date` (date, required, nullable) — Date of paycheck delivery - `pay_period_end_date` (date, required, nullable) — Last day of pay period - `pay_period_hours` (string, required, nullable) — Hours worked in this pay period - `pay_period_start_date` (date, required, nullable) — First day of pay period - `reference_id` (string, required, nullable) — ID for this paystub from the payroll provider ### RespondentV20220801 - `email` (string, required, nullable) - `full_name` (string, required, nullable) - `title` (string, required, nullable) ### VerificationRequestV20220801 - `created` (datetime, required) - `id` (string, required) - `type` (enum, required) - Allowed values: `employment-income`, `employment`, `tenant-screening`, `assets` ### _VerificationMethodsRead - `credentials` (_RequestMethod, required) - `instant` (_RequestMethod, required) - `smart_outreach` (_RequestMethod, required) ### CompanyOutputVMinimumVersion - `address` (string, required, nullable) — Human readable address - `city` (string, required, nullable) - `id` (integer, required, nullable) - `name` (string, required, nullable) - `phone_number` (string, required, nullable) - `state` (string, required, nullable) - `zip_code` (string, required, nullable) ### CompanyByNameInputVMinimumVersion - `name` (string, required) - `address` (string, optional, nullable) — Human readable address - `city` (string, optional, nullable) - `phone_number` (string, optional, nullable) - `state` (string, optional, nullable) - `zip_code` (string, optional, nullable) ### CompanyByIdInputVMinimumVersion - `id` (string, required) - `address` (string, optional, nullable) — Human readable address - `city` (string, optional, nullable) - `phone_number` (string, optional, nullable) - `state` (string, optional, nullable) - `zip_code` (string, optional, nullable) ### _RequestMethod - `enabled` (boolean, required) ### AddressV20220801 - `address` (string, required, nullable) - `city` (string, required, nullable) - `country_code` (string, required, nullable) - `country_subdivision_code` (string, required, nullable) - `extended_address` (string, required, nullable) - `postal_code` (string, required, nullable) ### EarningsV20220801 - `base` (string, required) - `bonus` (string, required) - `commission` (string, required) - `other` (string, required) - `overtime` (string, required) - `termination` (boolean, required) - `total` (string, required) - `year` (string, required, nullable) ### PositionV20220801 - `employment_type` (enum, required) — | VALUE | DESCRIPTION | VERSION INTRODUCED | OLDER VERSION VALUE | | ----------------- | -------------------------------- | ------------------ | ------------------- | | regular-full-time | Regular full time | | | | regular-part-time | Regular part time | | | | contractor-1099 | Contractor | | | | other | Other or unknown employment type | | | | no-answer | Question was not answered | `2020-12-07` | other | - Allowed values: `regular-full-time`, `regular-part-time`, `contractor-1099`, `other`, `no-answer` - `end_date` (date, required, nullable) - `start_date` (date, required, nullable) - `title` (string, required, nullable) ### SalaryV20220801 - `hours_per_week` (string, required, nullable) - `pay_frequency` (enum, required, nullable) — The frequency by which the employee is paid. - Allowed values: `annually`, `daily`, `semiweekly`, `monthly`, `weekly`, `biweekly`, `bimonthly`, `semimonthly`, `quarterly`, `semiannually`, `thirteen-monthly`, `fourteen-month`, `hourly`, `variable`, `other` - `pay_rate` (PayRateV20220801, required) — Describes the amount and unit that determine the employees pay. - `reduced_covid` (enum, required) - Allowed values: `yes`, `no`, `unknown` ### _GovernmentId - `id` (string, required) - `type` (enum, required) - Allowed values: `us-fein`, `other` ### _AnnualizedIncome - `amount` (MoneyAmountVMinimumVersion, required) — This field is being deprecated. This field is the same as gross_amount. If gross_amount returns `null`, this field will be returned with `0.00` as a value. - `base_amount` (MoneyAmountVMinimumVersion, required, nullable) — Represents annualized income for recurring income, like salary. In rare cases due to data quality issues, gross amount is returned without base amount or vice versa. - `gross_amount` (MoneyAmountVMinimumVersion, required, nullable) — Represents base annualized income plus variable income sources. In rare cases due to data quality issues, gross amount is returned without base amount or vice versa. - `short_employment_warning` (boolean, required) — True if the employee recently started at this position, which could impact annualized income accuracy. - `stale_data_warning` (boolean, required) — True if the data on this report is not fresh, which could impact annualized income accuracy. - `variable_income_warning` (boolean, required) — True if the employees income has high variability, which could impact annualized income accuracy. ### _IncomeVolatility - `gross_income_volatility` (string, required, nullable) — Coefficient of variation of the aggregated per pay period gross earnings for a given list of paystubs. ### PayRateV20220801 - `amount` (string, required, nullable) — The amount the employee gets paid per timeframe defined by the adject unit field. - `unit` (enum, required, nullable) — The timeframe in which the employee gets paid the amount defined in the adjacent amount field. - Allowed values: `annually`, `daily`, `semiweekly`, `monthly`, `weekly`, `biweekly`, `bimonthly`, `semimonthly`, `quarterly`, `semiannually`, `thirteen-monthly`, `fourteen-month`, `hourly`, `variable`, `other` ## Examples **Request** ```json { "permissible_purpose": "child-support", "target": { "first_name": "Jane", "last_name": "Doe", "social_security_number": "000-00-0000" }, "type": "employment-income", "use_case": "mortgage" } ``` **Response** ```json { "additional_information": "string", "branch_id": "5678", "cancellation_details": "string", "cancellation_reason": "immediate", "created": "2021-12-20T18:50:20.291247Z", "date_of_completion": "2021-12-20T18:50:20.291247Z", "documents": [ { "filename": "test.pdf" } ], "id": "AAAAAAAAAosABwGqF1AUKAH0-puth1tCzLNar3Jyb4bx3wdVKU99XC26", "loan_id": "string", "metadata": {}, "permissible_purpose": "child-support", "price": { "amount": "34.95", "currency": "USD" }, "reports": [ { "additional_notes": "string", "created": "2021-12-20T18:50:20.291247Z", "current_as_of": "2021-12-20", "d1c_eligible": true, "disputes": [ { "created": "2021-12-20T18:50:20.291247Z", "description": "Employee Title", "id": "AAAAAAAAAL8AElevkrw2n2vI8ScqGJEf50Lfg4W9LiQXwi-KSmg7DH0P", "reference_id": "d75346a0-a747-4907-a506-639ea436f2b0" } ], "du_reference_id": "string", "employee": { "address": { "address": "1234 Rainbow Road", "city": "San Francisco", "country_code": "US", "country_subdivision_code": "CA", "extended_address": "Suite 300", "postal_code": "98265" }, "earnings": [ { "base": "35000.00", "bonus": "0.00", "commission": "100.25", "other": "0.00", "overtime": "200.00", "termination": false, "total": "35300.25", "year": "2020" } ], "email": "string", "first_name": "Jane", "hired_date": "2023-01-15", "last_name": "Doe", "on_leave_date": "2023-01-15", "positions": [ { "employment_type": "regular-full-time", "end_date": "2023-01-15", "start_date": "2023-01-15", "title": "Software Engineer" } ], "salary": { "hours_per_week": "40", "pay_frequency": "biweekly", "pay_rate": { "amount": "150000.00", "unit": "annually" }, "reduced_covid": "yes" }, "social_security_number": "***-**-0000", "status": "active", "status_detail": "active", "termination_date": "2023-01-15" }, "employer": { "address": { "address": "1234 Rainbow Road", "city": "San Francisco", "country_code": "US", "country_subdivision_code": "CA", "extended_address": "Suite 300", "postal_code": "98265" }, "government_ids": [ { "id": "123456789", "type": "us-fein" } ], "name": "string" }, "id": "AAAAAAAADU8ACy03lGitY_ocCMCcgproUq8Gt4r37MM6GbyX2-DxWM3Y", "income_analytics": { "annualized_income": { "amount": { "amount": "34.95", "currency": "USD" }, "base_amount": { "amount": "34.95", "currency": "USD" }, "gross_amount": { "amount": "34.95", "currency": "USD" }, "short_employment_warning": true, "stale_data_warning": true, "variable_income_warning": true }, "income_volatility": { "gross_income_volatility": "string" } }, "paid_through_date": "2023-01-15", "paystubs": [ { "base": "7000.00", "bonus": "1000.00", "commission": "0.00", "gross": "8000.00", "id": "AAAAAAAAAmEADp7bmZJNhm4Kr5FM_ty5A_JX-Rxh04GSIHwmIRyp6Xss", "net": "5500.00", "other": "0.00", "overtime": "0.00", "pay_date": "2023-01-15", "pay_period_end_date": "2023-01-15", "pay_period_hours": "86.67", "pay_period_start_date": "2023-01-15", "reference_id": "6894632654" } ], "pricing_tier": "instant", "respondent": { "email": "string", "full_name": "string", "title": "string" }, "verification_request": { "created": "2021-12-20T18:50:20.291247Z", "id": "AAAAAAAAEboABwQhKv1_pWO7MWtZs28ksPTH0uSt6GffsoIJPj7e69P1", "type": "employment" } } ], "request_parameters": { "employer_filter": "target-employer", "verification_methods": { "credentials": { "enabled": true }, "instant": { "enabled": true }, "smart_outreach": { "enabled": true } } }, "reseller_originating_party": { "originating_party": "string", "permissible_purpose": "child-support", "use_case": "mortgage" }, "state": "pending-approval", "target": { "company": { "address": "string", "city": "string", "id": 1, "name": "Example Inc.", "phone_number": "string", "state": "string", "zip_code": "string" }, "contact_email": "string", "date_of_birth": "2023-01-15", "first_name": "Jane", "last_name": "Doe", "phone_number": "string", "social_security_number": "***-**-0000" }, "turnaround_time": { "best_estimate": "48", "lower_bound": "20", "upper_bound": "128" }, "type": "employment-income", "use_case": "mortgage" } ``` **SDK Code** ```python import requests url = "https://api.truework-sandbox.com/verification-requests" payload = { "permissible_purpose": "child-support", "target": { "first_name": "Jane", "last_name": "Doe", "social_security_number": "000-00-0000" }, "type": "employment-income", "use_case": "mortgage" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.truework-sandbox.com/verification-requests'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"permissible_purpose":"child-support","target":{"first_name":"Jane","last_name":"Doe","social_security_number":"000-00-0000"},"type":"employment-income","use_case":"mortgage"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.truework-sandbox.com/verification-requests" payload := strings.NewReader("{\n \"permissible_purpose\": \"child-support\",\n \"target\": {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"social_security_number\": \"000-00-0000\"\n },\n \"type\": \"employment-income\",\n \"use_case\": \"mortgage\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.truework-sandbox.com/verification-requests") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"permissible_purpose\": \"child-support\",\n \"target\": {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"social_security_number\": \"000-00-0000\"\n },\n \"type\": \"employment-income\",\n \"use_case\": \"mortgage\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.truework-sandbox.com/verification-requests") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"permissible_purpose\": \"child-support\",\n \"target\": {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"social_security_number\": \"000-00-0000\"\n },\n \"type\": \"employment-income\",\n \"use_case\": \"mortgage\"\n}") .asString(); ``` ```php request('POST', 'https://api.truework-sandbox.com/verification-requests', [ 'body' => '{ "permissible_purpose": "child-support", "target": { "first_name": "Jane", "last_name": "Doe", "social_security_number": "000-00-0000" }, "type": "employment-income", "use_case": "mortgage" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.truework-sandbox.com/verification-requests"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"permissible_purpose\": \"child-support\",\n \"target\": {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"social_security_number\": \"000-00-0000\"\n },\n \"type\": \"employment-income\",\n \"use_case\": \"mortgage\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "permissible_purpose": "child-support", "target": [ "first_name": "Jane", "last_name": "Doe", "social_security_number": "000-00-0000" ], "type": "employment-income", "use_case": "mortgage" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.truework-sandbox.com/verification-requests")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```