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

# Affinity: V2 Persons Search Post

> Search people (contacts) in your Affinity CRM by keyword or field filters, with sorting. Includes inputs, outputs, SDK V2 examples, and Deepline cost.

Search people (contacts) in your Affinity CRM by keyword or field filters, with sorting.

> [!NOTE]
>
> Tool ID: `affinity_v2_persons_search_post`

## Run this action

Use the TypeScript SDK for one call. Use `ctx.tools.execute(...)` inside a Play for durable calls, scheduled calls, or CSV processing.

```ts theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
import { Deepline } from 'deepline';

const deepline = await Deepline.connect();
const result = await deepline.tools.execute(
  'affinity_v2_persons_search_post',
  {
    "fieldIds": [
      "field_123"
    ],
    "fieldTypes": [
      "enriched"
    ],
    "cursor": "cursor_123"
  },
);

console.log(result.toolResponse.raw);
```

### CLI

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline tools execute affinity_v2_persons_search_post --input '{
  "fieldIds": [
    "field_123"
  ],
  "fieldTypes": [
    "enriched"
  ],
  "cursor": "cursor_123"
}' --json
```

## Example response

The SDK returns this shape at `result.toolResponse.raw`. The example values illustrate the response.

```json theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
{
  "data": {
    "data": [
      {
        "id": 123,
        "firstName": "Jane",
        "lastName": "Doe",
        "primaryEmailAddress": "jane.doe@example.com",
        "emailAddresses": [
          "jane.doe@example.com"
        ],
        "type": "internal"
      }
    ],
    "pagination": {
      "prevUrl": "https://example.com",
      "nextUrl": "https://example.com"
    }
  }
}
```

Use `deepline describe affinity_v2_persons_search_post --json` for the latest machine-readable contract.

## Input reference

Search criteria for filtering, sorting, and searching. All fields are optional — omitting the body returns all results with default pagination.

| Name | Type | Required | Default | Details |
| - | - | - | - | - |
| `payload.fieldIds` | `array` | No | — | Specific field IDs for which to return field data on each Person. Cannot be used together with `fieldTypes`. Use one or the other. Use `GET /v2/persons/fields` to discover available field IDs. |
| `payload.fieldTypes` | `array` | No | — | A category of fields for which to return field data on each Person. Cannot be used together with `fieldIds`. Use one or the other. |
| `payload.cursor` | `string` | No | — | Cursor for the next or previous page. |
| `payload.limit` | `integer` | No | `100` | Maximum number of Persons to return per page. Format: `int32`. Minimum: 1. Maximum: 100. |
| `payload.totalCount` | `boolean` | No | `false` | When `true`, includes the total count of matching Persons in the pagination response. Adds additional query cost. Use only when needed. |
| `payload.filters` | `object` | No | — | A logical group of filters combined with AND or OR. Groups can be nested to build complex filter trees. Each group may contain up to 50 items. Items can be individual filters or nested filter groups. |
| `payload.sorts` | `array` | No | — | One or more sort criteria, applied in order. Supports up to 5 sort items. Use the relevant fields endpoint for your resource type to discover sortable fields. Minimum items: 1. Maximum items: 5. |
| `payload.search` | `object` | No | — | A single keyword or phrase to match against field values. Multiple terms or comma-separated values are not supported. Use a single search string. |

<details>
  <summary>Show raw input schema</summary>

  ### Input JSON Schema

  ```json theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
  {
    "type": "object",
    "description": "Search criteria for filtering, sorting, and searching. All fields are optional — omitting the body returns all results with default pagination.",
    "properties": {
      "fieldIds": {
        "type": "array",
        "description": "Specific field IDs for which to return field data on each Person. Cannot be used together with `fieldTypes`; use one or the other. Use `GET /v2/persons/fields` to discover available field IDs.",
        "items": {
          "type": "string"
        }
      },
      "fieldTypes": {
        "type": "array",
        "description": "A category of fields for which to return field data on each Person. Cannot be used together with `fieldIds`; use one or the other.",
        "items": {
          "type": "string",
          "enum": [
            "enriched",
            "global",
            "relationship-intelligence"
          ]
        }
      },
      "cursor": {
        "type": "string",
        "description": "Cursor for the next or previous page."
      },
      "limit": {
        "type": "integer",
        "description": "Maximum number of Persons to return per page.",
        "default": 100,
        "minimum": 1,
        "maximum": 100,
        "format": "int32"
      },
      "totalCount": {
        "type": "boolean",
        "description": "When `true`, includes the total count of matching Persons in the pagination response. Adds additional query cost; use only when needed.",
        "default": false
      },
      "filters": {
        "type": "object",
        "description": "A logical group of filters combined with AND or OR. Groups can be nested to build complex filter trees. Each group may contain up to 50 items. Items can be individual filters or nested filter groups.",
        "properties": {
          "operator": {
            "type": "string",
            "description": "The logical operator applied to all filters in this group",
            "enum": [
              "and",
              "or"
            ]
          },
          "filters": {
            "type": "array",
            "description": "A list of filters or nested filter groups.",
            "minItems": 0,
            "maxItems": 50,
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          }
        },
        "required": [
          "operator",
          "filters"
        ],
        "additionalProperties": false
      },
      "sorts": {
        "type": "array",
        "description": "One or more sort criteria, applied in order. Supports up to 5 sort items. Use the relevant fields endpoint for your resource type to discover sortable fields.",
        "minItems": 1,
        "maxItems": 5,
        "items": {
          "type": "object",
          "description": "A single sort criterion. Up to 5 sorts may be specified and are applied in order. Use the relevant fields endpoint for your resource type to discover sortable fields and valid `attributeId` values.",
          "properties": {
            "fieldId": {
              "type": "string",
              "description": "The ID of the field to sort on",
              "minLength": 1
            },
            "attributeId": {
              "type": "string",
              "description": "The ID of the attribute to sort on. Required for some fields such as relationship intelligence fields. Use the relevant fields endpoint for your resource type to discover which fields require an `attributeId` and what values are valid.",
              "minLength": 1
            },
            "direction": {
              "type": "string",
              "description": "The sort direction",
              "enum": [
                "asc",
                "desc"
              ]
            }
          },
          "required": [
            "fieldId",
            "direction"
          ],
          "additionalProperties": false
        }
      },
      "search": {
        "type": "object",
        "description": "A single keyword or phrase to match against field values. Multiple terms or comma-separated values are not supported; use a single search string.",
        "properties": {
          "term": {
            "type": "string",
            "description": "The text to search for. Minimum 3 characters.",
            "minLength": 3
          },
          "fieldIds": {
            "type": "array",
            "description": "The IDs of additional fields to match the term against, extending the default identity search. Use the relevant fields endpoint for your resource type to discover available field IDs. Supports up to 100 field IDs. Fields with a `valueType` of `datetime` are not searchable and are silently ignored if included.",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "term"
        ],
        "additionalProperties": false
      }
    },
    "required": [],
    "additionalProperties": false
  }
  ```
</details>

## Output reference

| Name | Type | Required | Default | Details |
| - | - | - | - | - |
| `result.data` | `object` | Yes | — | — |
| `result.data.data` | `array` | Yes | — | Maximum items: 100. |
| `result.data.data[].id` | `integer` | Yes | — | Format: `int64`. Minimum: 1. Maximum: 9007199254740991. |
| `result.data.data[].firstName` | `string` | Yes | — | — |
| `result.data.data[].lastName` | `string \| null` | Yes | — | — |
| `result.data.data[].primaryEmailAddress` | `string \| null` | Yes | — | Format: `email`. |
| `result.data.data[].emailAddresses` | `array` | Yes | — | — |
| `result.data.data[].type` | `"internal" \| "external"` | Yes | — | Allowed: `internal`, `external`. |
| `result.data.data[].fields` | `array` | No | — | — |
| `result.data.data[].fields[].id` | `string` | Yes | — | — |
| `result.data.data[].fields[].name` | `string` | Yes | — | — |
| `result.data.data[].fields[].type` | `"enriched" \| "global" \| "list" \| "relationship-intelligence" \| "hidden"` | Yes | — | Allowed: `enriched`, `global`, `list`, `relationship-intelligence`, `hidden`. |
| `result.data.data[].fields[].enrichmentSource` | `"affinity-data" \| "dealroom" \| "eventbrite" \| "mailchimp" \| null` | Yes | — | Allowed: `affinity-data`, `dealroom`, `eventbrite`, `mailchimp`, `null`. |
| `result.data.data[].fields[].value` | `object` | Yes | — | — |
| `result.data.data[].fields[].value.type` | `"company-multi"` | Yes | — | — |
| `result.data.data[].fields[].value.data` | `array \| null` | Yes | — | — |
| `result.data.data[].fields[].value.data[].id` | `integer` | Yes | — | — |
| `result.data.data[].fields[].value.data[].name` | `string` | Yes | — | — |
| `result.data.data[].fields[].value.data[].domain` | `string \| null` | Yes | — | — |
| `result.data.data[].fields[].value.totalCount` | `integer` | No | — | Format: `int32`. Minimum: 0. Maximum: 2147483647. |
| `result.data.data[].fields[].value.data[].dropdownOptionId` | `integer` | Yes | — | — |
| `result.data.data[].fields[].value.data[].text` | `string` | Yes | — | — |
| `result.data.data[].fields[].value.data[].streetAddress` | `string \| null` | Yes | — | — |
| `result.data.data[].fields[].value.data[].city` | `string \| null` | Yes | — | — |
| `result.data.data[].fields[].value.data[].state` | `string \| null` | Yes | — | — |
| `result.data.data[].fields[].value.data[].country` | `string \| null` | Yes | — | — |
| `result.data.data[].fields[].value.data[].continent` | `string \| null` | Yes | — | — |
| `result.data.data[].fields[].value.data[].firstName` | `string \| null` | Yes | — | — |
| `result.data.data[].fields[].value.data[].lastName` | `string \| null` | Yes | — | — |
| `result.data.data[].fields[].value.data[].primaryEmailAddress` | `string \| null` | Yes | — | — |
| `result.data.data[].fields[].value.data[].type` | `"internal" \| "collaborator" \| "external"` | Yes | — | — |
| `result.data.pagination` | `object` | Yes | — | — |
| `result.data.pagination.prevUrl` | `string \| null` | No | — | Format: `uri`. |
| `result.data.pagination.nextUrl` | `string \| null` | No | — | Format: `uri`. |
| `result.meta` | `object` | No | — | — |

> [!NOTE]
>
> This output schema is too large for an inline display. Read the complete live contract with `deepline describe affinity_v2_persons_search_post --json`.

## Deepline cost

* Pricing model: `fixed` (per call).
* Estimated Deepline credits: `0` per pricing unit.
* Provider-native pricing may still exist outside Deepline credit billing.

## Related documentation

* [Affinity provider guide](https://deepline.com/docs/providers/affinity/guide.md)
* [SDK V2 quickstart](https://deepline.com/docs/sdk-v2/quickstart.md)
* [SDK reference](https://deepline.com/docs/sdk-v2/sdk-reference.md)
* [Run tools across a CSV](https://deepline.com/docs/sdk-v2/batch-csv.md)


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