curl --request GET \
--url https://api.sandbox.lead.bank/v2/entities/{id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.sandbox.lead.bank/v2/entities/{id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.sandbox.lead.bank/v2/entities/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.sandbox.lead.bank/v2/entities/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.sandbox.lead.bank/v2/entities/{id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.sandbox.lead.bank/v2/entities/{id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sandbox.lead.bank/v2/entities/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"id": "entity_xyz123",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"type": "individual",
"individual_details": {
"first_name": "<string>",
"last_name": "<string>",
"identification_details": {
"type": "us_entity",
"tax_identification": {
"type": "ssn",
"value": "<string>"
},
"identification_documents": [
{
"file_id": "file_7Tq4mR9vKx2LpW8nZc3B",
"identification_number": "X1234567",
"issuing_country": "GB",
"expiration_date": "2030-06-01"
},
{
"type": "passport",
"identification_number": "X7654321",
"issuing_country": "GB",
"expiration_date": "2031-01-15"
}
],
"legacy_identification_documents": [
{
"client_document_id": "passport_jane_doe.pdf",
"type": "passport",
"identification_number": "X1234567",
"issuing_country": "GB",
"expiration_date": "2026-06-01"
}
]
},
"preferred_first_name": "<string>",
"middle_name": "<string>",
"date_of_birth": "2002-02-15",
"occupation": "<string>",
"contact_methods": [
{
"type": "email",
"email": "abc@gmail.com"
}
],
"address_details": {
"physical_address": {
"line_1": "123 Main St.",
"city": "Denver",
"country": "US",
"line_2": "Apt 25",
"postal_code": 80014,
"state": "CO"
},
"mailing_address": {
"line_1": "123 Main St.",
"city": "Denver",
"country": "US",
"line_2": "Apt 25",
"postal_code": 80014,
"state": "CO"
},
"other_addresses": [
{
"line_1": "123 Main St.",
"city": "Denver",
"country": "US",
"line_2": "Apt 25",
"postal_code": 80014,
"state": "CO"
}
]
},
"additional_documents": [
{
"file_id": "file_X5jD8hN2sQ6yFb1Gt9Ka"
},
{
"type": "financial_statement"
}
],
"legacy_additional_documents": [
{
"client_document_id": "2026_01_02_statement",
"type": "bank_statement",
"description": "Bank statement for January"
}
]
},
"eligibility": {
"account_holder": {
"status": "eligible",
"failed_checks": []
},
"minor_account_holder": {
"status": "ineligible",
"failed_checks": [
{
"check": "check_date_of_birth_above_maximum",
"entity_id": "entity_xyz123",
"reason": "The entity exceeds the maximum age for minor_account_holder."
}
]
},
"authorized_signer": {
"status": "eligible",
"failed_checks": []
},
"authorized_user": {
"status": "eligible",
"failed_checks": []
}
},
"client_customer_id": "<string>",
"risk_score": "low",
"rfi_details": {
"result": "completed",
"requested_at": "2023-11-07T05:31:56Z"
},
"ofac_details": {
"result": "passed",
"screened_at": "2023-11-07T05:31:56Z"
},
"kyc_details": {
"result": "passed",
"screened_at": "2023-11-07T05:31:56Z"
},
"credit_details": [
{
"credit_report_source": "equifax",
"credit_pulled_at": "2023-11-07T05:31:56Z",
"credit_score": "<string>",
"credit_report_non_score_value": "unestablished"
}
],
"intended_eligibility": [
"account_holder"
],
"metadata": {}
}{
"code": "request_malformed",
"message": "The request is invalid and cannot be parsed by the server.",
"errors": [
{
"code": "url_malformed",
"message": "The request URL could not be parsed."
}
]
}{
"code": "token_invalid",
"message": "The bearer token is missing, expired, malformed, or invalid."
}{
"code": "object_not_found",
"message": "No object exists at the requested ID, or it is not visible to this caller."
}{
"code": "lead_control_restricted",
"message": "A Lead-configured control blocks this request. Contact Lead with the Lead-Request-ID.",
"errors": [
{
"code": "feature_not_enabled",
"message": "Entity v2 isn't enabled for your program. Contact Lead to enable it."
}
]
}{
"code": "rate_limit_exceeded",
"message": "You have exceeded the rate limit for this endpoint. Retry with backoff."
}{
"code": "internal_server_error",
"message": "Something went wrong on our end. Contact Lead with the Request-Id if this persists."
}{
"code": "service_unavailable",
"message": "The service is temporarily unavailable. Retry after the indicated delay."
}{
"code": "gateway_timeout",
"message": "An upstream system timed out. Retry with backoff."
}Retrieve an Entity
Retrieve an Entity by its ID. Entities created on v0 are returned in this shape. eligibility is computed from the Entity’s current data on every read. This also returns your program’s lead and partner Entities, which Lead provisions and which have a reduced, read-only shape. Documents sent through v0 are returned read-only in legacy_identification_documents and legacy_additional_documents.
curl --request GET \
--url https://api.sandbox.lead.bank/v2/entities/{id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.sandbox.lead.bank/v2/entities/{id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.sandbox.lead.bank/v2/entities/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.sandbox.lead.bank/v2/entities/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.sandbox.lead.bank/v2/entities/{id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.sandbox.lead.bank/v2/entities/{id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sandbox.lead.bank/v2/entities/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"id": "entity_xyz123",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"type": "individual",
"individual_details": {
"first_name": "<string>",
"last_name": "<string>",
"identification_details": {
"type": "us_entity",
"tax_identification": {
"type": "ssn",
"value": "<string>"
},
"identification_documents": [
{
"file_id": "file_7Tq4mR9vKx2LpW8nZc3B",
"identification_number": "X1234567",
"issuing_country": "GB",
"expiration_date": "2030-06-01"
},
{
"type": "passport",
"identification_number": "X7654321",
"issuing_country": "GB",
"expiration_date": "2031-01-15"
}
],
"legacy_identification_documents": [
{
"client_document_id": "passport_jane_doe.pdf",
"type": "passport",
"identification_number": "X1234567",
"issuing_country": "GB",
"expiration_date": "2026-06-01"
}
]
},
"preferred_first_name": "<string>",
"middle_name": "<string>",
"date_of_birth": "2002-02-15",
"occupation": "<string>",
"contact_methods": [
{
"type": "email",
"email": "abc@gmail.com"
}
],
"address_details": {
"physical_address": {
"line_1": "123 Main St.",
"city": "Denver",
"country": "US",
"line_2": "Apt 25",
"postal_code": 80014,
"state": "CO"
},
"mailing_address": {
"line_1": "123 Main St.",
"city": "Denver",
"country": "US",
"line_2": "Apt 25",
"postal_code": 80014,
"state": "CO"
},
"other_addresses": [
{
"line_1": "123 Main St.",
"city": "Denver",
"country": "US",
"line_2": "Apt 25",
"postal_code": 80014,
"state": "CO"
}
]
},
"additional_documents": [
{
"file_id": "file_X5jD8hN2sQ6yFb1Gt9Ka"
},
{
"type": "financial_statement"
}
],
"legacy_additional_documents": [
{
"client_document_id": "2026_01_02_statement",
"type": "bank_statement",
"description": "Bank statement for January"
}
]
},
"eligibility": {
"account_holder": {
"status": "eligible",
"failed_checks": []
},
"minor_account_holder": {
"status": "ineligible",
"failed_checks": [
{
"check": "check_date_of_birth_above_maximum",
"entity_id": "entity_xyz123",
"reason": "The entity exceeds the maximum age for minor_account_holder."
}
]
},
"authorized_signer": {
"status": "eligible",
"failed_checks": []
},
"authorized_user": {
"status": "eligible",
"failed_checks": []
}
},
"client_customer_id": "<string>",
"risk_score": "low",
"rfi_details": {
"result": "completed",
"requested_at": "2023-11-07T05:31:56Z"
},
"ofac_details": {
"result": "passed",
"screened_at": "2023-11-07T05:31:56Z"
},
"kyc_details": {
"result": "passed",
"screened_at": "2023-11-07T05:31:56Z"
},
"credit_details": [
{
"credit_report_source": "equifax",
"credit_pulled_at": "2023-11-07T05:31:56Z",
"credit_score": "<string>",
"credit_report_non_score_value": "unestablished"
}
],
"intended_eligibility": [
"account_holder"
],
"metadata": {}
}{
"code": "request_malformed",
"message": "The request is invalid and cannot be parsed by the server.",
"errors": [
{
"code": "url_malformed",
"message": "The request URL could not be parsed."
}
]
}{
"code": "token_invalid",
"message": "The bearer token is missing, expired, malformed, or invalid."
}{
"code": "object_not_found",
"message": "No object exists at the requested ID, or it is not visible to this caller."
}{
"code": "lead_control_restricted",
"message": "A Lead-configured control blocks this request. Contact Lead with the Lead-Request-ID.",
"errors": [
{
"code": "feature_not_enabled",
"message": "Entity v2 isn't enabled for your program. Contact Lead to enable it."
}
]
}{
"code": "rate_limit_exceeded",
"message": "You have exceeded the rate limit for this endpoint. Retry with backoff."
}{
"code": "internal_server_error",
"message": "Something went wrong on our end. Contact Lead with the Request-Id if this persists."
}{
"code": "service_unavailable",
"message": "The service is temporarily unavailable. Retry after the indicated delay."
}{
"code": "gateway_timeout",
"message": "An upstream system timed out. Retry with backoff."
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
The ID of your entity.
^entity_[^\s]{1,33}$"entity_xyz123"
Response
An entity object.
- Individual
- Business
- Sole Prop
- Lead
- Partner
Unique ID for the Entity object.
^entity_[^\s]{1,33}$"entity_xyz123"
Timestamp at which the entity object is created.
Timestamp at which the entity object was last updated.
Type of entity = individual.
^individual$Details for the individual entity. An authorized_user requires only first_name, last_name, a contact method, and identification_details.type. Other relationship types require more; see Eligibility.
Show child attributes
Show child attributes
Whether the entity's current data qualifies it for each relationship type, with the failing checks. Response only. Lead computes it from current data on every read and never stores it. All four keys are always present. On a program that does not offer minor account holders, minor_account_holder is ineligible for every entity.
Show child attributes
Show child attributes
{
"account_holder": { "status": "eligible", "failed_checks": [] },
"minor_account_holder": {
"status": "ineligible",
"failed_checks": [
{
"check": "check_date_of_birth_above_maximum",
"entity_id": "entity_xyz123",
"reason": "The entity exceeds the maximum age for minor_account_holder."
}
]
},
"authorized_signer": { "status": "eligible", "failed_checks": [] },
"authorized_user": { "status": "eligible", "failed_checks": [] }
}
Your customer ID, on entities created on v0 or through Entity files. Response only. Lead ignores it if sent, and does not return it on other entities.
The entity's risk score, mapped to Lead by the client. Client should have provided risk score mapping to Lead.
low, medium, high "low"
Show child attributes
Show child attributes
Details on OFAC on the entity.
Show child attributes
Show child attributes
Details on KYC on the entity.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
The relationship types you intend this entity to hold. When you send it, Lead checks the entity's data against every listed type and rejects the request with 422 parameters_invalid if any fails. The check is all or nothing, and the error returns every failing check, not just the first. Listing fewer types than the entity qualifies for still succeeds, and eligibility shows everything it qualifies for.
If the check passes, Lead saves the list and returns it on the entity. On a PATCH, Lead checks the entity as it would be after the update, against the list you send or, if you leave the field out, the saved list. Send an empty array to clear the saved list; no check runs.
A relationship type an entity can hold.
account_holder: Full control of, and legal responsibility for, the account.minor_account_holder: An individual aged 16 or 17 with account holder eligibility.authorized_signer: An individual allowed to sign on behalf of the account holder, without legal responsibility.authorized_user: An individual with restricted access to the account, without legal responsibility.
account_holder, minor_account_holder, authorized_signer, authorized_user ["account_holder"]
A set of key-value pairs that can be used to store additional information related to this object.
Show child attributes
Show child attributes
Was this page helpful?

