> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plyne.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Dictionary

> Field names, JSON types, examples, and missing-value behavior for the data returned by the Plyne API.

Use this reference to understand the records returned by the API and map them into your CRM, application, or workflow. The tables describe the fields available in API responses, including their types, examples, and behavior when a value is missing.

For the meaning of each signal type, see [Signal types](https://docs.plyne.ai/signals/types.md). For request filters, supported sorting, and country codes, see [Accepted Filter Values](https://docs.plyne.ai/api/accepted-filter-values.md).

## Which object do I receive?

| Endpoint | Each item in `data` |
| - | - |
| `GET /v1/signal-agents` | A SignalAgent with its linked Sheet and schedule information. |
| `POST /v1/leads/search` | A Lead with an AccountSummary and its selected evaluation with linked findings. |
| `POST /v1/accounts/search` | An Account with its selected evaluation, linked findings, and available assessment. |
| `POST /v1/leads/{lead_id}/evaluations/search` | An Evaluation with its own assessment and linked-finding preview. |
| `POST /v1/accounts/{account_id}/evaluations/search` | An Evaluation with its own assessment and linked-finding preview. |
| `POST /v1/leads/{lead_id}/signals/search` | A SignalHistoryEntry belonging to that Lead. |
| `POST /v1/accounts/{account_id}/signals/search` | A SignalHistoryEntry belonging to that Account. |

Field names in each table are relative to that object. For example, `account.domain` on a Lead is the `domain` field in AccountSummary. An embedded AccountSummary contains basic company identity, not every field on the Account response.

## JSON types and missing values

| JSON value | Meaning |
| - | - |
| `string` | Text or an opaque ID. Keep IDs as strings; do not parse them as numbers. |
| `integer` | A JSON number without a fractional part, such as an AI score or signal count. |
| `boolean` | `true` or `false`, used for pagination. |
| Timestamp string | An RFC 3339 timestamp, which may include fractional seconds. |
| `null` | An optional object or timestamp is unavailable. |
| `""` | A string has no available value. A missing person name uses the display fallback `Unknown person`. |
| `[]` | An array contains no returned items. |

Successful list responses always include a `data` array and a `cursor` object. A final page has `cursor.next: ""` and `cursor.has_more: false`. All object fields shown in successful response models are emitted; optional objects and timestamps use `null` instead of disappearing.

On Leads and Accounts, an uncalculated `evaluation.ai_score` is `null`; on a finding, `ai_score` is `null`. If the record has no evaluation, `evaluation` itself is `null`. A calculated score of zero is an object containing `value: 0`; it is not missing data. Its `fit` matches the portal: `weak` from 0 through 29, `low` from 30 through 49, `medium` from 50 through 79, and `high` from 80 through 100. Only records with an available score can match an explicit AI score range filter.

The downloadable [OpenAPI specification](https://docs.plyne.ai/openapi/public.swagger.json) uses the Swagger 2.0 `x-nullable` extension to express nullable fields. The **Nullable** column below describes the actual JSON responses. Schema examples are illustrative; they do not guarantee that a field will be populated for every record.

## Records, findings, and counts

Lead and Account lists return one row per Lead or Account. `evaluation` contains the selected saved evaluation and up to five findings linked to that exact evaluation. The assessment is returned only inside `evaluation`. `source_sheet` is the selected source context, rather than every Sheet membership. Use `evaluation.findings_cursor` with `evaluation_id` on signal history to continue reading the linked findings.

`signal_count` counts qualified signal sources, based on their latest qualification. Several retained findings from the same configuration can contribute only one source to that count. It is not the number of rows returned by signal history.

Source filters determine which entities match a search. `signal_count` and `latest_signal_at` still describe the entity across its visible sources. The selected evaluation can include findings with a different signal type from the source that matched the request. See [Pagination and Filters](https://docs.plyne.ai/api/pagination.md) for filter scope and sorting.

## Dates and historical assessments

* On a Lead or Account, `found_at` means when the entity first entered the portal's Directory.
* On a signal, `found_at` means when that finding was saved in Plyne. History is filtered and ordered using this timestamp.
* `latest_signal_at` is the newest visible signal finding time for the entity. It may refer to a newer rejected or unclear finding, and need not equal `evaluation.found_at`.
* `observed_at` is the source observation timestamp attached to a historical signal when available. Older findings may have `null` here.

History includes retained findings marked qualified, unqualified, or unclear, subject to source visibility and workspace scope. Each historical qualification and AI score belongs to that finding's own recorded result; the current entity assessment is not copied onto every historical row. Existing findings can be refreshed during re-evaluation, so history is not an immutable revision log of every agent check.

## Evaluations and their findings

An `Evaluation` has its own occurrence ID, saved time, qualification, and AI score. Its `findings` contains at most five visible linked findings, each with its own saved assessment and evidence. Continue with `findings_cursor` on signal history using `evaluation_id` equal to that evaluation's ID. Evaluation list pagination is separate from linked-finding pagination.

A Lead or Account exposes its assessment only through `evaluation.qualification` and `evaluation.ai_score`. `signal_sources` lists the qualified source identities shown by the portal's signal stack; `signal_count` uses the same source set. Different evaluations can legitimately reference the same finding.

## Evidence and qualification references

`qualification.references` contains links attached to that exact qualification result. On a history entry, the top-level `references` contains evidence links for the signal finding, including supported legacy evidence sources. These fields serve different purposes and need not contain the same links.

Each reference array returns at most 20 distinct links. An empty array means no links are available in the response; it does not mean the finding has no supporting evidence.

## Data coverage

Fields are returned when supported by the public response model and available for that record. These endpoints do not automatically run enrichment or fetch missing contact information.

The current public models do not expose full employment histories, education, skills, verified email/phone collections, company firmographics, arbitrary custom enrichment columns, or raw provider metadata. A signal's type can describe the criterion that found a record without returning the entire underlying profile or dataset. For example, a Skills & About signal is evidence of a match; it does not add a `skills[]` profile field to the Lead response.

## Lead

| API field | Type | Meaning | Example | Nullable |
| - | - | - | - | - |
| `account` | AccountSummary object | Associated company summary, or null when no Account is available. This is a compact AccountSummary rather than the full Account response. | — | Yes |
| `country_code` | string | Lead country as an ISO 3166-1 alpha-2 code; empty string when unavailable. | `"US"` | No |
| `evaluation` | Evaluation object | Selected portal evaluation and a page of its exact linked findings, or null. Qualification and AI score are returned only inside this evaluation. | — | Yes |
| `found_at` | string (RFC 3339 timestamp) | When the Lead first entered the portal Directory. This is entity-level Date found, not the selected finding date. | `"2026-08-01T08:00:00Z"` | Yes |
| `full_name` | string | First and last name joined for display. Uses Unknown person when no name is recorded. | `"Sarah Carter"` | No |
| `id` | string | Stable Lead identifier; use this ID to read Lead signal history. | `"ld_person"` | No |
| `job_title` | string | Current selected job title; empty string when unavailable. | `"Head of Engineering"` | No |
| `latest_signal_at` | string (RFC 3339 timestamp) | Time the latest visible material occurrence was saved for this entity, including rejected or unclear findings. Null when none exists. Source filters do not reduce this entity-wide statistic. | `"2026-11-15T08:00:00Z"` | Yes |
| `profile` | Profile object | Selected person profile, or null when no profile details are available. | — | Yes |
| `signal_count` | integer (int32) | Number of independently configured qualified signal sources across this entity. Repeated findings for one type, Sheet, and agent configuration count once. This is not the history-entry count. | `3` | No |
| `signal_sources` | array of SignalSource object | Qualified source identities shown in the portal signal stack. Grouped by type, Sheet, and Signal Agent; not the complete finding history. Uses the same source set as signal\_count. | `[]` | No |
| `source_sheet` | Sheet object | Source Sheet for the selected row, or null. This is not the complete list of Sheet memberships. | — | Yes |

## Account

| API field | Type | Meaning | Example | Nullable |
| - | - | - | - | - |
| `country_code` | string | Company country as an ISO 3166-1 alpha-2 code; empty string when unavailable. | `"US"` | No |
| `domain` | string | Company domain without a scheme; empty string when unavailable. | `"acme.com"` | No |
| `evaluation` | Evaluation object | Selected portal evaluation and a page of its exact linked findings, or null. Qualification and AI score are returned only inside this evaluation. | — | Yes |
| `found_at` | string (RFC 3339 timestamp) | When the Account first entered the portal Directory. This is entity-level Date found, not the selected finding date. | `"2026-08-01T08:00:00Z"` | Yes |
| `id` | string | Stable Account identifier; use this ID to read Account signal history. | `"co_acme"` | No |
| `latest_signal_at` | string (RFC 3339 timestamp) | Time the latest visible material occurrence was saved for this entity, including rejected or unclear findings. Null when none exists. Source filters do not reduce this entity-wide statistic. | `"2026-11-15T08:00:00Z"` | Yes |
| `name` | string | Company display name; empty string when unavailable. | `"Acme"` | No |
| `profile` | Profile object | Company LinkedIn profile, or null when unavailable. | — | Yes |
| `signal_count` | integer (int32) | Number of independently configured qualified signal sources across this entity. Repeated findings for one type, Sheet, and agent configuration count once. This is not the history-entry count. | `3` | No |
| `signal_sources` | array of SignalSource object | Qualified source identities shown in the portal signal stack. Grouped by type, Sheet, and Signal Agent; not the complete finding history. Uses the same source set as signal\_count. | `[]` | No |
| `source_sheet` | Sheet object | Source Sheet for the selected row, or null. This is not the complete list of Sheet memberships. | — | Yes |

## SignalHistoryEntry

| API field | Type | Meaning | Example | Nullable |
| - | - | - | - | - |
| `ai_score` | Score object | AI score recorded for this finding, or null when uncalculated. It is not replaced by the entity current score. | — | Yes |
| `found_at` | string (RFC 3339 timestamp) | When this finding was first saved in Plyne. Used for history ordering and date filtering. | `"2026-08-10T08:00:00Z"` | No |
| `id` | string | Stable identifier of the saved material finding. Use this ID to identify the same finding inside an evaluation. | `"sig_finding"` | No |
| `name` | string | Human-readable signal name following portal labels. | `"Post Engagers"` | No |
| `observed_at` | string (RFC 3339 timestamp) | Observation timestamp from source evidence, or null when unavailable. It can differ from found\_at, particularly for older findings. | `"2026-08-09T12:00:00Z"` | Yes |
| `qualification` | Qualification object | Qualification recorded for this finding, or null. Historical unqualified and unclear decisions remain readable. | — | Yes |
| `reason` | string | Explanation recorded for this exact finding; empty string when unavailable. | `"Engagement matches the configured topic."` | No |
| `references` | array of Reference object | Available source links for this finding, deduplicated by URL and limited to at most 20. Empty array when no links are available. | `[]` | No |
| `signal_agent_id` | string | Signal Agent that produced the finding. Empty string when no Signal Agent is associated with the finding. | `"ag_discovery"` | No |
| `source_sheet` | Sheet object | Sheet that produced this finding, or null when it has no source Sheet. | — | Yes |
| `summary` | string | Summary recorded for this exact finding; empty string when unavailable. | `"Engaged with relevant topic content."` | No |
| `type` | string | Stable signal source ID. Current types and additional historical source IDs are described in Signal Types. | `"topic_engagement_signal"` | No |

## SignalAgent

| API field | Type | Meaning | Example | Nullable |
| - | - | - | - | - |
| `id` | string | Stable identifier of a non-archived Signal Agent configured in the portal. | `"ag_discovery"` | No |
| `next_check_at` | string (RFC 3339 timestamp) | Next scheduled check time, or null when none is scheduled. | `"2026-11-17T08:00:00Z"` | Yes |
| `schedule` | string | Human-readable schedule label such as daily, 4x daily, or manual. This is a display string rather than a cron expression. | `"4x daily"` | No |
| `sheet` | Sheet object | Sheet associated with the agent, or null when no named Sheet is available. | — | Yes |
| `status` | string; active, paused | Whether this agent has an enabled recurring schedule. Active does not mean a run is currently executing. | `"active"` | No |

## AccountSummary

| API field | Type | Meaning | Example | Nullable |
| - | - | - | - | - |
| `country_code` | string | Company country as an ISO 3166-1 alpha-2 code; empty string when unavailable. | `"US"` | No |
| `domain` | string | Company domain without a scheme; empty string when unavailable. | `"acme.com"` | No |
| `id` | string | Stable Account identifier; use this ID with the Accounts and Account signal history endpoints. | `"co_acme"` | No |
| `linkedin_url` | string | Company LinkedIn profile URL; empty string when unavailable. | `"https://www.linkedin.com/company/acme"` | No |
| `name` | string | Company display name; empty string when unavailable. | `"Acme"` | No |

## Profile

| API field | Type | Meaning | Example | Nullable |
| - | - | - | - | - |
| `platform` | string | Profile source platform; empty string when unavailable. Values can include linkedin, facebook, and reddit. | `"linkedin"` | No |
| `url` | string | Profile URL; empty string when unavailable. | `"https://www.linkedin.com/in/example"` | No |

## Sheet

| API field | Type | Meaning | Example | Nullable |
| - | - | - | - | - |
| `id` | string | Stable Sheet identifier. | `"sh_buyers"` | No |
| `name` | string | Sheet display name. | `"AI infrastructure buyers"` | No |

## Qualification

| API field | Type | Meaning | Example | Nullable |
| - | - | - | - | - |
| `reason` | string | Short explanation of the qualification decision; empty string when unavailable. | `"Matches the target customer profile."` | No |
| `reasoning` | string | Detailed explanation recorded for this qualification; empty string when unavailable. | `"Role and account context match the configured ICP."` | No |
| `references` | array of Reference object | Source links attached to this qualification decision, distinct from signal finding evidence. At most 20 distinct URLs; empty array when none are available. | `[]` | No |
| `status` | string | Recorded qualification status. Known values are qualified, unqualified, unclear, and error; empty string when no status was recorded. | `"qualified"` | No |

## Score

| API field | Type | Meaning | Example | Nullable |
| - | - | - | - | - |
| `fit` | string; weak, low, medium, high | Score band: weak for 0-29, low for 30-49, medium for 50-79, high for 80-100. | `"high"` | No |
| `reasoning` | string | Explanation associated with this calculated score; empty string when unavailable. | `"Strong role fit and relevant signal evidence."` | No |
| `value` | integer (int32) | Calculated AI score from 0 to 100. A score of zero is valid; the parent ai\_score object is null when no score has been calculated. | `86` | No |

## Reference

| API field | Type | Meaning | Example | Nullable |
| - | - | - | - | - |
| `label` | string | Human-readable source label. | `"Evidence source"` | No |
| `type` | string | Reference category. Public evidence links currently use evidence. | `"evidence"` | No |
| `url` | string | Source URL associated with this record. | `"https://example.com/source"` | No |

## CursorResponse

| API field | Type | Meaning | Example | Nullable |
| - | - | - | - | - |
| `has_more` | boolean | Whether another page of matching records is available. | `false` | No |
| `next` | string | Opaque cursor for the next page; empty string on the final page. | `""` | No |

## Evaluation

| API field | Type | Meaning | Example | Nullable |
| - | - | - | - | - |
| `ai_score` | Score object | This evaluation's recorded score, or null when uncalculated. | — | Yes |
| `findings` | array of SignalHistoryEntry object | Up to 5 visible findings linked to this exact evaluation, newest saved first. Each retains its own assessment and evidence. An independently evaluated finding can appear here as itself. | `[]` | No |
| `findings_cursor` | CursorResponse object | Continue via the corresponding signal history endpoint using evaluation\_id equal to this evaluation's id and cursor.after equal to next. Keep other filters unset. Always present. | — | No |
| `found_at` | string (RFC 3339 timestamp) | When this evaluation was saved. Evaluations can be refreshed and are not immutable revisions. | — | No |
| `id` | string | Saved evaluation occurrence ID. Use it as evaluation\_id on signal history to retrieve its linked findings. | — | No |
| `qualification` | Qualification object | This evaluation's recorded qualification, or null. It is not copied from a different evaluation. | — | Yes |
| `signal_agent_id` | string | Signal Agent associated with this evaluation; empty string when unavailable. | — | No |
| `source_sheet` | Sheet object | Source Sheet for this evaluation, or null. | — | Yes |

## ListAccountEvaluationsResponse

| API field | Type | Meaning | Example | Nullable |
| - | - | - | - | - |
| `cursor` | CursorResponse object | Continuation cursor bound to the workspace, entity, evaluation resource, and filters. Always present. | — | No |
| `data` | array of Evaluation object | One page of saved evaluations, including older decisions. Always an array. | `[]` | No |

## ListAccountSignalsResponse

| API field | Type | Meaning | Example | Nullable |
| - | - | - | - | - |
| `cursor` | CursorResponse object | Pagination metadata. Always present; next is empty and has\_more is false on the final page. | — | No |
| `data` | array of SignalHistoryEntry object | Records on this page. Always an array, including when no records match. | `[]` | No |

## ListAccountsResponse

| API field | Type | Meaning | Example | Nullable |
| - | - | - | - | - |
| `cursor` | CursorResponse object | Pagination metadata. Always present; next is empty and has\_more is false on the final page. | — | No |
| `data` | array of Account object | Records on this page. Always an array, including when no records match. | `[]` | No |

## ListLeadEvaluationsResponse

| API field | Type | Meaning | Example | Nullable |
| - | - | - | - | - |
| `cursor` | CursorResponse object | Continuation cursor bound to the workspace, entity, evaluation resource, and filters. Always present. | — | No |
| `data` | array of Evaluation object | One page of saved evaluations, including older decisions. Always an array. | `[]` | No |

## ListLeadSignalsResponse

| API field | Type | Meaning | Example | Nullable |
| - | - | - | - | - |
| `cursor` | CursorResponse object | Pagination metadata. Always present; next is empty and has\_more is false on the final page. | — | No |
| `data` | array of SignalHistoryEntry object | Records on this page. Always an array, including when no records match. | `[]` | No |

## ListLeadsResponse

| API field | Type | Meaning | Example | Nullable |
| - | - | - | - | - |
| `cursor` | CursorResponse object | Pagination metadata. Always present; next is empty and has\_more is false on the final page. | — | No |
| `data` | array of Lead object | Records on this page. Always an array, including when no records match. | `[]` | No |

## ListSignalAgentsResponse

| API field | Type | Meaning | Example | Nullable |
| - | - | - | - | - |
| `cursor` | CursorResponse object | Pagination metadata. Always present; next is empty and has\_more is false on the final page. | — | No |
| `data` | array of SignalAgent object | Records on this page. Always an array, including when no records match. | `[]` | No |

## SignalSource

| API field | Type | Meaning | Example | Nullable |
| - | - | - | - | - |
| `finding_id` | string | Representative finding ID for this source identity. It is not guaranteed to be the newest finding. | — | No |
| `is_primary` | boolean | Whether this is the source shown first on the selected portal row. Other sources appear in the portal's additional-source stack. | — | No |
| `name` | string | Signal display name used by the portal. | — | No |
| `signal_agent_id` | string | Signal Agent identity associated with this source, or an empty string. | — | No |
| `source_sheet` | Sheet object | Source Sheet for this configured source, or null. | — | Yes |
| `type` | string | Stable signal source type ID. | — | No |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.