---
title: "Search legal persons"
method: POST
path: "/v0/organizations/{organization-id}/legal-persons/search"
tags: ["Legal persons"]
---

# Search legal persons

`POST /v0/organizations/{organization-id}/legal-persons/search`

Returns a list of legal persons whose legal names match the `search-query` supplied in the request.
                 Takes an optional 'equals onboarded' filter.

## Path parameters

- `organization-id` string, required

## Query parameters

- `include` string[]
- `filter[legal-person-status][eq]` 'onboarded'

## Request body

- object
  - `search-query` string, required

## Response `200`

OK

- object
  - `search-results` object[], required
    - `latest-decision` object — The most recent [decision](#tag/Decisions)
      - `decision-outcome` 'accepted' | 'declined', required
      - `decision-notes` string, required — Free-text field to explain the reasons behind the decision.
      - `verification-url` string, required — A link to the [verification](#tag/Verifications).
      - `legal-person-url` union, required — A contextual link to the [legal person](#tag/Legal-persons).
        - string
        - string
      - `created-at` string, date-time, required — ISO 8601 formatted date-time.
      - `decision-maker` 'system' | 'ops-user' | 'user', required — Indicates if the decision was automated or made by a human.
      - `decision-user-url` string — Link to the [user](#tag/Users) that made the decision (if applicable).
      - `decision-ops-user` 'griffin-ops-user' — Indicates that an Ops user has created the decision.
      - `decision-user-username` string — Username of the [user](#tag/Users) that made the decision (if applicable).
    - `legal-person-type` 'individual' | 'corporation', required — Specifies if the legal person is an `individual` or a `corporation`.
    - `latest-risk-rating-url` string — A contextual link to the risk rating.
    - `display-name` string, required — The mutable display name for the Legal-Person
    - `application-status` 'referred' | 'errored' | 'declined' | 'submitted' | 'accepted' — Status of the current [application](/docs/terms/application)
    - `legal-person-status` 'restricted' | 'onboarding-declined' | 'onboarded' | 'verified' | 'onboarding' — Status of the [legal person](#tag/Legal-persons)
    - `legal-person-url` union, required — A contextual link to the [legal person](#tag/Legal-persons).
      - string
      - string
    - `legal-person-decisions-url` union, required — Link to [decisions](#tag/Decisions) for this [legal person](/docs/terms/legal-person).
      - string
      - string
    - `status-changed-at` string, date-time — ISO 8601 formatted date-time.
    - `created-at` string, date-time, required — ISO 8601 formatted date-time.
    - `legal-person-claims-url` union — Link to the [claims](#tag/Claims) for this [legal person](/docs/terms/legal-person).
      - string
      - string
    - `legal-person-bank-payees-url` union — Link to the [payees](#tag/Payees) for this [legal person](/docs/terms/legal-person).
      - string
      - string
    - `legal-person-verifications-url` union, required — Link to all [verifications](#tag/Verifications) run against this [legal person](/docs/terms/legal-person).
      - string
      - string
    - `legal-name` string — A read-only, human readable label derived from claims
    - `legal-person-documents-url` union, required — Link to all evidence documents associated with this [legal person](/docs/terms/legal-person).
      - string
      - string
  - `meta` object, required
    - `page` object
      - `total` integer — Total number of items. Present when the total number of items in the full result set is less than 10,000.
      - `estimated-total` object
        - `at-least` 10000 — Present when the total number of items in the full result set exceeds 10,000. This indicates that the actual number of items is at least 10,000, but the exact total is not provided due to performance considerations.
  - `included` object — Present only when the request uses the `include` parameter.
    - `company-roles` object[]
      - `legal-person-url` union, required — A contextual link to the [legal person](#tag/Legal-persons).
        - string
        - string
      - `individual-company-roles` object, required — Each key identifies a company the individual holds a role in. Each value is a collection of company roles the individual has in the company specified by the key.

## Other responses

- `401` — Requires an API key to continue
- `404` — Not Found

---

[API](https://skmtc.net/griffin/apis/the-griffin-api.md) · [All operations](https://skmtc.net/griffin/apis/the-griffin-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/griffin/the-griffin-api/revisions/e56cd4bb9677/schema)