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

# Input Parameters - Person Changelog API

## Required Parameters

### `api_key`

| Type     | Description          | Default | Example |
| :------- | :------------------- | :------ | :------ |
| `String` | Your secret API key. |         |         |

Your API Key **must** be included in either the request header or the `api_key` parameter. For more information about request authentication, see the [Authentication](https://docs.peopledatalabs.com/docs/authentication) page.

### `origin_version`

| Type    | Description                                                                                                | Default | Example |
| :------ | :--------------------------------------------------------------------------------------------------------- | :------ | :------ |
| `Float` | The older version for comparison. Must be a valid version and cannot skip versions with `current_version`. |         | `28.1`  |

The valid versions that can be provided for input are:

* Any of the last 3 monthly releases
* OR any of the last 2 quarterly releases

For example as of v28.2, these would be:

* Monthly: `28.2`, `28.1`, `28.0`, `27.2`
* Quarterly: `28.0`, `27.0`, `26.0`

Note that the `origin_version` must be less than `current_version`

### `current_version`

| Type    | Description                                                                                    | Default | Example |
| :------ | :--------------------------------------------------------------------------------------------- | :------ | :------ |
| `Float` | The newer version for comparison. Must be a valid version and consecutive to `origin_version`. |         | `28.2`  |

The valid versions that can be provided for input are:

* Any of the last 3 monthly releases
* OR any of the last 2 quarterly releases

For example as of v28.2, these would be:

* Monthly: `28.2`, `28.1`, `28.0`, `27.2`
* Quarterly: `28.0`, `27.0`, `26.0`

Note that the `current_version` must be greater than `origin_version`

***

## Optional Parameters

<br />

### `type`

<Table align={["left","left","left","left"]}>
  <thead>
    <tr>
      <th style={{ textAlign: "left" }}>
        Type
      </th>

      <th style={{ textAlign: "left" }}>
        Description
      </th>

      <th style={{ textAlign: "left" }}>
        Default
      </th>

      <th style={{ textAlign: "left" }}>
        Example
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td style={{ textAlign: "left" }}>
        `String`
      </td>

      <td style={{ textAlign: "left" }}>
        Specifies the type of changelog to return. This field is required when not submitting a list of ids (via the `ids` field).

        Supported values: `added`, `deleted`, `updated`, `merged`,  `opted_out`
      </td>

      <td style={{ textAlign: "left" }} />

      <td style={{ textAlign: "left" }}>
        `added`
      </td>
    </tr>
  </tbody>
</Table>

<br />

### `ids`

<Table align={["left","left","left","left"]}>
  <thead>
    <tr>
      <th style={{ textAlign: "left" }}>
        Type
      </th>

      <th style={{ textAlign: "left" }}>
        Description
      </th>

      <th style={{ textAlign: "left" }}>
        Default
      </th>

      <th style={{ textAlign: "left" }}>
        Example
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td style={{ textAlign: "left" }}>
        `Array [String]`
      </td>

      <td style={{ textAlign: "left" }}>
        List of person IDs to query changes for.\
        Minimum length: 1\
        Maximum length: 60,000
      </td>

      <td style={{ textAlign: "left" }} />

      <td style={{ textAlign: "left" }}>
        `["123", "qEnOZ5Oh0poWnQ1luFBfVw_0000", "345", "678", "000", "111"]`
      </td>
    </tr>
  </tbody>
</Table>

Passing this field allows you to filter the query results to return only changes in the records containing the specified IDs. The `ids` field must be an passed as an array of IDs (corresponding to PDL person IDs from the [Person Schema](https://docs.peopledatalabs.com/docs/fields#id)). The length of this array must be be at least 1 and less than 60,000.

### `fields_updated`

| Type             | Description                                                                                                                                                                                |
| :--------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Array [String]` | Specifies fields updated between versions (only allowed when passing `type: "updated"` as an input parameter). Each field must match a top-level field in the [Person Schema](https://docs.peopledatalabs.com/docs/fields). |

This field is only supported when providing the `"type": "updated"` in the input query. Fields must be passed as an array of top-level fields from the [Person Schema](https://docs.peopledatalabs.com/docs/fields#id).

Examples of top-level fields are fields like:

* `experience` (but not `experience.company.title`)
* `education` (but not `education.degrees`)
* etc

If any invalid fields are provided, the API will return an error with details on list of valid field names (see [`error.valid_fields_updated`](https://docs.peopledatalabs.com/docs/output-response-person-changelog-api#errorvalid_fields_updated)

<br />

### `scroll_token`

| Type     | Description                                             |
| :------- | :------------------------------------------------------ |
| `String` | Token for pagination when retrieving large result sets. |

<br />

A `scroll_token` returns in every [response from the Person Changelog API](https://docs.peopledatalabs.com/docs/output-response-person-changelog-api#scroll_token) and serves as a placeholder or bookmark for the last record received. For queries with more results than can fit in a single API response (see the [`size`](#size) field), use the `scroll_token` to get the next batch of results.

For example, if you send a query to the Person Changelog API that has 1000 matching records, you will need multiple API calls to retrieve all the records. The `scroll_token` represents how far along you are in that list of records.

Generally, the way to use `scroll_token` is:

1. Send a query to the Person Changelog API.
2. Get a response back containing one batch of records as well as a `scroll_token` response value (if you have already retrieved all the available records in this batch, then the `scroll_token` value will be `null`).
3. Use the same query from Step 1 and the `scroll_token` you just received to make another request to the Person Changelog API.
4. Get another response back with the next batch of records and a new `scroll_token` value.
5. Repeat steps 3 and 4 until you have received the desired number of records or until you receive a 404 status code because pagination is complete and the `scroll_token` key is missing from the response.