> ## 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.

# Opensosdata Actions/bulk Lookup: Inputs, Cost & CLI

> Look up up to 1000 business entities in one native OpenSOSData job. Includes inputs, outputs, pricing notes, Deepline CLI examples, and GTM automation guidance.

## Run in Enrichment Spreadsheet

<Info>
  Use this function as a column step in `deepline enrich`.
</Info>

```bash theme={null}
deepline enrich --input leads.csv --output leads.enriched.csv --with 'result=opensosdata_bulk_lookup:{"entities":"{{entities}}"}' --json
```

<Tip>
  Map payload values to spreadsheet columns with `{{column_name}}` placeholders.
</Tip>

## Input Schema

| Name                          | Type                                           | Required | Default | Description                                                                                |
| ----------------------------- | ---------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------ |
| `payload.entities`            | `array`                                        | Yes      |         | Business entities to look up in one native bulk job.                                       |
| `payload.source`              | `"auto" \| "cache" \| "live"`                  | No       |         | Data source preference for every entity in the job.                                        |
| `payload.cache_preference`    | `"cache_only" \| "cache_first" \| "live_only"` | No       |         |                                                                                            |
| `payload.search_by`           | `"debtor" \| "secured_party"`                  | No       |         |                                                                                            |
| `payload.max_results`         | `integer`                                      | No       |         | Maximum results returned for each submitted entity.                                        |
| `payload.wait_for_completion` | `boolean`                                      | No       | `true`  | Wait briefly for terminal results. Set false to return the recoverable job ID immediately. |
| `payload.poll_interval_ms`    | `integer`                                      | No       | `5000`  |                                                                                            |
| `payload.max_wait_ms`         | `integer`                                      | No       | `30000` | Maximum synchronous wait. Jobs still running after this return a recoverable job\_id.      |

### Allowed values

| Field                      | Allowed values                           |
| -------------------------- | ---------------------------------------- |
| `payload.source`           | `auto`, `cache`, `live`                  |
| `payload.cache_preference` | `cache_only`, `cache_first`, `live_only` |
| `payload.search_by`        | `debtor`, `secured_party`                |

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

  ### Input JSON Schema

  ```json theme={null}
  {
    "type": "object",
    "description": "Submit up to 1000 Secretary of State lookups in one OpenSOSData job and poll it to completion.",
    "properties": {
      "entities": {
        "type": "array",
        "description": "Business entities to look up in one native bulk job.",
        "minItems": 1,
        "maxItems": 1000,
        "items": {
          "type": "object",
          "properties": {
            "entity_name": {
              "type": "string",
              "description": "Business or entity name to look up.",
              "minLength": 2,
              "maxLength": 200
            },
            "state": {
              "type": "string",
              "description": "Two-letter US state code (e.g. 'OH', 'FL').",
              "enum": [
                "AL",
                "AK",
                "AZ",
                "AR",
                "CA",
                "CO",
                "CT",
                "DE",
                "FL",
                "GA",
                "HI",
                "ID",
                "IL",
                "IN",
                "IA",
                "KS",
                "KY",
                "LA",
                "ME",
                "MD",
                "MA",
                "MI",
                "MN",
                "MS",
                "MO",
                "MT",
                "NE",
                "NV",
                "NH",
                "NJ",
                "NM",
                "NY",
                "NC",
                "ND",
                "OH",
                "OK",
                "OR",
                "PA",
                "RI",
                "SC",
                "SD",
                "TN",
                "TX",
                "UT",
                "VT",
                "VA",
                "WA",
                "WV",
                "WI",
                "WY",
                "DC",
                "PR"
              ]
            }
          },
          "required": [
            "entity_name",
            "state"
          ],
          "additionalProperties": false
        }
      },
      "source": {
        "type": "string",
        "description": "Data source preference for every entity in the job.",
        "enum": [
          "auto",
          "cache",
          "live"
        ]
      },
      "cache_preference": {
        "type": "string",
        "enum": [
          "cache_only",
          "cache_first",
          "live_only"
        ]
      },
      "search_by": {
        "type": "string",
        "enum": [
          "debtor",
          "secured_party"
        ]
      },
      "max_results": {
        "type": "integer",
        "description": "Maximum results returned for each submitted entity.",
        "minimum": 1,
        "maximum": 30
      },
      "wait_for_completion": {
        "type": "boolean",
        "description": "Wait briefly for terminal results. Set false to return the recoverable job ID immediately.",
        "default": true
      },
      "poll_interval_ms": {
        "type": "integer",
        "default": 5000,
        "minimum": 250,
        "maximum": 30000
      },
      "max_wait_ms": {
        "type": "integer",
        "description": "Maximum synchronous wait. Jobs still running after this return a recoverable job_id.",
        "default": 30000,
        "minimum": 1000,
        "maximum": 30000
      }
    },
    "required": [
      "entities"
    ],
    "additionalProperties": false
  }
  ```
</details>

## Output Schema

| Name               | Type      | Required | Default | Description |
| ------------------ | --------- | -------- | ------- | ----------- |
| `result.job_id`    | `string`  | Yes      |         |             |
| `result.status`    | `string`  | Yes      |         |             |
| `result.total`     | `integer` | Yes      |         |             |
| `result.completed` | `integer` | Yes      |         |             |
| `result.failed`    | `integer` | Yes      |         |             |
| `result.results`   | `array`   | Yes      |         |             |

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

  ### Output JSON Schema

  ```json theme={null}
  {
    "type": "object",
    "properties": {
      "job_id": {
        "type": "string"
      },
      "status": {
        "type": "string"
      },
      "total": {
        "type": "integer"
      },
      "completed": {
        "type": "integer"
      },
      "failed": {
        "type": "integer"
      },
      "results": {
        "type": "array",
        "items": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "entity_name": {
                  "type": "string"
                },
                "state": {
                  "type": "string"
                },
                "success": {
                  "type": "boolean"
                },
                "data": {
                  "type": "object",
                  "properties": {
                    "entityName": {
                      "type": "string"
                    },
                    "entityType": {
                      "type": "string"
                    },
                    "entityId": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    },
                    "officers": {
                      "type": "array",
                      "items": {}
                    }
                  },
                  "required": [
                    "entityName",
                    "entityType",
                    "entityId",
                    "status",
                    "officers"
                  ],
                  "additionalProperties": true
                }
              },
              "required": [
                "entity_name",
                "state",
                "success",
                "data"
              ],
              "additionalProperties": true
            },
            {
              "type": "object",
              "properties": {
                "entity_name": {
                  "type": "string"
                },
                "state": {
                  "type": "string"
                },
                "success": {
                  "type": "boolean"
                },
                "error": {
                  "type": "string"
                }
              },
              "required": [
                "entity_name",
                "state",
                "success",
                "error"
              ],
              "additionalProperties": true
            }
          ]
        }
      }
    },
    "required": [
      "job_id",
      "status",
      "total",
      "completed",
      "failed",
      "results"
    ],
    "additionalProperties": true
  }
  ```
</details>

## Advanced: Direct CLI

<Info>
  Use direct execution for single payload debugging.
</Info>

```bash theme={null}
deepline tools execute opensosdata_bulk_lookup --payload '{
  "entities": "array"
}' --json
```

### CLI flags

| Flag                        | Description                                         |
| --------------------------- | --------------------------------------------------- |
| `--json`                    | Print machine-readable output.                      |
| `--wait`                    | Wait for terminal provider status when supported.   |
| `--debug`                   | Enable wait mode with additional status/log output. |
| `--wait-timeout SECONDS`    | Max seconds to wait in wait mode.                   |
| `--poll-interval SECONDS`   | Polling interval in seconds during wait mode.       |
| `--timeout SECONDS`         | Request timeout in seconds.                         |
| `--connect-timeout SECONDS` | Connection timeout in seconds.                      |

## Cost

* Pricing model: `provider_usage` (provider usage).
* Estimated Deepline credits: `0` per pricing unit.
* Billing mode: `post_deduct`.