Create a Credentials Session

Creates a new Credentials Session and returns a JSON object representing the newly created Credentials Session.

Authentication

AuthorizationBearer

Bearer tokens conform to the RFC6750 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 .

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 `.

Request

permissible_purposeenumRequired

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

targetobjectRequired

typeenumRequired

use_caseenumRequired

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

metadatamap from strings to strings or nullOptionalDefaults to {}

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.

reseller_originating_partyobject or nullOptional

Required for reseller requests, should not be provided for non-reseller requests.

Response headers

Datestring

For JSON requests, the date at which the request was signed

X-Truework-Signaturestring

For JSON requests, the signature of the request, see: https://www.truework.com/docs/verifications-signatures

Response

A Credentials Session was successfully created.

idstring>=1 character

tokenstring>=1 character

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

406

Not Acceptable Error

429

Too Many Requests Error

451

Unavailable for Legal Reasons Error

500

Internal Server Error

501

Not Implemented Error

$	curl -X POST https://api.truework-sandbox.com/credentials/session \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"permissible_purpose": "child-support",
>	"target": {
>	"first_name": "Jane",
>	"last_name": "Doe",
>	"social_security_number": "000-00-0000"
>	},
>	"type": "employment-income",
>	"use_case": "mortgage"
>	}'

1	{
2	"id": "AAAAAAAAQnIAAYd5YHFVOm8PNX2ecFbEjqV__upOKUE8YE_IK2GwSQTP",
3	"token": "qvsEXEdbnGCSW3UmwbUuYZ_jlA73BLHvFy93Ocv8tPI"
4	}