> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://www.truework.com/docs/api-reference/previous-versions/2019-10-15/get-credentials-session/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://www.truework.com/_mcp/server. # Create a Credentials Session POST https://api.truework-sandbox.com/credentials/session Content-Type: application/json Creates a new Credentials Session and returns a JSON object representing the newly created Credentials Session. Reference: https://www.truework.com/docs/api-reference/previous-versions/2019-10-15/get-credentials-session ## 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 ### 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=2019-10-15` ### Body (application/json) This endpoint expects a CredentialsSessionPostVMinimumVersion. - `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) - `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` - `metadata` (map from string to string, optional, nullable, default: {}) — 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_party` (_CredentialsResellerInfo, optional, nullable) — Required for reseller requests, should not be provided for non-reseller requests. ## Response ### 201 A Credentials Session was successfully created. - `id` (string, required) - `token` (string, required) ## 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) ### _CredentialsResellerInfo - `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` ### _InvalidRequestError - `message` (string, required, default: Invalid field values provided) ### Error - `message` (string, required) ### SubmissionTargetInputVMinimumVersionCompany ### 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) ## 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 { "id": "AAAAAAAAQnIAAYd5YHFVOm8PNX2ecFbEjqV__upOKUE8YE_IK2GwSQTP", "token": "qvsEXEdbnGCSW3UmwbUuYZ_jlA73BLHvFy93Ocv8tPI" } ``` **SDK Code** ```python import requests url = "https://api.truework-sandbox.com/credentials/session" 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/credentials/session'; 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/credentials/session" 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/credentials/session") 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/credentials/session") .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/credentials/session', [ '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/credentials/session"); 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/credentials/session")! 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() ```