openapi.json

{
  "openapi": "3.1.0",
  "info": {
    "title": "NGP VAN API (community OpenAPI spec)",
    "version": "0.1.0",
    "description": "Community-maintained OpenAPI spec for the NGP VAN API, reverse-engineered from https://docs.ngpvan.com, the NGPVAN/van-cli source, and live probing of the sandbox API. The spec describes the API's actual behavior as observed. Where that behavior deviates from the official docs, the comparison is recorded out of band in `x-docs-discrepancy` fields (hidden by most documentation renderers) and summarized in [DISCREPANCIES.md](https://github.com/NickCrews/van-openapi/blob/main/DISCREPANCIES.md); research evidence and confidence notes live in `x-provenance` fields.\n\nSource repository: https://github.com/NickCrews/van-openapi — file issues and corrections there. This spec is not published or endorsed by NGP VAN; for questions about the API itself, contact APIDevelopers@ngpvan.com.\n\nSee [STATUS.md](https://github.com/NickCrews/van-openapi/blob/main/STATUS.md) for per-endpoint research status.\n\n**The API is not callable from a browser.** Its CORS support is incomplete: `api.securevan.com` answers the preflight correctly — reflecting the request origin and allowing the `Authorization` header — but omits `Access-Control-Allow-Origin` from the actual response (observed 2026-08-03; a `200` comes back with no `access-control-*` headers at all). A browser therefore sends the request, receives the response, and then blocks the page from reading it. `Access-Control-Allow-Credentials` is missing as well, which Basic auth would separately require. This affects only browser-based callers; server-side clients such as cURL, Python, or Apps Script are unaffected, since CORS is enforced by the browser rather than the server.",
    "contact": {
      "name": "van-openapi on GitHub",
      "url": "https://github.com/NickCrews/van-openapi"
    }
  },
  "externalDocs": {
    "description": "Source repository (NickCrews/van-openapi)",
    "url": "https://github.com/NickCrews/van-openapi"
  },
  "servers": [
    {
      "url": "https://api.securevan.com/v4",
      "description": "Production / sandbox (the API key determines the committee and database)"
    }
  ],
  "security": [
    {
      "basicAuth": []
    }
  ],
  "tags": [
    {
      "name": "People",
      "description": "Look up, search, create and update people — the contacts and voters that most of the API hangs off."
    },
    {
      "name": "Notes",
      "description": "Free-text notes attached to a person, and the note categories available in the current context."
    },
    {
      "name": "Survey Questions",
      "description": "Survey questions and the canned responses canvassers can record against them."
    },
    {
      "name": "Echoes",
      "description": "Test endpoint for checking auth and connectivity. Writes nothing."
    }
  ],
  "x-traps": [
    {
      "text": "Related collections are `null` unless `$expand` asks for them. A person with no `phones` key is not a person without phones. The `$expand` vocabulary differs between operations — `getPerson` accepts 23 sections, `searchPeople` only four.",
      "see": [
        "person-collections-null-until-expanded",
        "person-expand-set-is-policed"
      ]
    },
    {
      "text": "Six scalar person fields — `nickname`, `website`, `jobTitle` and the three `contactMethodPreference*` fields — are also gated behind `$expand=preferences`. Write one and read the person back plainly and the write looks discarded.",
      "see": [
        "update-writes-every-scalar-field"
      ]
    },
    {
      "text": "`findPerson` returning 404 means \"no match\", not a broken route — and usually means the criteria fell short of the minimum combination rather than that the person is absent.",
      "see": [
        "findPerson",
        "find-below-threshold-is-unmatched"
      ]
    },
    {
      "text": "Phone search wants bare 10 digits. `9072223333` matches; `(907) 222-3333` is accepted and then silently matches nobody.",
      "see": [
        "search-phone-must-be-bare-digits"
      ]
    },
    {
      "text": "Writes append contact methods, they never replace them. Updating a person with a phone adds a phone, so writing back a record you just read duplicates its contact methods.",
      "see": [
        "update-appends-contact-methods"
      ]
    },
    {
      "text": "`mergePerson` is irreversible, and `whatIf` only accepts the literal `true` — any other value is parsed as false and the merge happens for real.",
      "see": [
        "mergePerson",
        "merge-whatif-requires-literal-true"
      ]
    },
    {
      "text": "Text matching is case-insensitive *prefix*, never substring: `helmina` does not find Wilhelmina.",
      "see": [
        "search-is-a-case-insensitive-prefix-match"
      ]
    },
    {
      "text": "A `vanId` in a request body overrides every other criterion, and on the create endpoints a plausible-looking id is echoed back as a match without ever being checked against the database.",
      "see": [
        "find-by-vanid-overrides-criteria",
        "create-echoes-a-plausible-vanid-blindly"
      ]
    },
    {
      "text": "429 carries no `Retry-After`; the suggested wait appears only in the error text, and the limit is per API key across all endpoints.",
      "see": []
    },
    {
      "text": "There is no aggregate or count-by-attribute endpoint. The only total is `count` in the pagination envelope, which counts matches for a query you already had to specify — and every search parameter demands a value, so there is no \"all people\" query to count.",
      "see": [
        "searchPeople"
      ]
    }
  ],
  "paths": {
    "/people/{vanId}": {
      "get": {
        "operationId": "getPerson",
        "summary": "Get a person by VAN id",
        "description": "Retrieves a person record. Related collections (emails, phones, addresses, …) are null unless requested via $expand, and empty arrays when expanded but absent. An unknown, zero, or negative vanId returns the standard 404 error envelope; a non-integer path segment does not match the route and returns an HTML 404 page instead.",
        "tags": [
          "People"
        ],
        "x-keywords": [
          "get person",
          "fetch person",
          "read person",
          "retrieve",
          "by vanId",
          "person details",
          "full record",
          "expand",
          "phones",
          "emails",
          "addresses",
          "custom fields",
          "scores",
          "districts"
        ],
        "x-task": "Read one person in full",
        "parameters": [
          {
            "name": "vanId",
            "in": "path",
            "required": true,
            "description": "VAN id of the person.",
            "x-docs-discrepancy": "Official docs type this path parameter as string (default \"100476252\"); the route only matches integers — a non-integer segment returns an IIS HTML 404 page (observed 2026-08-03).",
            "schema": {
              "type": "integer",
              "format": "int32",
              "minimum": 1
            },
            "example": 102714507
          },
          {
            "name": "$expand",
            "in": "query",
            "description": "Related sections to include, comma-delimited eg 'addresses,emails'. Anything outside this set returns 400 INVALID_PARAMETER with a hint listing the valid values. Two sections in the set are still refused in a My Campaign context: `scores` with 403 FORBIDDEN and `pollingLocation` with 400 BAD_REQUEST.",
            "x-docs-discrepancy": "Official docs list only 10 valid $expand values; the API's own INVALID_PARAMETER hint (observed 2026-08-03) lists these 23.",
            "style": "form",
            "explode": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "addresses",
                  "biography",
                  "cases",
                  "codes",
                  "contributionHistory",
                  "customFields",
                  "customProperties",
                  "disclosureFieldValues",
                  "districts",
                  "electionRecords",
                  "emails",
                  "externalIds",
                  "membershipStatuses",
                  "notes",
                  "organizationRoles",
                  "phones",
                  "pollingLocation",
                  "preferences",
                  "primaryContact",
                  "recordedAddresses",
                  "reportedDemographics",
                  "scores",
                  "suppressions"
                ]
              }
            },
            "example": [
              "emails",
              "phones",
              "addresses"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The person record. Clients that follow redirects can also land here with `text/html` instead: a path segment containing `<`, `>`, `*` or `&` is bounced to the web application's error page, which answers 200 with HTML (see the 302 response).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Person"
                },
                "examples": {
                  "expanded": {
                    "summary": "Sandbox test person with $expand=emails,phones,addresses (abridged: null-only fields omitted)",
                    "value": {
                      "vanId": 102714558,
                      "firstName": "Grace",
                      "lastName": "Testperson",
                      "contactSource": "API",
                      "contactMode": "Person",
                      "salutation": "Grace",
                      "formalSalutation": "Grace Testperson",
                      "envelopeName": "Grace Testperson",
                      "formalEnvelopeName": "Grace Testperson",
                      "isDeceased": false,
                      "dateCreated": "2026-08-03T16:31:00Z",
                      "dateAcquired": "0001-01-01T00:00:00Z",
                      "emails": [
                        {
                          "type": "W",
                          "email": "grace.testperson@example.com",
                          "dateCreated": "2026-08-03T16:31:00Z",
                          "isPreferred": true,
                          "isSubscribed": null,
                          "subscriptionStatus": "N"
                        }
                      ],
                      "phones": [
                        {
                          "phoneId": 1021629,
                          "phoneNumber": "9075550142",
                          "dialingPrefix": "1",
                          "countryCode": "US",
                          "ext": "123",
                          "dateCreated": "2026-08-03T16:31:00Z",
                          "phoneType": "Personal",
                          "deviceType": "Cell",
                          "isPreferred": true,
                          "isBest": true,
                          "isDisclosure": true,
                          "smsOptInStatus": "Opt-In",
                          "phoneOptInStatus": "Opt-In",
                          "isCellPhoneExchange": false,
                          "isCellStatus": null,
                          "tags": null
                        }
                      ],
                      "addresses": [
                        {
                          "addressId": 1206601,
                          "addressLine1": "123 Test St",
                          "addressLine2": "Apt 4",
                          "addressLine3": null,
                          "unitNo": null,
                          "city": "Anchorage",
                          "stateOrProvince": "AK",
                          "zipOrPostalCode": "99501",
                          "geoLocation": null,
                          "countryCode": "US",
                          "preview": "123 Test St Apt 4",
                          "type": "Voting",
                          "isPreferred": true,
                          "isBest": true,
                          "streetAddress": null,
                          "displayMode": "Standardized"
                        },
                        {
                          "addressId": 1206601,
                          "addressLine1": "123 Test St",
                          "addressLine2": "Apt 4",
                          "addressLine3": null,
                          "unitNo": null,
                          "city": "Anchorage",
                          "stateOrProvince": "AK",
                          "zipOrPostalCode": "99501",
                          "geoLocation": null,
                          "countryCode": "US",
                          "preview": "123 Test St Apt 4",
                          "type": "Mailing",
                          "isPreferred": true,
                          "isBest": true,
                          "streetAddress": null,
                          "displayMode": "Standardized"
                        }
                      ]
                    }
                  },
                  "person-collections-null-until-expanded/1": {
                    "summary": "Without $expand, every collection is null — including the email we just wrote.",
                    "description": "Emails, phones and addresses come back null — not empty — unless the request names them in $expand. Expanded, a section the person actually has is an array of entries and a section they lack is an empty array, so null always means 'not requested', never 'none'.",
                    "x-transcript": "person-collections-null-until-expanded",
                    "value": {
                      "vanId": 100000001,
                      "firstName": "Nadia",
                      "lastName": "Okonkwo",
                      "middleName": null,
                      "suffix": null,
                      "title": null,
                      "sourceFileTitle": null,
                      "sourceFileFirstName": null,
                      "sourceFileMiddleName": null,
                      "sourceFileLastName": null,
                      "sourceFileSuffix": null,
                      "contactSource": "API",
                      "contactMode": "Person",
                      "organizationContactCommonName": null,
                      "organizationContactOfficialName": null,
                      "salutation": "Nadia",
                      "formalSalutation": "Nadia Okonkwo",
                      "additionalSalutation": null,
                      "preferredPronoun": null,
                      "pronouns": null,
                      "namePronunciation": null,
                      "envelopeName": "Nadia Okonkwo",
                      "formalEnvelopeName": "Nadia Okonkwo",
                      "additionalEnvelopeName": null,
                      "contactMethodPreferenceCode": null,
                      "contactMethodPreferenceId": null,
                      "contactMethodPreferenceName": null,
                      "assistantName": null,
                      "nickname": null,
                      "website": null,
                      "professionalSuffix": null,
                      "party": null,
                      "employer": null,
                      "occupation": null,
                      "jobTitle": null,
                      "sex": null,
                      "dateOfBirth": null,
                      "isDeceased": false,
                      "dateCreated": "2026-01-01T00:00:00Z",
                      "dateAcquired": "0001-01-01T00:00:00Z",
                      "selfReportedRace": null,
                      "selfReportedEthnicity": null,
                      "selfReportedRaces": null,
                      "selfReportedEthnicities": null,
                      "selfReportedGenders": null,
                      "selfReportedSexualOrientations": null,
                      "selfReportedLanguagePreference": null,
                      "selfReportedLanguagePreferences": null,
                      "emails": null,
                      "phones": null,
                      "addresses": null,
                      "recordedAddresses": null,
                      "pollingLocation": null,
                      "earlyVoteLocation": null,
                      "identifiers": null,
                      "codes": null,
                      "customFields": null,
                      "primaryCustomField": null,
                      "contributionSummary": null,
                      "suppressions": null,
                      "caseworkCases": null,
                      "caseworkIssues": null,
                      "caseworkStories": null,
                      "notes": null,
                      "scores": null,
                      "customProperties": null,
                      "electionRecords": null,
                      "membershipStatus": null,
                      "organizationRoles": null,
                      "districts": null,
                      "surveyQuestionResponses": null,
                      "finderNumber": null,
                      "biographyImageUrl": null,
                      "biographyText": null,
                      "biographyHtml": null,
                      "primaryContact": null
                    }
                  },
                  "person-collections-null-until-expanded/2": {
                    "summary": "Expanded, the email appears and the phones the person lacks are [] rather than null.",
                    "description": "Emails, phones and addresses come back null — not empty — unless the request names them in $expand. Expanded, a section the person actually has is an array of entries and a section they lack is an empty array, so null always means 'not requested', never 'none'.",
                    "x-transcript": "person-collections-null-until-expanded",
                    "value": {
                      "vanId": 100000001,
                      "firstName": "Nadia",
                      "lastName": "Okonkwo",
                      "middleName": null,
                      "suffix": null,
                      "title": null,
                      "sourceFileTitle": null,
                      "sourceFileFirstName": null,
                      "sourceFileMiddleName": null,
                      "sourceFileLastName": null,
                      "sourceFileSuffix": null,
                      "contactSource": "API",
                      "contactMode": "Person",
                      "organizationContactCommonName": null,
                      "organizationContactOfficialName": null,
                      "salutation": "Nadia",
                      "formalSalutation": "Nadia Okonkwo",
                      "additionalSalutation": null,
                      "preferredPronoun": null,
                      "pronouns": null,
                      "namePronunciation": null,
                      "envelopeName": "Nadia Okonkwo",
                      "formalEnvelopeName": "Nadia Okonkwo",
                      "additionalEnvelopeName": null,
                      "contactMethodPreferenceCode": null,
                      "contactMethodPreferenceId": null,
                      "contactMethodPreferenceName": null,
                      "assistantName": null,
                      "nickname": null,
                      "website": null,
                      "professionalSuffix": null,
                      "party": null,
                      "employer": null,
                      "occupation": null,
                      "jobTitle": null,
                      "sex": null,
                      "dateOfBirth": null,
                      "isDeceased": false,
                      "dateCreated": "2026-01-01T00:00:00Z",
                      "dateAcquired": "0001-01-01T00:00:00Z",
                      "selfReportedRace": null,
                      "selfReportedEthnicity": null,
                      "selfReportedRaces": null,
                      "selfReportedEthnicities": null,
                      "selfReportedGenders": null,
                      "selfReportedSexualOrientations": null,
                      "selfReportedLanguagePreference": null,
                      "selfReportedLanguagePreferences": null,
                      "emails": [
                        {
                          "type": "P",
                          "email": "nadia.okonkwo@example.com",
                          "dateCreated": "2026-01-01T00:00:00Z",
                          "isPreferred": true,
                          "isSubscribed": true,
                          "subscriptionStatus": "S"
                        }
                      ],
                      "phones": [],
                      "addresses": null,
                      "recordedAddresses": null,
                      "pollingLocation": null,
                      "earlyVoteLocation": null,
                      "identifiers": null,
                      "codes": null,
                      "customFields": null,
                      "primaryCustomField": null,
                      "contributionSummary": null,
                      "suppressions": null,
                      "caseworkCases": null,
                      "caseworkIssues": null,
                      "caseworkStories": null,
                      "notes": null,
                      "scores": null,
                      "customProperties": null,
                      "electionRecords": null,
                      "membershipStatus": null,
                      "organizationRoles": null,
                      "districts": null,
                      "surveyQuestionResponses": null,
                      "finderNumber": null,
                      "biographyImageUrl": null,
                      "biographyText": null,
                      "biographyHtml": null,
                      "primaryContact": null
                    }
                  }
                }
              },
              "text/html": {
                "schema": {
                  "type": "string"
                },
                "x-provenance": {
                  "lastProbed": "2026-08-03",
                  "note": "The VAN web app's \"Oops...something went wrong\" page, reached by following the request-validation 302. Documented so redirect-following clients (including the schemathesis stateful phase, which found it) conform."
                }
              }
            }
          },
          "302": {
            "$ref": "#/components/responses/RequestValidationRedirect"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/PersonNotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "Related collections are null until $expand asks for them",
            "source": "# Emails, phones and addresses come back null — not empty — unless the\n# request names them in $expand. Expanded, a section the person actually has\n# is an array of entries and a section they lack is an empty array, so null\n# always means 'not requested', never 'none'.\n\n# A person with one email and nothing else.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Nadia\",\n    \"lastName\": \"Okonkwo\",\n    \"emails\": [\n      {\n        \"email\": \"nadia.okonkwo@example.com\"\n      }\n    ]\n  }'\n# → 201  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Stored\"\n# }\n\n# Without $expand, every collection is null — including the email we just\n# wrote.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people/100000001' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 200\n# {\n#   \"vanId\": 100000001,\n#   \"firstName\": \"Nadia\",\n#   \"lastName\": \"Okonkwo\",\n#   \"middleName\": null,\n#   \"suffix\": null,\n#   \"title\": null,\n#   \"sourceFileTitle\": null,\n#   \"sourceFileFirstName\": null,\n#   \"sourceFileMiddleName\": null,\n#   \"sourceFileLastName\": null,\n#   \"sourceFileSuffix\": null,\n#   \"contactSource\": \"API\",\n#   \"contactMode\": \"Person\",\n#   \"organizationContactCommonName\": null,\n#   \"organizationContactOfficialName\": null,\n#   \"salutation\": \"Nadia\",\n#   \"formalSalutation\": \"Nadia Okonkwo\",\n#   \"additionalSalutation\": null,\n#   \"preferredPronoun\": null,\n#   \"pronouns\": null,\n#   \"namePronunciation\": null,\n#   \"envelopeName\": \"Nadia Okonkwo\",\n#   \"formalEnvelopeName\": \"Nadia Okonkwo\",\n#   \"additionalEnvelopeName\": null,\n#   \"contactMethodPreferenceCode\": null,\n#   \"contactMethodPreferenceId\": null,\n#   \"contactMethodPreferenceName\": null,\n#   \"assistantName\": null,\n#   \"nickname\": null,\n#   \"website\": null,\n#   \"professionalSuffix\": null,\n#   \"party\": null,\n#   \"employer\": null,\n#   \"occupation\": null,\n#   \"jobTitle\": null,\n#   \"sex\": null,\n#   \"dateOfBirth\": null,\n#   \"isDeceased\": false,\n#   \"dateCreated\": \"2026-01-01T00:00:00Z\",\n#   \"dateAcquired\": \"0001-01-01T00:00:00Z\",\n#   \"selfReportedRace\": null,\n#   \"selfReportedEthnicity\": null,\n#   \"selfReportedRaces\": null,\n#   \"selfReportedEthnicities\": null,\n#   \"selfReportedGenders\": null,\n#   \"selfReportedSexualOrientations\": null,\n#   \"selfReportedLanguagePreference\": null,\n#   \"selfReportedLanguagePreferences\": null,\n#   \"emails\": null,\n#   \"phones\": null,\n#   \"addresses\": null,\n#   \"recordedAddresses\": null,\n#   \"pollingLocation\": null,\n#   \"earlyVoteLocation\": null,\n#   \"identifiers\": null,\n#   \"codes\": null,\n#   \"customFields\": null,\n#   \"primaryCustomField\": null,\n#   \"contributionSummary\": null,\n#   \"suppressions\": null,\n#   \"caseworkCases\": null,\n#   \"caseworkIssues\": null,\n#   \"caseworkStories\": null,\n#   \"notes\": null,\n#   \"scores\": null,\n#   \"customProperties\": null,\n#   \"electionRecords\": null,\n#   \"membershipStatus\": null,\n#   \"organizationRoles\": null,\n#   \"districts\": null,\n#   \"surveyQuestionResponses\": null,\n#   \"finderNumber\": null,\n#   \"biographyImageUrl\": null,\n#   \"biographyText\": null,\n#   \"biographyHtml\": null,\n#   \"primaryContact\": null\n# }\n\n# Expanded, the email appears and the phones the person lacks are [] rather\n# than null.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people/100000001?%24expand=emails%2Cphones' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 200\n# {\n#   \"vanId\": 100000001,\n#   \"firstName\": \"Nadia\",\n#   \"lastName\": \"Okonkwo\",\n#   \"middleName\": null,\n#   \"suffix\": null,\n#   \"title\": null,\n#   \"sourceFileTitle\": null,\n#   \"sourceFileFirstName\": null,\n#   \"sourceFileMiddleName\": null,\n#   \"sourceFileLastName\": null,\n#   \"sourceFileSuffix\": null,\n#   \"contactSource\": \"API\",\n#   \"contactMode\": \"Person\",\n#   \"organizationContactCommonName\": null,\n#   \"organizationContactOfficialName\": null,\n#   \"salutation\": \"Nadia\",\n#   \"formalSalutation\": \"Nadia Okonkwo\",\n#   \"additionalSalutation\": null,\n#   \"preferredPronoun\": null,\n#   \"pronouns\": null,\n#   \"namePronunciation\": null,\n#   \"envelopeName\": \"Nadia Okonkwo\",\n#   \"formalEnvelopeName\": \"Nadia Okonkwo\",\n#   \"additionalEnvelopeName\": null,\n#   \"contactMethodPreferenceCode\": null,\n#   \"contactMethodPreferenceId\": null,\n#   \"contactMethodPreferenceName\": null,\n#   \"assistantName\": null,\n#   \"nickname\": null,\n#   \"website\": null,\n#   \"professionalSuffix\": null,\n#   \"party\": null,\n#   \"employer\": null,\n#   \"occupation\": null,\n#   \"jobTitle\": null,\n#   \"sex\": null,\n#   \"dateOfBirth\": null,\n#   \"isDeceased\": false,\n#   \"dateCreated\": \"2026-01-01T00:00:00Z\",\n#   \"dateAcquired\": \"0001-01-01T00:00:00Z\",\n#   \"selfReportedRace\": null,\n#   \"selfReportedEthnicity\": null,\n#   \"selfReportedRaces\": null,\n#   \"selfReportedEthnicities\": null,\n#   \"selfReportedGenders\": null,\n#   \"selfReportedSexualOrientations\": null,\n#   \"selfReportedLanguagePreference\": null,\n#   \"selfReportedLanguagePreferences\": null,\n#   \"emails\": [\n#     {\n#       \"type\": \"P\",\n#       \"email\": \"nadia.okonkwo@example.com\",\n#       \"dateCreated\": \"2026-01-01T00:00:00Z\",\n#       \"isPreferred\": true,\n#       \"isSubscribed\": true,\n#       \"subscriptionStatus\": \"S\"\n#     }\n#   ],\n#   \"phones\": [],\n#   \"addresses\": null,\n#   \"recordedAddresses\": null,\n#   \"pollingLocation\": null,\n#   \"earlyVoteLocation\": null,\n#   \"identifiers\": null,\n#   \"codes\": null,\n#   \"customFields\": null,\n#   \"primaryCustomField\": null,\n#   \"contributionSummary\": null,\n#   \"suppressions\": null,\n#   \"caseworkCases\": null,\n#   \"caseworkIssues\": null,\n#   \"caseworkStories\": null,\n#   \"notes\": null,\n#   \"scores\": null,\n#   \"customProperties\": null,\n#   \"electionRecords\": null,\n#   \"membershipStatus\": null,\n#   \"organizationRoles\": null,\n#   \"districts\": null,\n#   \"surveyQuestionResponses\": null,\n#   \"finderNumber\": null,\n#   \"biographyImageUrl\": null,\n#   \"biographyText\": null,\n#   \"biographyHtml\": null,\n#   \"primaryContact\": null\n# }",
            "x-transcript": "person-collections-null-until-expanded"
          },
          {
            "lang": "Shell",
            "label": "$expand values are policed, and two valid ones are refused here",
            "source": "# A value outside the documented set is refused with INVALID_PARAMETER and a\n# hint listing every valid value. Two values inside the set are still\n# refused in a My Campaign context: `scores` with 403 and `pollingLocation`\n# with 400.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Emeka\",\n    \"lastName\": \"Adeyemi\"\n  }'\n# → 201  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Stored\"\n# }\n\n# An invented section. The hint in the refusal is the authoritative list.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people/100000001?%24expand=frisbees' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 400\n# {\n#   \"errors\": [\n#     {\n#       \"code\": \"INVALID_PARAMETER\",\n#       \"text\": \"'frisbees' is not a valid argument for the '$expand' parameter\",\n#       \"properties\": [\n#         \"$expand\"\n#       ],\n#       \"hint\": \"The only valid expand sections are: 'contributionHistory', 'addresses', 'phones', 'emails', 'codes', 'customFields', 'externalIds', 'preferences', 'recordedAddresses', 'reportedDemographics', 'suppressions', 'cases', 'customProperties', 'districts', 'electionRecords', 'membershipStatuses', 'notes', 'organizationRoles', 'scores', 'disclosureFieldValues', 'primaryContact', 'pollingLocation', 'biography'\"\n#     }\n#   ]\n# }\n\n# `scores` is in the valid set, but this context is refused it outright.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people/100000001?%24expand=scores' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 403\n# {\n#   \"errors\": [\n#     {\n#       \"code\": \"FORBIDDEN\",\n#       \"text\": \"May not request 'scores'\"\n#     }\n#   ]\n# }\n\n# `pollingLocation` is also in the set, and also refused — but as a 400.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people/100000001?%24expand=pollingLocation' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 400\n# {\n#   \"errors\": [\n#     {\n#       \"code\": \"BAD_REQUEST\",\n#       \"text\": \"May not request 'pollingLocation' in this context\"\n#     }\n#   ]\n# }",
            "x-transcript": "person-expand-set-is-policed"
          },
          {
            "lang": "Shell",
            "label": "Unknown ids 404 with the envelope; a non-integer id gets HTML",
            "source": "# An unknown, zero or negative vanId returns the standard 404 error\n# envelope. A path segment that is not an integer never reaches the handler\n# — the route does not match, and the answer is an HTML 404 page instead.\n\n# An id no record has ever had.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people/2147483646' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 404\n# {\n#   \"errors\": [\n#     {\n#       \"code\": \"NOT_FOUND\",\n#       \"text\": \"The specified resource cannot be found.\"\n#     }\n#   ]\n# }\n\n# Zero is refused the same way.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people/0' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 404\n# {\n#   \"errors\": [\n#     {\n#       \"code\": \"NOT_FOUND\",\n#       \"text\": \"The specified resource cannot be found.\"\n#     }\n#   ]\n# }\n\n# A non-integer segment matches no route: HTML, not the JSON envelope.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people/abc' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 404\n# <!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Strict//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd\">\r\n<html xmlns=\"http://www.w3.org/1999/xhtml\">\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=iso-8859-1\"/>\r\n<title>404 - File or directory not found.</title>\r\n<style type=\"text/css\">\r\n<!--\r\nbody{margin:0;font-size:.7em;font-family:Verdana, Arial, Helvetica, sans-serif;background:#EEEEEE;}\r\nfieldset{padding:0 15px 10px 15px;} \r\nh1{font-size:2.4em;margin:0;color:#FFF;}\r\nh2{font-size:1.7em;margin:0;color:#CC0000;} \r\nh3{font-size:1.2em;margin:10px 0 0 0;color:#000000;} \r\n#header{width:96%;margin:0 0 0 0;padding:6px 2% 6px 2%;font-family:\"trebuchet MS\", Verdana, sans-serif;color:#FFF;\r\nbackground-color:#555555;}\r\n#content{margin:0 0 0 2%;position:relative;}\r\n.content-container{background:#FFF;width:96%;margin-top:8px;padding:10px;position:relative;}\r\n-->\r\n</style>\r\n</head>\r\n<body>\r\n<div id=\"header\"><h1>Server Error</h1></div>\r\n<div id=\"content\">\r\n <div class=\"content-container\"><fieldset>\r\n  <h2>404 - File or directory not found.</h2>\r\n  <h3>The resource you are looking for might have been removed, had its name changed, or is temporarily unavailable.</h3>\r\n </fieldset></div>\r\n</div>\r\n</body>\r\n</html>\r\n",
            "x-transcript": "person-unknown-ids-404-two-ways"
          }
        ]
      },
      "post": {
        "operationId": "updatePerson",
        "summary": "Update an existing person",
        "description": "Merges the payload into an existing person record, addressed by id — no matching, no minimum-criteria threshold, and no chance of writing to the wrong duplicate. **This is the endpoint to write through once you have identified a person yourself** (e.g. from GET /people); POST /people/findOrCreate resolves ambiguity silently and creates duplicates below the match threshold.\n\nFields left out of the body keep their current values, and `emails`, `phones` and `addresses` are appended to what is already there rather than replacing it — there is no way to remove a contact method through this endpoint. The append is idempotent for an identical value: re-sending an email address the person already has — in a later update or twice in one body — does not create a second entry (observed via $expand=emails, 2026-08-08).\n\nOutcomes:\n\n- **The vanId exists** — **302 Found** with a `Location` header pointing back at `/people/{vanId}` and a match-stub body: the same shape POST /people/find returns, **not** the updated person.\n- **The body is empty (`{}`)** — accepted, answered the same **302**, and nothing changes.\n- **An unknown, zero or negative vanId** — **404**.\n\nEvery scalar field in the payload is writeable here, and all of them can go in one request. Four caveats: `nickname`, `website`, `jobTitle` and `contactMethodPreferenceCode` are stored but read back only under `$expand=preferences`; `organizationContactCommonName` and `organizationContactOfficialName` are stored only while `contactMode` is \"Organization\"; `suffix` is normalized against a lookup, and an unrecognized value leaves the existing suffix standing; and `collectedLocationId`, `electionType` and `cycle` are accepted and then discarded outright.",
        "x-provenance": {
          "lastProbed": "2026-08-10",
          "note": "Merge semantics confirmed by updating only middleName on a person and observing firstName, lastName and employer survive; append semantics by adding a second email and seeing both returned, with isPreferred moving to the newer one. Not in the official docs' page index; the path comes from van-cli (people.ts update), which notes PUT is not supported. The writeable field set was swept on 2026-08-10: a blank person updated with every scalar field at once, then read back with and without $expand=preferences."
        },
        "tags": [
          "People"
        ],
        "x-keywords": [
          "update",
          "edit",
          "modify",
          "change",
          "set field",
          "add phone",
          "add email",
          "add address",
          "append contact method",
          "write",
          "correct a record"
        ],
        "x-task": "Change fields, or add a phone / email / address",
        "parameters": [
          {
            "name": "vanId",
            "in": "path",
            "required": true,
            "description": "VAN id of the person to update.",
            "schema": {
              "type": "integer",
              "format": "int32",
              "minimum": 1
            },
            "example": 102714580
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PersonInput"
              },
              "examples": {
                "scalars": {
                  "summary": "Change a couple of fields, leaving the rest alone",
                  "value": {
                    "middleName": "Quinn",
                    "employer": "Ship Creek Group"
                  }
                },
                "addEmail": {
                  "summary": "Append an email address (existing addresses are kept)",
                  "value": {
                    "emails": [
                      {
                        "email": "cre.work@example.com",
                        "type": "W"
                      }
                    ]
                  }
                },
                "update-appends-contact-methods/1": {
                  "summary": "Update with a second address. The first is not replaced — the list grows.",
                  "description": "Emails, phones and addresses in an update are added to what is already there; there is no way to remove one through this endpoint. The append is idempotent for an identical value: re-sending an email the person already has does not create a second entry.",
                  "x-transcript": "update-appends-contact-methods",
                  "value": {
                    "emails": [
                      {
                        "email": "imani.o@example.org"
                      }
                    ]
                  }
                },
                "update-appends-contact-methods/2": {
                  "summary": "Send the second address again, unchanged. Nothing is duplicated: still two entries.",
                  "description": "Emails, phones and addresses in an update are added to what is already there; there is no way to remove one through this endpoint. The append is idempotent for an identical value: re-sending an email the person already has does not create a second entry.",
                  "x-transcript": "update-appends-contact-methods",
                  "value": {
                    "emails": [
                      {
                        "email": "imani.o@example.org"
                      }
                    ]
                  }
                },
                "update-empty-body-is-accepted-and-unknown-ids-404/1": {
                  "summary": "An update that updates nothing. Accepted all the same.",
                  "description": "`{}` is accepted and answered with the same 302 as a real update, changing nothing. The failure mode is the id, not the body: an unknown vanId returns 404 whatever the payload says.",
                  "x-transcript": "update-empty-body-is-accepted-and-unknown-ids-404",
                  "value": {}
                },
                "update-empty-body-is-accepted-and-unknown-ids-404/2": {
                  "summary": "A perfectly good payload aimed at an id nobody has: 404.",
                  "description": "`{}` is accepted and answered with the same 302 as a real update, changing nothing. The failure mode is the id, not the body: an unknown vanId returns 404 whatever the payload says.",
                  "x-transcript": "update-empty-body-is-accepted-and-unknown-ids-404",
                  "value": {
                    "firstName": "Nobody"
                  }
                },
                "update-merges-fields-and-answers-with-a-stub": {
                  "summary": "An update merges the payload and answers 302 with a match stub",
                  "description": "The payload is merged into the record: fields in the body are overwritten, fields left out keep their values. The response is a 302 whose Location points back at the person and whose body is the same match stub find returns — not the updated person.",
                  "x-transcript": "update-merges-fields-and-answers-with-a-stub",
                  "value": {
                    "firstName": "Cora"
                  }
                },
                "update-suffix-is-matched-against-a-lookup/1": {
                  "summary": "Lowercase, with no period. Stored in the lookup's own spelling.",
                  "description": "Unlike every other name part, `suffix` is not free text: it is matched case- and punctuation-insensitively against a known list, so \"jr\" and \"Jr.\" both read back as \"Jr\". A value the list does not recognize is neither stored nor refused — the request succeeds and the previous suffix is left standing.",
                  "x-transcript": "update-suffix-is-matched-against-a-lookup",
                  "value": {
                    "suffix": "jr"
                  }
                },
                "update-suffix-is-matched-against-a-lookup/2": {
                  "summary": "An honorific the list does not hold. Accepted, and quietly ignored.",
                  "description": "Unlike every other name part, `suffix` is not free text: it is matched case- and punctuation-insensitively against a known list, so \"jr\" and \"Jr.\" both read back as \"Jr\". A value the list does not recognize is neither stored nor refused — the request succeeds and the previous suffix is left standing.",
                  "x-transcript": "update-suffix-is-matched-against-a-lookup",
                  "value": {
                    "suffix": "Esq."
                  }
                },
                "update-writes-every-scalar-field/1": {
                  "summary": "One update carrying every scalar field the payload documents.",
                  "description": "Every scalar field PersonInput documents is writeable through an update, in a single payload: the name parts, the derived-by-default salutation and envelopeName, nickname, website, party, sex, dateOfBirth, the three job fields, contactMethodPreferenceCode and contactMode. Four of them — nickname, website, jobTitle and contactMethodPreferenceCode — read back null on a plain GET and only surface under `$expand=preferences`, so a round-trip without it looks like the write was dropped. Three genuinely are dropped: collectedLocationId, electionType and cycle are accepted and leave no trace anywhere the API will show you. The organizationContact names are conditional — discarded while the record is in Person mode, stored once contactMode is Organization.",
                  "x-transcript": "update-writes-every-scalar-field",
                  "value": {
                    "firstName": "Ottoline",
                    "middleName": "Quill",
                    "lastName": "Fieldwright",
                    "suffix": "Jr.",
                    "title": "Dr.",
                    "salutation": "Hey Otto",
                    "envelopeName": "O. Q. Fieldwright",
                    "nickname": "Otto",
                    "website": "https://ottoline.example",
                    "party": "D",
                    "contactMethodPreferenceCode": "E",
                    "employer": "Ship Creek Group",
                    "occupation": "Cartographer",
                    "jobTitle": "Chief Mapper",
                    "sex": "F",
                    "dateOfBirth": "1985-03-04",
                    "collectedLocationId": 12345,
                    "electionType": "G",
                    "cycle": "2024",
                    "organizationContactCommonName": "Fieldwright Cartography",
                    "organizationContactOfficialName": "Fieldwright Cartography LLC",
                    "contactMode": "Person"
                  }
                },
                "update-writes-every-scalar-field/2": {
                  "summary": "The organization names were dropped too — the record is in Person mode. Send them again with contactMode Organization and they stick.",
                  "description": "Every scalar field PersonInput documents is writeable through an update, in a single payload: the name parts, the derived-by-default salutation and envelopeName, nickname, website, party, sex, dateOfBirth, the three job fields, contactMethodPreferenceCode and contactMode. Four of them — nickname, website, jobTitle and contactMethodPreferenceCode — read back null on a plain GET and only surface under `$expand=preferences`, so a round-trip without it looks like the write was dropped. Three genuinely are dropped: collectedLocationId, electionType and cycle are accepted and leave no trace anywhere the API will show you. The organizationContact names are conditional — discarded while the record is in Person mode, stored once contactMode is Organization.",
                  "x-transcript": "update-writes-every-scalar-field",
                  "value": {
                    "contactMode": "Organization",
                    "organizationContactCommonName": "Fieldwright Cartography",
                    "organizationContactOfficialName": "Fieldwright Cartography LLC"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Never sent by this endpoint. This is where a redirect-following client *lands* after a successful update:\n\n```\nPOST /people/102714580         {\"firstName\": \"Cre\", …}\n  ← 302 Found\n    Location: https://api.securevan.com/v4/people/102714580   (same URL)\n    {\"vanId\": 102714580, \"status\": \"Matched\"}\n\nGET /people/102714580          ← client re-issues the request at Location\n  ← 200 OK\n    { the merged person record — the body documented here }\n```\n\nA happy accident: the update itself never returns the person, but the followed GET does, so redirect-following clients get the merged result for free. See POST /people/find for the full redirect-following notes, including the `curl -X POST -L` gotcha.\n\nThe other way to reach a 200 is a failure: when the 302 was the ASP.NET request-validation bounce (a path segment containing `<`, `>`, `*` or `&`), following it lands on the web application's HTML error page, which answers 200 with `text/html`. Check the content type before parsing JSON.",
            "x-provenance": {
              "lastProbed": "2026-08-04",
              "note": "Chain observed end to end with httpx: POST /people/{vanId} with an empty body → 302 back to the same URL → GET → 200 with the full person record."
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Person"
                }
              },
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "302": {
            "description": "The person was updated. `Location` points back at the person resource; the body is a match stub, not the updated person.\n\nThe same status also covers a failure that never reaches the API: a path segment containing `<`, `>`, `*` or `&` is rejected by ASP.NET request validation and redirected to `/Error.aspx?EID={code}` with an HTML body. Check the content type to tell them apart.",
            "headers": {
              "Location": {
                "description": "URL of the updated person — or of the web application's error page when request validation rejected the path.",
                "schema": {
                  "type": "string",
                  "format": "uri"
                },
                "example": "https://api.securevan.com/v4/people/102714580"
              }
            },
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                },
                "x-provenance": {
                  "lastProbed": "2026-08-03",
                  "note": "\"Object moved\" body of the request-validation redirect; see the RequestValidationRedirect response for the full story."
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PersonMatched"
                },
                "examples": {
                  "update-appends-contact-methods/1": {
                    "summary": "Update with a second address. The first is not replaced — the list grows.",
                    "description": "Emails, phones and addresses in an update are added to what is already there; there is no way to remove one through this endpoint. The append is idempotent for an identical value: re-sending an email the person already has does not create a second entry.",
                    "x-transcript": "update-appends-contact-methods",
                    "value": {
                      "vanId": 100000001,
                      "status": "Matched"
                    }
                  },
                  "update-appends-contact-methods/2": {
                    "summary": "Send the second address again, unchanged. Nothing is duplicated: still two entries.",
                    "description": "Emails, phones and addresses in an update are added to what is already there; there is no way to remove one through this endpoint. The append is idempotent for an identical value: re-sending an email the person already has does not create a second entry.",
                    "x-transcript": "update-appends-contact-methods",
                    "value": {
                      "vanId": 100000001,
                      "status": "Matched"
                    }
                  },
                  "update-empty-body-is-accepted-and-unknown-ids-404/1": {
                    "summary": "An update that updates nothing. Accepted all the same.",
                    "description": "`{}` is accepted and answered with the same 302 as a real update, changing nothing. The failure mode is the id, not the body: an unknown vanId returns 404 whatever the payload says.",
                    "x-transcript": "update-empty-body-is-accepted-and-unknown-ids-404",
                    "value": {
                      "vanId": 100000001,
                      "status": "Matched"
                    }
                  },
                  "update-merges-fields-and-answers-with-a-stub": {
                    "summary": "An update merges the payload and answers 302 with a match stub",
                    "description": "The payload is merged into the record: fields in the body are overwritten, fields left out keep their values. The response is a 302 whose Location points back at the person and whose body is the same match stub find returns — not the updated person.",
                    "x-transcript": "update-merges-fields-and-answers-with-a-stub",
                    "value": {
                      "vanId": 100000001,
                      "status": "Matched"
                    }
                  },
                  "update-suffix-is-matched-against-a-lookup/1": {
                    "summary": "Lowercase, with no period. Stored in the lookup's own spelling.",
                    "description": "Unlike every other name part, `suffix` is not free text: it is matched case- and punctuation-insensitively against a known list, so \"jr\" and \"Jr.\" both read back as \"Jr\". A value the list does not recognize is neither stored nor refused — the request succeeds and the previous suffix is left standing.",
                    "x-transcript": "update-suffix-is-matched-against-a-lookup",
                    "value": {
                      "vanId": 100000001,
                      "status": "Matched"
                    }
                  },
                  "update-suffix-is-matched-against-a-lookup/2": {
                    "summary": "An honorific the list does not hold. Accepted, and quietly ignored.",
                    "description": "Unlike every other name part, `suffix` is not free text: it is matched case- and punctuation-insensitively against a known list, so \"jr\" and \"Jr.\" both read back as \"Jr\". A value the list does not recognize is neither stored nor refused — the request succeeds and the previous suffix is left standing.",
                    "x-transcript": "update-suffix-is-matched-against-a-lookup",
                    "value": {
                      "vanId": 100000001,
                      "status": "Matched"
                    }
                  },
                  "update-writes-every-scalar-field/1": {
                    "summary": "One update carrying every scalar field the payload documents.",
                    "description": "Every scalar field PersonInput documents is writeable through an update, in a single payload: the name parts, the derived-by-default salutation and envelopeName, nickname, website, party, sex, dateOfBirth, the three job fields, contactMethodPreferenceCode and contactMode. Four of them — nickname, website, jobTitle and contactMethodPreferenceCode — read back null on a plain GET and only surface under `$expand=preferences`, so a round-trip without it looks like the write was dropped. Three genuinely are dropped: collectedLocationId, electionType and cycle are accepted and leave no trace anywhere the API will show you. The organizationContact names are conditional — discarded while the record is in Person mode, stored once contactMode is Organization.",
                    "x-transcript": "update-writes-every-scalar-field",
                    "value": {
                      "vanId": 100000001,
                      "status": "Matched"
                    }
                  },
                  "update-writes-every-scalar-field/2": {
                    "summary": "The organization names were dropped too — the record is in Person mode. Send them again with contactMode Organization and they stick.",
                    "description": "Every scalar field PersonInput documents is writeable through an update, in a single payload: the name parts, the derived-by-default salutation and envelopeName, nickname, website, party, sex, dateOfBirth, the three job fields, contactMethodPreferenceCode and contactMode. Four of them — nickname, website, jobTitle and contactMethodPreferenceCode — read back null on a plain GET and only surface under `$expand=preferences`, so a round-trip without it looks like the write was dropped. Three genuinely are dropped: collectedLocationId, electionType and cycle are accepted and leave no trace anywhere the API will show you. The organizationContact names are conditional — discarded while the record is in Person mode, stored once contactMode is Organization.",
                    "x-transcript": "update-writes-every-scalar-field",
                    "value": {
                      "vanId": 100000001,
                      "status": "Matched"
                    }
                  }
                }
              }
            },
            "links": {
              "getUpdatedPerson": {
                "operationId": "getPerson",
                "parameters": {
                  "vanId": "$response.body#/vanId"
                },
                "description": "Fetch the person to see the merged result — the update response does not include it."
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/PersonNotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "Contact methods are appended, never replaced — and identical ones dedupe",
            "source": "# Emails, phones and addresses in an update are added to what is already\n# there; there is no way to remove one through this endpoint. The append is\n# idempotent for an identical value: re-sending an email the person already\n# has does not create a second entry.\n\nPEOPLE_BODY='{\n  \"emails\": [\n    {\n      \"email\": \"imani.o@example.org\"\n    }\n  ]\n}'\n\n# A person with one email address.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Imani\",\n    \"lastName\": \"Oyelaran\",\n    \"emails\": [\n      {\n        \"email\": \"imani.oyelaran@example.com\"\n      }\n    ]\n  }'\n# → 201  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Stored\"\n# }\n\n# Update with a second address. The first is not replaced — the list grows.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/100000001' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"$PEOPLE_BODY\"\n# → 302  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Matched\"\n# }\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people/100000001?%24expand=emails' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 200\n# {\n#   \"vanId\": 100000001,\n#   \"firstName\": \"Imani\",\n#   \"lastName\": \"Oyelaran\",\n#   \"middleName\": null,\n#   \"suffix\": null,\n#   \"title\": null,\n#   \"sourceFileTitle\": null,\n#   \"sourceFileFirstName\": null,\n#   \"sourceFileMiddleName\": null,\n#   \"sourceFileLastName\": null,\n#   \"sourceFileSuffix\": null,\n#   \"contactSource\": \"API\",\n#   \"contactMode\": \"Person\",\n#   \"organizationContactCommonName\": null,\n#   \"organizationContactOfficialName\": null,\n#   \"salutation\": \"Imani\",\n#   \"formalSalutation\": \"Imani Oyelaran\",\n#   \"additionalSalutation\": null,\n#   \"preferredPronoun\": null,\n#   \"pronouns\": null,\n#   \"namePronunciation\": null,\n#   \"envelopeName\": \"Imani Oyelaran\",\n#   \"formalEnvelopeName\": \"Imani Oyelaran\",\n#   \"additionalEnvelopeName\": null,\n#   \"contactMethodPreferenceCode\": null,\n#   \"contactMethodPreferenceId\": null,\n#   \"contactMethodPreferenceName\": null,\n#   \"assistantName\": null,\n#   \"nickname\": null,\n#   \"website\": null,\n#   \"professionalSuffix\": null,\n#   \"party\": null,\n#   \"employer\": null,\n#   \"occupation\": null,\n#   \"jobTitle\": null,\n#   \"sex\": null,\n#   \"dateOfBirth\": null,\n#   \"isDeceased\": false,\n#   \"dateCreated\": \"2026-01-01T00:00:00Z\",\n#   \"dateAcquired\": \"0001-01-01T00:00:00Z\",\n#   \"selfReportedRace\": null,\n#   \"selfReportedEthnicity\": null,\n#   \"selfReportedRaces\": null,\n#   \"selfReportedEthnicities\": null,\n#   \"selfReportedGenders\": null,\n#   \"selfReportedSexualOrientations\": null,\n#   \"selfReportedLanguagePreference\": null,\n#   \"selfReportedLanguagePreferences\": null,\n#   \"emails\": [\n#     {\n#       \"type\": \"P\",\n#       \"email\": \"imani.oyelaran@example.com\",\n#       \"dateCreated\": \"2026-01-01T00:00:00Z\",\n#       \"isPreferred\": false,\n#       \"isSubscribed\": true,\n#       \"subscriptionStatus\": \"S\"\n#     },\n#     {\n#       \"type\": \"P\",\n#       \"email\": \"imani.o@example.org\",\n#       \"dateCreated\": \"2026-01-01T00:00:00Z\",\n#       \"isPreferred\": true,\n#       \"isSubscribed\": true,\n#       \"subscriptionStatus\": \"S\"\n#     }\n#   ],\n#   \"phones\": null,\n#   \"addresses\": null,\n#   \"recordedAddresses\": null,\n#   \"pollingLocation\": null,\n#   \"earlyVoteLocation\": null,\n#   \"identifiers\": null,\n#   \"codes\": null,\n#   \"customFields\": null,\n#   \"primaryCustomField\": null,\n#   \"contributionSummary\": null,\n#   \"suppressions\": null,\n#   \"caseworkCases\": null,\n#   \"caseworkIssues\": null,\n#   \"caseworkStories\": null,\n#   \"notes\": null,\n#   \"scores\": null,\n#   \"customProperties\": null,\n#   \"electionRecords\": null,\n#   \"membershipStatus\": null,\n#   \"organizationRoles\": null,\n#   \"districts\": null,\n#   \"surveyQuestionResponses\": null,\n#   \"finderNumber\": null,\n#   \"biographyImageUrl\": null,\n#   \"biographyText\": null,\n#   \"biographyHtml\": null,\n#   \"primaryContact\": null\n# }\n\n# Send the second address again, unchanged. Nothing is duplicated: still two\n# entries.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/100000001' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"$PEOPLE_BODY\"\n# → 302  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Matched\"\n# }\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people/100000001?%24expand=emails' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 200\n# {\n#   \"vanId\": 100000001,\n#   \"firstName\": \"Imani\",\n#   \"lastName\": \"Oyelaran\",\n#   \"middleName\": null,\n#   \"suffix\": null,\n#   \"title\": null,\n#   \"sourceFileTitle\": null,\n#   \"sourceFileFirstName\": null,\n#   \"sourceFileMiddleName\": null,\n#   \"sourceFileLastName\": null,\n#   \"sourceFileSuffix\": null,\n#   \"contactSource\": \"API\",\n#   \"contactMode\": \"Person\",\n#   \"organizationContactCommonName\": null,\n#   \"organizationContactOfficialName\": null,\n#   \"salutation\": \"Imani\",\n#   \"formalSalutation\": \"Imani Oyelaran\",\n#   \"additionalSalutation\": null,\n#   \"preferredPronoun\": null,\n#   \"pronouns\": null,\n#   \"namePronunciation\": null,\n#   \"envelopeName\": \"Imani Oyelaran\",\n#   \"formalEnvelopeName\": \"Imani Oyelaran\",\n#   \"additionalEnvelopeName\": null,\n#   \"contactMethodPreferenceCode\": null,\n#   \"contactMethodPreferenceId\": null,\n#   \"contactMethodPreferenceName\": null,\n#   \"assistantName\": null,\n#   \"nickname\": null,\n#   \"website\": null,\n#   \"professionalSuffix\": null,\n#   \"party\": null,\n#   \"employer\": null,\n#   \"occupation\": null,\n#   \"jobTitle\": null,\n#   \"sex\": null,\n#   \"dateOfBirth\": null,\n#   \"isDeceased\": false,\n#   \"dateCreated\": \"2026-01-01T00:00:00Z\",\n#   \"dateAcquired\": \"0001-01-01T00:00:00Z\",\n#   \"selfReportedRace\": null,\n#   \"selfReportedEthnicity\": null,\n#   \"selfReportedRaces\": null,\n#   \"selfReportedEthnicities\": null,\n#   \"selfReportedGenders\": null,\n#   \"selfReportedSexualOrientations\": null,\n#   \"selfReportedLanguagePreference\": null,\n#   \"selfReportedLanguagePreferences\": null,\n#   \"emails\": [\n#     {\n#       \"type\": \"P\",\n#       \"email\": \"imani.oyelaran@example.com\",\n#       \"dateCreated\": \"2026-01-01T00:00:00Z\",\n#       \"isPreferred\": false,\n#       \"isSubscribed\": true,\n#       \"subscriptionStatus\": \"S\"\n#     },\n#     {\n#       \"type\": \"P\",\n#       \"email\": \"imani.o@example.org\",\n#       \"dateCreated\": \"2026-01-01T00:00:00Z\",\n#       \"isPreferred\": true,\n#       \"isSubscribed\": true,\n#       \"subscriptionStatus\": \"S\"\n#     }\n#   ],\n#   \"phones\": null,\n#   \"addresses\": null,\n#   \"recordedAddresses\": null,\n#   \"pollingLocation\": null,\n#   \"earlyVoteLocation\": null,\n#   \"identifiers\": null,\n#   \"codes\": null,\n#   \"customFields\": null,\n#   \"primaryCustomField\": null,\n#   \"contributionSummary\": null,\n#   \"suppressions\": null,\n#   \"caseworkCases\": null,\n#   \"caseworkIssues\": null,\n#   \"caseworkStories\": null,\n#   \"notes\": null,\n#   \"scores\": null,\n#   \"customProperties\": null,\n#   \"electionRecords\": null,\n#   \"membershipStatus\": null,\n#   \"organizationRoles\": null,\n#   \"districts\": null,\n#   \"surveyQuestionResponses\": null,\n#   \"finderNumber\": null,\n#   \"biographyImageUrl\": null,\n#   \"biographyText\": null,\n#   \"biographyHtml\": null,\n#   \"primaryContact\": null\n# }",
            "x-transcript": "update-appends-contact-methods"
          },
          {
            "lang": "Shell",
            "label": "An empty body is a successful no-op; an unknown vanId is 404",
            "source": "# `{}` is accepted and answered with the same 302 as a real update, changing\n# nothing. The failure mode is the id, not the body: an unknown vanId\n# returns 404 whatever the payload says.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Otis\",\n    \"lastName\": \"Renwick\"\n  }'\n# → 201  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Stored\"\n# }\n\n# An update that updates nothing. Accepted all the same.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/100000001' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{}\n  {}'\n# → 302  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Matched\"\n# }\n\n# The record is untouched.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people/100000001' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 200\n# {\n#   \"vanId\": 100000001,\n#   \"firstName\": \"Otis\",\n#   \"lastName\": \"Renwick\",\n#   \"middleName\": null,\n#   \"suffix\": null,\n#   \"title\": null,\n#   \"sourceFileTitle\": null,\n#   \"sourceFileFirstName\": null,\n#   \"sourceFileMiddleName\": null,\n#   \"sourceFileLastName\": null,\n#   \"sourceFileSuffix\": null,\n#   \"contactSource\": \"API\",\n#   \"contactMode\": \"Person\",\n#   \"organizationContactCommonName\": null,\n#   \"organizationContactOfficialName\": null,\n#   \"salutation\": \"Otis\",\n#   \"formalSalutation\": \"Otis Renwick\",\n#   \"additionalSalutation\": null,\n#   \"preferredPronoun\": null,\n#   \"pronouns\": null,\n#   \"namePronunciation\": null,\n#   \"envelopeName\": \"Otis Renwick\",\n#   \"formalEnvelopeName\": \"Otis Renwick\",\n#   \"additionalEnvelopeName\": null,\n#   \"contactMethodPreferenceCode\": null,\n#   \"contactMethodPreferenceId\": null,\n#   \"contactMethodPreferenceName\": null,\n#   \"assistantName\": null,\n#   \"nickname\": null,\n#   \"website\": null,\n#   \"professionalSuffix\": null,\n#   \"party\": null,\n#   \"employer\": null,\n#   \"occupation\": null,\n#   \"jobTitle\": null,\n#   \"sex\": null,\n#   \"dateOfBirth\": null,\n#   \"isDeceased\": false,\n#   \"dateCreated\": \"2026-01-01T00:00:00Z\",\n#   \"dateAcquired\": \"0001-01-01T00:00:00Z\",\n#   \"selfReportedRace\": null,\n#   \"selfReportedEthnicity\": null,\n#   \"selfReportedRaces\": null,\n#   \"selfReportedEthnicities\": null,\n#   \"selfReportedGenders\": null,\n#   \"selfReportedSexualOrientations\": null,\n#   \"selfReportedLanguagePreference\": null,\n#   \"selfReportedLanguagePreferences\": null,\n#   \"emails\": null,\n#   \"phones\": null,\n#   \"addresses\": null,\n#   \"recordedAddresses\": null,\n#   \"pollingLocation\": null,\n#   \"earlyVoteLocation\": null,\n#   \"identifiers\": null,\n#   \"codes\": null,\n#   \"customFields\": null,\n#   \"primaryCustomField\": null,\n#   \"contributionSummary\": null,\n#   \"suppressions\": null,\n#   \"caseworkCases\": null,\n#   \"caseworkIssues\": null,\n#   \"caseworkStories\": null,\n#   \"notes\": null,\n#   \"scores\": null,\n#   \"customProperties\": null,\n#   \"electionRecords\": null,\n#   \"membershipStatus\": null,\n#   \"organizationRoles\": null,\n#   \"districts\": null,\n#   \"surveyQuestionResponses\": null,\n#   \"finderNumber\": null,\n#   \"biographyImageUrl\": null,\n#   \"biographyText\": null,\n#   \"biographyHtml\": null,\n#   \"primaryContact\": null\n# }\n\n# A perfectly good payload aimed at an id nobody has: 404.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/2147483646' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Nobody\"\n  }'\n# → 404\n# {\n#   \"errors\": [\n#     {\n#       \"code\": \"NOT_FOUND\",\n#       \"text\": \"The specified resource cannot be found.\"\n#     }\n#   ]\n# }",
            "x-transcript": "update-empty-body-is-accepted-and-unknown-ids-404"
          },
          {
            "lang": "Shell",
            "label": "An update merges the payload and answers 302 with a match stub",
            "source": "# The payload is merged into the record: fields in the body are overwritten,\n# fields left out keep their values. The response is a 302 whose Location\n# points back at the person and whose body is the same match stub find\n# returns — not the updated person.\n\n# A person whose first name is about to change.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Corazon\",\n    \"lastName\": \"Ellsworth\"\n  }'\n# → 201  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Stored\"\n# }\n\n# Send only the new first name.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/100000001' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Cora\"\n  }'\n# → 302  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Matched\"\n# }\n\n# The first name changed; the last name, absent from the body, survived.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people/100000001' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 200\n# {\n#   \"vanId\": 100000001,\n#   \"firstName\": \"Cora\",\n#   \"lastName\": \"Ellsworth\",\n#   \"middleName\": null,\n#   \"suffix\": null,\n#   \"title\": null,\n#   \"sourceFileTitle\": null,\n#   \"sourceFileFirstName\": null,\n#   \"sourceFileMiddleName\": null,\n#   \"sourceFileLastName\": null,\n#   \"sourceFileSuffix\": null,\n#   \"contactSource\": \"API\",\n#   \"contactMode\": \"Person\",\n#   \"organizationContactCommonName\": null,\n#   \"organizationContactOfficialName\": null,\n#   \"salutation\": \"Cora\",\n#   \"formalSalutation\": \"Cora Ellsworth\",\n#   \"additionalSalutation\": null,\n#   \"preferredPronoun\": null,\n#   \"pronouns\": null,\n#   \"namePronunciation\": null,\n#   \"envelopeName\": \"Cora Ellsworth\",\n#   \"formalEnvelopeName\": \"Cora Ellsworth\",\n#   \"additionalEnvelopeName\": null,\n#   \"contactMethodPreferenceCode\": null,\n#   \"contactMethodPreferenceId\": null,\n#   \"contactMethodPreferenceName\": null,\n#   \"assistantName\": null,\n#   \"nickname\": null,\n#   \"website\": null,\n#   \"professionalSuffix\": null,\n#   \"party\": null,\n#   \"employer\": null,\n#   \"occupation\": null,\n#   \"jobTitle\": null,\n#   \"sex\": null,\n#   \"dateOfBirth\": null,\n#   \"isDeceased\": false,\n#   \"dateCreated\": \"2026-01-01T00:00:00Z\",\n#   \"dateAcquired\": \"0001-01-01T00:00:00Z\",\n#   \"selfReportedRace\": null,\n#   \"selfReportedEthnicity\": null,\n#   \"selfReportedRaces\": null,\n#   \"selfReportedEthnicities\": null,\n#   \"selfReportedGenders\": null,\n#   \"selfReportedSexualOrientations\": null,\n#   \"selfReportedLanguagePreference\": null,\n#   \"selfReportedLanguagePreferences\": null,\n#   \"emails\": null,\n#   \"phones\": null,\n#   \"addresses\": null,\n#   \"recordedAddresses\": null,\n#   \"pollingLocation\": null,\n#   \"earlyVoteLocation\": null,\n#   \"identifiers\": null,\n#   \"codes\": null,\n#   \"customFields\": null,\n#   \"primaryCustomField\": null,\n#   \"contributionSummary\": null,\n#   \"suppressions\": null,\n#   \"caseworkCases\": null,\n#   \"caseworkIssues\": null,\n#   \"caseworkStories\": null,\n#   \"notes\": null,\n#   \"scores\": null,\n#   \"customProperties\": null,\n#   \"electionRecords\": null,\n#   \"membershipStatus\": null,\n#   \"organizationRoles\": null,\n#   \"districts\": null,\n#   \"surveyQuestionResponses\": null,\n#   \"finderNumber\": null,\n#   \"biographyImageUrl\": null,\n#   \"biographyText\": null,\n#   \"biographyHtml\": null,\n#   \"primaryContact\": null\n# }",
            "x-transcript": "update-merges-fields-and-answers-with-a-stub"
          },
          {
            "lang": "Shell",
            "label": "A suffix is matched against a lookup, not stored as written",
            "source": "# Unlike every other name part, `suffix` is not free text: it is matched\n# case- and punctuation-insensitively against a known list, so \"jr\" and\n# \"Jr.\" both read back as \"Jr\". A value the list does not recognize is\n# neither stored nor refused — the request succeeds and the previous suffix\n# is left standing.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Thaddeus\",\n    \"lastName\": \"Suffixon\"\n  }'\n# → 201  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Stored\"\n# }\n\n# Lowercase, with no period. Stored in the lookup's own spelling.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/100000001' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"suffix\": \"jr\"\n  }'\n# → 302  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Matched\"\n# }\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people/100000001' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 200\n# {\n#   \"vanId\": 100000001,\n#   \"firstName\": \"Thaddeus\",\n#   \"lastName\": \"Suffixon\",\n#   \"middleName\": null,\n#   \"suffix\": \"Jr\",\n#   \"title\": null,\n#   \"sourceFileTitle\": null,\n#   \"sourceFileFirstName\": null,\n#   \"sourceFileMiddleName\": null,\n#   \"sourceFileLastName\": null,\n#   \"sourceFileSuffix\": null,\n#   \"contactSource\": \"API\",\n#   \"contactMode\": \"Person\",\n#   \"organizationContactCommonName\": null,\n#   \"organizationContactOfficialName\": null,\n#   \"salutation\": \"Thaddeus\",\n#   \"formalSalutation\": \"Thaddeus Suffixon\",\n#   \"additionalSalutation\": null,\n#   \"preferredPronoun\": null,\n#   \"pronouns\": null,\n#   \"namePronunciation\": null,\n#   \"envelopeName\": \"Thaddeus Suffixon\",\n#   \"formalEnvelopeName\": \"Thaddeus Suffixon, Jr\",\n#   \"additionalEnvelopeName\": null,\n#   \"contactMethodPreferenceCode\": null,\n#   \"contactMethodPreferenceId\": null,\n#   \"contactMethodPreferenceName\": null,\n#   \"assistantName\": null,\n#   \"nickname\": null,\n#   \"website\": null,\n#   \"professionalSuffix\": null,\n#   \"party\": null,\n#   \"employer\": null,\n#   \"occupation\": null,\n#   \"jobTitle\": null,\n#   \"sex\": null,\n#   \"dateOfBirth\": null,\n#   \"isDeceased\": false,\n#   \"dateCreated\": \"2026-01-01T00:00:00Z\",\n#   \"dateAcquired\": \"0001-01-01T00:00:00Z\",\n#   \"selfReportedRace\": null,\n#   \"selfReportedEthnicity\": null,\n#   \"selfReportedRaces\": null,\n#   \"selfReportedEthnicities\": null,\n#   \"selfReportedGenders\": null,\n#   \"selfReportedSexualOrientations\": null,\n#   \"selfReportedLanguagePreference\": null,\n#   \"selfReportedLanguagePreferences\": null,\n#   \"emails\": null,\n#   \"phones\": null,\n#   \"addresses\": null,\n#   \"recordedAddresses\": null,\n#   \"pollingLocation\": null,\n#   \"earlyVoteLocation\": null,\n#   \"identifiers\": null,\n#   \"codes\": null,\n#   \"customFields\": null,\n#   \"primaryCustomField\": null,\n#   \"contributionSummary\": null,\n#   \"suppressions\": null,\n#   \"caseworkCases\": null,\n#   \"caseworkIssues\": null,\n#   \"caseworkStories\": null,\n#   \"notes\": null,\n#   \"scores\": null,\n#   \"customProperties\": null,\n#   \"electionRecords\": null,\n#   \"membershipStatus\": null,\n#   \"organizationRoles\": null,\n#   \"districts\": null,\n#   \"surveyQuestionResponses\": null,\n#   \"finderNumber\": null,\n#   \"biographyImageUrl\": null,\n#   \"biographyText\": null,\n#   \"biographyHtml\": null,\n#   \"primaryContact\": null\n# }\n\n# An honorific the list does not hold. Accepted, and quietly ignored.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/100000001' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"suffix\": \"Esq.\"\n  }'\n# → 302  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Matched\"\n# }\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people/100000001' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 200\n# {\n#   \"vanId\": 100000001,\n#   \"firstName\": \"Thaddeus\",\n#   \"lastName\": \"Suffixon\",\n#   \"middleName\": null,\n#   \"suffix\": \"Jr\",\n#   \"title\": null,\n#   \"sourceFileTitle\": null,\n#   \"sourceFileFirstName\": null,\n#   \"sourceFileMiddleName\": null,\n#   \"sourceFileLastName\": null,\n#   \"sourceFileSuffix\": null,\n#   \"contactSource\": \"API\",\n#   \"contactMode\": \"Person\",\n#   \"organizationContactCommonName\": null,\n#   \"organizationContactOfficialName\": null,\n#   \"salutation\": \"Thaddeus\",\n#   \"formalSalutation\": \"Thaddeus Suffixon\",\n#   \"additionalSalutation\": null,\n#   \"preferredPronoun\": null,\n#   \"pronouns\": null,\n#   \"namePronunciation\": null,\n#   \"envelopeName\": \"Thaddeus Suffixon\",\n#   \"formalEnvelopeName\": \"Thaddeus Suffixon, Jr\",\n#   \"additionalEnvelopeName\": null,\n#   \"contactMethodPreferenceCode\": null,\n#   \"contactMethodPreferenceId\": null,\n#   \"contactMethodPreferenceName\": null,\n#   \"assistantName\": null,\n#   \"nickname\": null,\n#   \"website\": null,\n#   \"professionalSuffix\": null,\n#   \"party\": null,\n#   \"employer\": null,\n#   \"occupation\": null,\n#   \"jobTitle\": null,\n#   \"sex\": null,\n#   \"dateOfBirth\": null,\n#   \"isDeceased\": false,\n#   \"dateCreated\": \"2026-01-01T00:00:00Z\",\n#   \"dateAcquired\": \"0001-01-01T00:00:00Z\",\n#   \"selfReportedRace\": null,\n#   \"selfReportedEthnicity\": null,\n#   \"selfReportedRaces\": null,\n#   \"selfReportedEthnicities\": null,\n#   \"selfReportedGenders\": null,\n#   \"selfReportedSexualOrientations\": null,\n#   \"selfReportedLanguagePreference\": null,\n#   \"selfReportedLanguagePreferences\": null,\n#   \"emails\": null,\n#   \"phones\": null,\n#   \"addresses\": null,\n#   \"recordedAddresses\": null,\n#   \"pollingLocation\": null,\n#   \"earlyVoteLocation\": null,\n#   \"identifiers\": null,\n#   \"codes\": null,\n#   \"customFields\": null,\n#   \"primaryCustomField\": null,\n#   \"contributionSummary\": null,\n#   \"suppressions\": null,\n#   \"caseworkCases\": null,\n#   \"caseworkIssues\": null,\n#   \"caseworkStories\": null,\n#   \"notes\": null,\n#   \"scores\": null,\n#   \"customProperties\": null,\n#   \"electionRecords\": null,\n#   \"membershipStatus\": null,\n#   \"organizationRoles\": null,\n#   \"districts\": null,\n#   \"surveyQuestionResponses\": null,\n#   \"finderNumber\": null,\n#   \"biographyImageUrl\": null,\n#   \"biographyText\": null,\n#   \"biographyHtml\": null,\n#   \"primaryContact\": null\n# }",
            "x-transcript": "update-suffix-is-matched-against-a-lookup"
          },
          {
            "lang": "Shell",
            "label": "The whole scalar field set, written in one update",
            "source": "# Every scalar field PersonInput documents is writeable through an update,\n# in a single payload: the name parts, the derived-by-default salutation and\n# envelopeName, nickname, website, party, sex, dateOfBirth, the three job\n# fields, contactMethodPreferenceCode and contactMode. Four of them —\n# nickname, website, jobTitle and contactMethodPreferenceCode — read back\n# null on a plain GET and only surface under `$expand=preferences`, so a\n# round-trip without it looks like the write was dropped. Three genuinely\n# are dropped: collectedLocationId, electionType and cycle are accepted and\n# leave no trace anywhere the API will show you. The organizationContact\n# names are conditional — discarded while the record is in Person mode,\n# stored once contactMode is Organization.\n\n# A blank person, so every field below arrives by way of the update.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{}\n  {}'\n# → 201  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Stored\"\n# }\n\n# One update carrying every scalar field the payload documents.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/100000001' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Ottoline\",\n    \"middleName\": \"Quill\",\n    \"lastName\": \"Fieldwright\",\n    \"suffix\": \"Jr.\",\n    \"title\": \"Dr.\",\n    \"salutation\": \"Hey Otto\",\n    \"envelopeName\": \"O. Q. Fieldwright\",\n    \"nickname\": \"Otto\",\n    \"website\": \"https://ottoline.example\",\n    \"party\": \"D\",\n    \"contactMethodPreferenceCode\": \"E\",\n    \"employer\": \"Ship Creek Group\",\n    \"occupation\": \"Cartographer\",\n    \"jobTitle\": \"Chief Mapper\",\n    \"sex\": \"F\",\n    \"dateOfBirth\": \"1985-03-04\",\n    \"collectedLocationId\": 12345,\n    \"electionType\": \"G\",\n    \"cycle\": \"2024\",\n    \"organizationContactCommonName\": \"Fieldwright Cartography\",\n    \"organizationContactOfficialName\": \"Fieldwright Cartography LLC\",\n    \"contactMode\": \"Person\"\n  }'\n# → 302  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Matched\"\n# }\n\n# Read it back plainly. Most of it landed — but nickname, website, jobTitle\n# and contactMethodPreferenceCode come back null, as if the write had been\n# ignored.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people/100000001' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 200\n# {\n#   \"vanId\": 100000001,\n#   \"firstName\": \"Ottoline\",\n#   \"lastName\": \"Fieldwright\",\n#   \"middleName\": \"Quill\",\n#   \"suffix\": \"Jr\",\n#   \"title\": \"Dr.\",\n#   \"sourceFileTitle\": null,\n#   \"sourceFileFirstName\": null,\n#   \"sourceFileMiddleName\": null,\n#   \"sourceFileLastName\": null,\n#   \"sourceFileSuffix\": null,\n#   \"contactSource\": \"API\",\n#   \"contactMode\": \"Person\",\n#   \"organizationContactCommonName\": null,\n#   \"organizationContactOfficialName\": null,\n#   \"salutation\": \"Hey Otto\",\n#   \"formalSalutation\": \"Dr. Fieldwright\",\n#   \"additionalSalutation\": null,\n#   \"preferredPronoun\": null,\n#   \"pronouns\": null,\n#   \"namePronunciation\": null,\n#   \"envelopeName\": \"O. Q. Fieldwright\",\n#   \"formalEnvelopeName\": \"Dr. Ottoline Q. Fieldwright, Jr\",\n#   \"additionalEnvelopeName\": null,\n#   \"contactMethodPreferenceCode\": null,\n#   \"contactMethodPreferenceId\": null,\n#   \"contactMethodPreferenceName\": null,\n#   \"assistantName\": null,\n#   \"nickname\": null,\n#   \"website\": null,\n#   \"professionalSuffix\": null,\n#   \"party\": \"D\",\n#   \"employer\": \"Ship Creek Group\",\n#   \"occupation\": \"Cartographer\",\n#   \"jobTitle\": null,\n#   \"sex\": \"F\",\n#   \"dateOfBirth\": \"1985-03-04T00:00:00Z\",\n#   \"isDeceased\": false,\n#   \"partialDateOfBirth\": {\n#     \"month\": 3,\n#     \"day\": 4,\n#     \"year\": 1985\n#   },\n#   \"dateCreated\": \"2026-01-01T00:00:00Z\",\n#   \"dateAcquired\": \"0001-01-01T00:00:00Z\",\n#   \"selfReportedRace\": null,\n#   \"selfReportedEthnicity\": null,\n#   \"selfReportedRaces\": null,\n#   \"selfReportedEthnicities\": null,\n#   \"selfReportedGenders\": null,\n#   \"selfReportedSexualOrientations\": null,\n#   \"selfReportedLanguagePreference\": null,\n#   \"selfReportedLanguagePreferences\": null,\n#   \"emails\": null,\n#   \"phones\": null,\n#   \"addresses\": null,\n#   \"recordedAddresses\": null,\n#   \"pollingLocation\": null,\n#   \"earlyVoteLocation\": null,\n#   \"identifiers\": null,\n#   \"codes\": null,\n#   \"customFields\": null,\n#   \"primaryCustomField\": null,\n#   \"contributionSummary\": null,\n#   \"suppressions\": null,\n#   \"caseworkCases\": null,\n#   \"caseworkIssues\": null,\n#   \"caseworkStories\": null,\n#   \"notes\": null,\n#   \"scores\": null,\n#   \"customProperties\": null,\n#   \"electionRecords\": null,\n#   \"membershipStatus\": null,\n#   \"organizationRoles\": null,\n#   \"districts\": null,\n#   \"surveyQuestionResponses\": null,\n#   \"finderNumber\": null,\n#   \"biographyImageUrl\": null,\n#   \"biographyText\": null,\n#   \"biographyHtml\": null,\n#   \"primaryContact\": null\n# }\n\n# They did land. `$expand=preferences` is what makes those four readable.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people/100000001?%24expand=preferences%2CelectionRecords' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 200\n# {\n#   \"vanId\": 100000001,\n#   \"firstName\": \"Ottoline\",\n#   \"lastName\": \"Fieldwright\",\n#   \"middleName\": \"Quill\",\n#   \"suffix\": \"Jr\",\n#   \"title\": \"Dr.\",\n#   \"sourceFileTitle\": null,\n#   \"sourceFileFirstName\": null,\n#   \"sourceFileMiddleName\": null,\n#   \"sourceFileLastName\": null,\n#   \"sourceFileSuffix\": null,\n#   \"contactSource\": \"API\",\n#   \"contactMode\": \"Person\",\n#   \"organizationContactCommonName\": null,\n#   \"organizationContactOfficialName\": null,\n#   \"salutation\": \"Hey Otto\",\n#   \"formalSalutation\": \"Dr. Fieldwright\",\n#   \"additionalSalutation\": null,\n#   \"preferredPronoun\": null,\n#   \"pronouns\": null,\n#   \"namePronunciation\": null,\n#   \"envelopeName\": \"O. Q. Fieldwright\",\n#   \"formalEnvelopeName\": \"Dr. Ottoline Q. Fieldwright, Jr\",\n#   \"additionalEnvelopeName\": null,\n#   \"contactMethodPreferenceCode\": \"E\",\n#   \"contactMethodPreferenceId\": 2,\n#   \"contactMethodPreferenceName\": \"Email\",\n#   \"assistantName\": null,\n#   \"nickname\": \"Otto\",\n#   \"website\": \"https://ottoline.example\",\n#   \"professionalSuffix\": null,\n#   \"party\": \"D\",\n#   \"employer\": \"Ship Creek Group\",\n#   \"occupation\": \"Cartographer\",\n#   \"jobTitle\": \"Chief Mapper\",\n#   \"sex\": \"F\",\n#   \"dateOfBirth\": \"1985-03-04T00:00:00Z\",\n#   \"isDeceased\": false,\n#   \"partialDateOfBirth\": {\n#     \"month\": 3,\n#     \"day\": 4,\n#     \"year\": 1985\n#   },\n#   \"dateCreated\": \"2026-01-01T00:00:00Z\",\n#   \"dateAcquired\": \"0001-01-01T00:00:00Z\",\n#   \"selfReportedRace\": null,\n#   \"selfReportedEthnicity\": null,\n#   \"selfReportedRaces\": null,\n#   \"selfReportedEthnicities\": null,\n#   \"selfReportedGenders\": null,\n#   \"selfReportedSexualOrientations\": null,\n#   \"selfReportedLanguagePreference\": null,\n#   \"selfReportedLanguagePreferences\": null,\n#   \"emails\": null,\n#   \"phones\": null,\n#   \"addresses\": null,\n#   \"recordedAddresses\": null,\n#   \"pollingLocation\": null,\n#   \"earlyVoteLocation\": null,\n#   \"identifiers\": null,\n#   \"codes\": null,\n#   \"customFields\": null,\n#   \"primaryCustomField\": null,\n#   \"contributionSummary\": null,\n#   \"suppressions\": null,\n#   \"caseworkCases\": null,\n#   \"caseworkIssues\": null,\n#   \"caseworkStories\": null,\n#   \"notes\": null,\n#   \"scores\": null,\n#   \"customProperties\": null,\n#   \"electionRecords\": [],\n#   \"membershipStatus\": null,\n#   \"organizationRoles\": null,\n#   \"districts\": null,\n#   \"surveyQuestionResponses\": null,\n#   \"finderNumber\": null,\n#   \"biographyImageUrl\": null,\n#   \"biographyText\": null,\n#   \"biographyHtml\": null,\n#   \"primaryContact\": null\n# }\n\n# collectedLocationId, electionType and cycle are the ones really discarded:\n# the person record has nowhere to carry them, and the election records they\n# name stay empty.\n\n# The organization names were dropped too — the record is in Person mode.\n# Send them again with contactMode Organization and they stick.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/100000001' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"contactMode\": \"Organization\",\n    \"organizationContactCommonName\": \"Fieldwright Cartography\",\n    \"organizationContactOfficialName\": \"Fieldwright Cartography LLC\"\n  }'\n# → 302  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Matched\"\n# }\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people/100000001' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 200\n# {\n#   \"vanId\": 100000001,\n#   \"firstName\": \"Ottoline\",\n#   \"lastName\": \"Fieldwright\",\n#   \"middleName\": \"Quill\",\n#   \"suffix\": \"Jr\",\n#   \"title\": \"Dr.\",\n#   \"sourceFileTitle\": null,\n#   \"sourceFileFirstName\": null,\n#   \"sourceFileMiddleName\": null,\n#   \"sourceFileLastName\": null,\n#   \"sourceFileSuffix\": null,\n#   \"contactSource\": \"API\",\n#   \"contactMode\": \"Organization\",\n#   \"organizationContactCommonName\": \"Fieldwright Cartography\",\n#   \"organizationContactOfficialName\": \"Fieldwright Cartography LLC\",\n#   \"salutation\": \"Hey Otto\",\n#   \"formalSalutation\": \"Friends\",\n#   \"additionalSalutation\": \"Fieldwright Cartography\",\n#   \"preferredPronoun\": null,\n#   \"pronouns\": null,\n#   \"namePronunciation\": null,\n#   \"envelopeName\": \"Fieldwright Cartography LLC\",\n#   \"formalEnvelopeName\": \"Fieldwright Cartography LLC\",\n#   \"additionalEnvelopeName\": null,\n#   \"contactMethodPreferenceCode\": null,\n#   \"contactMethodPreferenceId\": null,\n#   \"contactMethodPreferenceName\": null,\n#   \"assistantName\": null,\n#   \"nickname\": null,\n#   \"website\": null,\n#   \"professionalSuffix\": null,\n#   \"party\": \"D\",\n#   \"employer\": \"Ship Creek Group\",\n#   \"occupation\": \"Cartographer\",\n#   \"jobTitle\": null,\n#   \"sex\": \"F\",\n#   \"dateOfBirth\": \"1985-03-04T00:00:00Z\",\n#   \"isDeceased\": false,\n#   \"partialDateOfBirth\": {\n#     \"month\": 3,\n#     \"day\": 4,\n#     \"year\": 1985\n#   },\n#   \"dateCreated\": \"2026-01-01T00:00:00Z\",\n#   \"dateAcquired\": \"0001-01-01T00:00:00Z\",\n#   \"selfReportedRace\": null,\n#   \"selfReportedEthnicity\": null,\n#   \"selfReportedRaces\": null,\n#   \"selfReportedEthnicities\": null,\n#   \"selfReportedGenders\": null,\n#   \"selfReportedSexualOrientations\": null,\n#   \"selfReportedLanguagePreference\": null,\n#   \"selfReportedLanguagePreferences\": null,\n#   \"emails\": null,\n#   \"phones\": null,\n#   \"addresses\": null,\n#   \"recordedAddresses\": null,\n#   \"pollingLocation\": null,\n#   \"earlyVoteLocation\": null,\n#   \"identifiers\": null,\n#   \"codes\": null,\n#   \"customFields\": null,\n#   \"primaryCustomField\": null,\n#   \"contributionSummary\": null,\n#   \"suppressions\": null,\n#   \"caseworkCases\": null,\n#   \"caseworkIssues\": null,\n#   \"caseworkStories\": null,\n#   \"notes\": null,\n#   \"scores\": null,\n#   \"customProperties\": null,\n#   \"electionRecords\": null,\n#   \"membershipStatus\": null,\n#   \"organizationRoles\": null,\n#   \"districts\": null,\n#   \"surveyQuestionResponses\": null,\n#   \"finderNumber\": null,\n#   \"biographyImageUrl\": null,\n#   \"biographyText\": null,\n#   \"biographyHtml\": null,\n#   \"primaryContact\": null\n# }",
            "x-transcript": "update-writes-every-scalar-field"
          }
        ]
      }
    },
    "/people": {
      "get": {
        "operationId": "searchPeople",
        "summary": "Search for people",
        "description": "Searches for people matching the given criteria and returns full person records in the standard pagination envelope. At least one search parameter must be set: firstName, lastName, middleName, streetAddress, city, stateOrProvince, zipOrPostalCode, phoneNumber, email, commonName, or officialName. A request with none of these — even one with filter or paging parameters set — returns 400 INVALID_PARAMETER with the text \"This endpoint requires at least one search parameter to be set.\" Text criteria are case-insensitive prefix matches: lastName=Testpers matches \"Testperson\", lastName=estperson does not. Related collections on the returned person records are null unless requested via $expand.\n\n**This is the endpoint to use when you only have loose criteria.** Unlike POST /people/find and POST /people/findOrCreate — which refuse to attempt a match until you supply one of a handful of minimum field combinations, and answer Unmatched (or create a duplicate) when you cannot — this search has no such threshold. A single name is a perfectly valid query. In exchange it makes no identity claim: it hands back every person whose fields start with what you typed, and deciding which one is your person, or that none of them is, is your job. Inspect the candidates (with $expand for addresses, emails and phones if you need them) and take the vanId from there.",
        "x-provenance": {
          "source": "van-cli people.ts (list command) plus live sandbox probing; the endpoint is absent from the official docs' page index (llms.txt lists only /people/find).",
          "lastProbed": "2026-08-04"
        },
        "tags": [
          "People"
        ],
        "x-keywords": [
          "search",
          "list people",
          "browse",
          "enumerate",
          "find by name",
          "how many",
          "count",
          "total",
          "filter",
          "prefix match",
          "paginate",
          "lookup by city",
          "lookup by zip",
          "everyone named"
        ],
        "x-task": "Find people by loose criteria — name, city, ZIP, email",
        "parameters": [
          {
            "name": "firstName",
            "in": "query",
            "description": "First name. Case-insensitive prefix match.",
            "schema": {
              "type": "string"
            },
            "example": "Ada"
          },
          {
            "name": "lastName",
            "in": "query",
            "description": "Last name. Case-insensitive prefix match.",
            "schema": {
              "type": "string"
            },
            "example": "Testperson"
          },
          {
            "name": "middleName",
            "in": "query",
            "description": "Middle name.",
            "schema": {
              "type": "string"
            },
            "example": "Marie"
          },
          {
            "name": "streetAddress",
            "in": "query",
            "description": "Street address, matched as a case-insensitive prefix — but only against the person's **Voting (home) address**, as are `city`, `stateOrProvince` and `zipOrPostalCode`. All four read the single address VAN files as Voting; Work and Custom addresses are not indexed at all, and a Mailing address is only reachable when the person has no separate Voting address (VAN then serves the mailing one under both types, and it becomes findable). So a person can hold an address and still not be findable by it.\n\nThe comparison also runs against the *standardized* form VAN stored rather than the text that was written: a person created with `1000 W 5th Ave` is found by `1000 5Th Ave Mall` and **not** by `1000 W 5th Ave`.\n\nPOST /people/find has neither limitation — it matches every address type, including the Work and Custom addresses that $expand=addresses never shows.",
            "x-provenance": {
              "source": "sandbox probe",
              "lastProbed": "2026-08-06",
              "note": "Probed on a person carrying four addresses (Home, Work, Mailing, Custom): only the Home/Voting one was findable here, and only under its standardized form, while POST /people/find matched all four. Calibrated while re-testing what PUT /people/{vanId}/mergeInto does to addresses, where this parameter had been used as an instrument and produced a false negative. Re-probed 2026-08-06 with single-address people: a Mailing-only person reads back with that address listed under both Voting and Mailing (same addressId) and is findable by streetAddress/city/state/zip; a Work-only person is findable by none of them."
            },
            "schema": {
              "type": "string"
            },
            "example": "123 Test St"
          },
          {
            "name": "city",
            "in": "query",
            "description": "City, matched as a case-insensitive prefix (`anchor` finds Anchorage; `nchorage` finds nothing). Like `streetAddress`, it reads the **Voting (home) address only** — a person whose mailing or work address sits in a different city is not returned for that city — and it compares against the city VAN standardized at write time, which is not always the one that was written.",
            "x-provenance": {
              "source": "sandbox probe",
              "lastProbed": "2026-08-06",
              "note": "Probe person with Voting=Anchorage AK, Mailing=Seattle WA, Work=Portland OR, Custom=Sacramento CA: found by Anchorage only. Prefix and case behavior probed with anchor/ANCHORAGE/nchorage."
            },
            "schema": {
              "type": "string"
            },
            "example": "Anchorage"
          },
          {
            "name": "stateOrProvince",
            "in": "query",
            "description": "State or province, as the two/three character code — case-insensitive but **not** a prefix match and not the spelled-out name: `AK` and `ak` match, `A` and `Alaska` return nothing. Like `streetAddress`, it reads the **Voting (home) address only**.",
            "x-provenance": {
              "source": "sandbox probe",
              "lastProbed": "2026-08-06",
              "note": "Same four-address probe person (Voting AK, Mailing WA, Work OR, Custom CA): found by AK/ak only; WA, OR, CA, A and Alaska all returned 0."
            },
            "schema": {
              "type": "string"
            },
            "example": "AK"
          },
          {
            "name": "zipOrPostalCode",
            "in": "query",
            "description": "ZIP or postal code. Like `streetAddress`, this matches the **Voting (home) address only** — a person whose mailing address sits in a different ZIP is not returned for that ZIP.\n\nThe value is validated as a postal code (`995` and `995012357` both return 400 INVALID_PARAMETER \"is not a valid Postal Code for UsaAndInternational\"), and only the 5-digit form matches: a person whose stored ZIP is `99501-2357` is found by `99501` and not by `99501-2357`, which is accepted but returns nothing.",
            "x-provenance": {
              "source": "sandbox probe",
              "lastProbed": "2026-08-06",
              "note": "The four-address probe person was found by its home ZIP 99501 and not by its mailing ZIP 99503; re-probed with Voting 99501 / Mailing 98101 / Work 97201 / Custom 95814 to the same effect. ZIP+4 and unpunctuated-9-digit forms tested against a person whose address standardized to 99501-2357."
            },
            "schema": {
              "type": "string"
            },
            "example": "99501"
          },
          {
            "name": "phoneNumber",
            "in": "query",
            "description": "Phone number. **Send bare 10 digits — `9072223333`.** Anything else silently finds nothing: the comparison is against the stored 10-digit string, so `(907) 222-3333`, `907-222-3333` and the `1`-prefixed `19072223333` are all *accepted* and then match no one. (Validation is laxer than matching: non-numeric characters are stripped before the value is checked against `^1?[2-9][0-8]\\d[2-9]\\d{6,6}$`, which is why the formatted forms get through. Failing that regex returns 400 INVALID_PARAMETER with it in the hint.)\n\nThis checks **one number per person**: the number VAN flags `isBest` (the first entry `$expand=phones` returns). A person holding home, work, cell and fax numbers is findable only by whichever one is best — for that person the cell — even though the others are on the person record and POST /people/find matches them. A person can also have **no** best number — when every number on it is a work, other or fax number and none was written `isPreferred` — and such a person cannot be found through this parameter at all. See `PersonPhone.isBest` for how the best number is picked.",
            "x-provenance": {
              "source": "sandbox probe",
              "lastProbed": "2026-08-06",
              "note": "Person with four phones (H 9072223333, W 9073334444, C 9074445555, F 9075556666): only 9074445555 — the isBest/cell one — was findable. Confirmed on three further people that the isBest phone is always the matching one, including a home-only person (isBest home, findable) and a cell+explicitly-preferred-home person (findable by the home number, not the cell). isPreferred is not required: the four-phone person had no preferred phone. The no-best case was probed 2026-08-06: work-only, other-only and Personal/fax-only people each returned an empty items array for their own number, while an otherwise identical work-only person whose number was written with isPreferred:true was found."
            },
            "schema": {
              "type": "string",
              "pattern": "^1?[2-9][0-8]\\d[2-9]\\d{6,6}$"
            },
            "example": "9075550142"
          },
          {
            "name": "email",
            "in": "query",
            "description": "Email address. Case-insensitive prefix match, checked against **all** of the person's email addresses, not just the preferred one. Prefix means from the start of the address: `probe.charlie` finds `probe.charlie@example.com`, `charlie@example.com` does not.",
            "x-provenance": {
              "source": "sandbox probe",
              "lastProbed": "2026-08-06",
              "note": "Person with three emails (personal/work/other, the second flagged preferred): all three matched in full, uppercased, and by leading prefix; a mid-string substring did not."
            },
            "schema": {
              "type": "string"
            },
            "example": "ada.testperson@example.com"
          },
          {
            "name": "commonName",
            "in": "query",
            "description": "Organization common name.",
            "schema": {
              "type": "string"
            },
            "example": "Acme Corp"
          },
          {
            "name": "officialName",
            "in": "query",
            "description": "Organization official name.",
            "schema": {
              "type": "string"
            },
            "example": "Acme Corporation"
          },
          {
            "name": "contactMode",
            "in": "query",
            "description": "Filters the results to Person or Organization contacts. Does not count toward the at-least-one-search-parameter requirement, and any other value is ignored rather than rejected.",
            "schema": {
              "type": "string",
              "enum": [
                "Person",
                "Organization"
              ]
            },
            "example": "Person"
          },
          {
            "name": "employer",
            "in": "query",
            "description": "Accepted but has no effect on the results, and does not count toward the at-least-one-search-parameter requirement.",
            "schema": {
              "type": "string"
            },
            "example": "Acme Corp",
            "x-provenance": {
              "lastProbed": "2026-08-04",
              "note": "Listed as a search criterion in van-cli people.ts, but adding it to a lastName search never changed the result count, even for values matching no one. Only My Campaign was probed."
            }
          },
          {
            "name": "occupation",
            "in": "query",
            "description": "Accepted but has no effect on the results, and does not count toward the at-least-one-search-parameter requirement.",
            "schema": {
              "type": "string"
            },
            "example": "Engineer",
            "x-provenance": {
              "lastProbed": "2026-08-04",
              "note": "Listed as a search criterion in van-cli people.ts, but adding it to a lastName search never changed the result count, even for values matching no one. Only My Campaign was probed."
            }
          },
          {
            "name": "dateOfBirth",
            "in": "query",
            "description": "Accepted but has no effect on the results, and does not count toward the at-least-one-search-parameter requirement. Even an unparseable value is accepted and ignored.",
            "schema": {
              "type": "string"
            },
            "example": "1980-01-15",
            "x-provenance": {
              "lastProbed": "2026-08-04",
              "note": "Listed as a search criterion in van-cli people.ts, but adding it to a lastName search never changed the result count, even for values matching no one. Only My Campaign was probed."
            }
          },
          {
            "name": "$top",
            "in": "query",
            "description": "Limits the number of results per page. Default 50, maximum 200; 0 and negative values return 400.",
            "x-provenance": {
              "lastProbed": "2026-08-04",
              "note": "van-cli caps this at 50 client-side with a comment that VAN limits people search to 50, but the API's own INVALID_PARAMETER hint states default 50 / maximum 200, and $top=200 was accepted live."
            },
            "schema": {
              "type": "integer",
              "format": "int32",
              "minimum": 1,
              "maximum": 200
            },
            "example": 50
          },
          {
            "name": "$skip",
            "in": "query",
            "description": "Number of results to skip. Negative values return 400.",
            "schema": {
              "type": "integer",
              "format": "int32",
              "minimum": 0
            },
            "example": 0
          },
          {
            "name": "$orderby",
            "in": "query",
            "description": "Sort expression. The only sortable property is Name; \"Name desc\" sorts descending. Any other property returns 400 INVALID_PARAMETER with the hint \"The only valid orderby property is: 'Name'\".",
            "schema": {
              "type": "string"
            },
            "example": "Name"
          },
          {
            "name": "$expand",
            "in": "query",
            "description": "Related sections to include, comma-delimited and case-insensitive eg 'addresses,emails' — a much smaller set than GET /people/{vanId} accepts. The API's hint also lists pollingLocation, but requesting it is then refused with 400 BAD_REQUEST \"May not request 'pollingLocation' in this context\", alone or combined, so the usable set is the four below. Anything outside the hinted set returns 400 INVALID_PARAMETER. Expanded collections come back as empty arrays when absent; unexpanded sections stay null.",
            "style": "form",
            "explode": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "addresses",
                  "emails",
                  "phones",
                  "districts"
                ]
              }
            },
            "example": [
              "emails",
              "phones",
              "addresses",
              "districts"
            ],
            "x-provenance": {
              "lastProbed": "2026-08-04",
              "note": "pollingLocation was rejected in My Campaign mode (the only mode the sandbox key can reach); it may be expandable in My Voters mode, which is what the hint presumably describes."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of matching people.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PersonList"
                },
                "examples": {
                  "First of Many Pages (with $expand)": {
                    "description": "lastName=Testperson&$top=1&$orderby=Name desc&$expand=emails,phones,addresses,districts (item abridged: null-only fields, sandbox fuzz noise, and the duplicate Mailing copy of the address omitted — see GET /people/{vanId} for that quirk)",
                    "value": {
                      "items": [
                        {
                          "vanId": 102715285,
                          "firstName": "Grace",
                          "lastName": "Testperson",
                          "contactSource": "API",
                          "contactMode": "Person",
                          "sex": "M",
                          "dateOfBirth": "2000-01-01T00:00:00Z",
                          "isDeceased": false,
                          "partialDateOfBirth": {
                            "month": 1,
                            "day": 1,
                            "year": 2000
                          },
                          "dateCreated": "2026-08-04T12:16:00Z",
                          "dateAcquired": "0001-01-01T00:00:00Z",
                          "emails": [
                            {
                              "type": "W",
                              "email": "grace.testperson@example.com",
                              "dateCreated": "2026-08-04T12:16:00Z",
                              "isPreferred": true,
                              "isSubscribed": true,
                              "subscriptionStatus": "S"
                            }
                          ],
                          "phones": [
                            {
                              "phoneId": 1021654,
                              "phoneNumber": "9075550142",
                              "dialingPrefix": "1",
                              "countryCode": "US",
                              "ext": "123",
                              "dateCreated": "2026-08-04T12:25:00Z",
                              "phoneType": "Personal",
                              "deviceType": "Cell",
                              "isPreferred": true,
                              "isBest": true,
                              "isDisclosure": true,
                              "smsOptInStatus": "Opt-In",
                              "phoneOptInStatus": "Opt-In",
                              "isCellPhoneExchange": false,
                              "isCellStatus": null,
                              "tags": null
                            }
                          ],
                          "addresses": [
                            {
                              "addressId": 1206622,
                              "addressLine1": "123 Test St",
                              "addressLine2": "Apt 4",
                              "city": "Anchorage",
                              "stateOrProvince": "AK",
                              "zipOrPostalCode": "99501",
                              "countryCode": "US",
                              "preview": "123 Test St Apt 4",
                              "type": "Voting",
                              "isPreferred": true,
                              "isBest": true,
                              "displayMode": "Standardized"
                            },
                            {
                              "addressId": 1206622,
                              "addressLine1": "123 Test St",
                              "addressLine2": "Apt 4",
                              "city": "Anchorage",
                              "stateOrProvince": "AK",
                              "zipOrPostalCode": "99501",
                              "countryCode": "US",
                              "preview": "123 Test St Apt 4",
                              "type": "Mailing",
                              "isPreferred": true,
                              "isBest": true,
                              "displayMode": "Standardized"
                            }
                          ],
                          "districts": [
                            {
                              "districtFieldId": 0,
                              "name": "County",
                              "parentFieldId": null,
                              "isCustomDistrict": false,
                              "districtFieldValues": [
                                {
                                  "id": "020",
                                  "name": "Anchorage",
                                  "parentId": null
                                }
                              ]
                            },
                            {
                              "districtFieldId": 0,
                              "name": "State",
                              "parentFieldId": null,
                              "isCustomDistrict": false,
                              "districtFieldValues": [
                                {
                                  "id": "AK",
                                  "name": "Alaska",
                                  "parentId": null
                                }
                              ]
                            }
                          ],
                          "pollingLocation": null,
                          "scores": null
                        }
                      ],
                      "nextPageLink": "https://api.securevan.com:443/v4/people?lastName=Testperson&$top=1&$orderby=Name%20desc&$expand=emails%2Cphones%2Caddresses%2Cdistricts&$skip=1",
                      "count": 131
                    }
                  },
                  "No Matches": {
                    "value": {
                      "items": [],
                      "nextPageLink": null,
                      "count": 0
                    }
                  },
                  "First of Many Pages (no $expand)": {
                    "description": "First of 120 matches for lastName=Testperson with $top=1 (item abridged: null-only fields omitted)",
                    "value": {
                      "items": [
                        {
                          "vanId": 102714808,
                          "firstName": null,
                          "lastName": "Testperson",
                          "contactSource": "API",
                          "contactMode": "Person",
                          "isDeceased": false,
                          "dateCreated": "2026-08-03T17:31:00Z",
                          "dateAcquired": "0001-01-01T00:00:00Z",
                          "emails": null,
                          "phones": null,
                          "addresses": null
                        }
                      ],
                      "nextPageLink": "https://api.securevan.com:443/v4/people?lastName=Testperson&$top=1&$skip=1",
                      "count": 120
                    }
                  },
                  "search-is-a-case-insensitive-prefix-match/1": {
                    "summary": "A lowercase prefix of the first name is enough.",
                    "description": "Matching runs from the start of the field, ignoring case: `wilhel` finds Wilhelmina, `helmina` finds nothing. Hits come back as full person records in the pagination envelope, with collections null unless $expand asks for them.",
                    "x-transcript": "search-is-a-case-insensitive-prefix-match",
                    "value": {
                      "items": [
                        {
                          "vanId": 100000001,
                          "firstName": "Wilhelmina",
                          "lastName": "Prefixling",
                          "middleName": null,
                          "suffix": null,
                          "title": null,
                          "sourceFileTitle": null,
                          "sourceFileFirstName": null,
                          "sourceFileMiddleName": null,
                          "sourceFileLastName": null,
                          "sourceFileSuffix": null,
                          "contactSource": "API",
                          "contactMode": "Person",
                          "organizationContactCommonName": null,
                          "organizationContactOfficialName": null,
                          "salutation": null,
                          "formalSalutation": null,
                          "additionalSalutation": null,
                          "preferredPronoun": null,
                          "pronouns": null,
                          "namePronunciation": null,
                          "envelopeName": null,
                          "formalEnvelopeName": null,
                          "additionalEnvelopeName": null,
                          "contactMethodPreferenceCode": null,
                          "contactMethodPreferenceId": null,
                          "contactMethodPreferenceName": null,
                          "assistantName": null,
                          "nickname": null,
                          "website": null,
                          "professionalSuffix": null,
                          "party": null,
                          "employer": null,
                          "occupation": null,
                          "jobTitle": null,
                          "sex": null,
                          "dateOfBirth": null,
                          "isDeceased": false,
                          "dateCreated": "2026-01-01T00:00:00Z",
                          "dateAcquired": "0001-01-01T00:00:00Z",
                          "selfReportedRace": null,
                          "selfReportedEthnicity": null,
                          "selfReportedRaces": null,
                          "selfReportedEthnicities": null,
                          "selfReportedGenders": null,
                          "selfReportedSexualOrientations": null,
                          "selfReportedLanguagePreference": null,
                          "selfReportedLanguagePreferences": null,
                          "emails": null,
                          "phones": null,
                          "addresses": null,
                          "recordedAddresses": null,
                          "pollingLocation": null,
                          "earlyVoteLocation": null,
                          "identifiers": null,
                          "codes": null,
                          "customFields": null,
                          "primaryCustomField": null,
                          "contributionSummary": null,
                          "suppressions": null,
                          "caseworkCases": null,
                          "caseworkIssues": null,
                          "caseworkStories": null,
                          "notes": null,
                          "scores": null,
                          "customProperties": null,
                          "electionRecords": null,
                          "membershipStatus": null,
                          "organizationRoles": null,
                          "districts": null,
                          "surveyQuestionResponses": null,
                          "finderNumber": null,
                          "biographyImageUrl": null,
                          "biographyText": null,
                          "biographyHtml": null,
                          "primaryContact": null
                        }
                      ],
                      "nextPageLink": null,
                      "count": 1
                    }
                  },
                  "search-is-a-case-insensitive-prefix-match/2": {
                    "summary": "The same characters from the middle of the name match nothing: prefix, not contains.",
                    "description": "Matching runs from the start of the field, ignoring case: `wilhel` finds Wilhelmina, `helmina` finds nothing. Hits come back as full person records in the pagination envelope, with collections null unless $expand asks for them.",
                    "x-transcript": "search-is-a-case-insensitive-prefix-match",
                    "value": {
                      "items": [],
                      "nextPageLink": null,
                      "count": 0
                    }
                  },
                  "search-phone-must-be-bare-digits/1": {
                    "summary": "Bare 10 digits: found.",
                    "description": "The comparison is against the stored 10-digit string, so `(907) 555-0137` is accepted as valid input and then silently matches no one. There is no error to catch — a formatted number just looks like a person who is not there.",
                    "x-transcript": "search-phone-must-be-bare-digits",
                    "value": {
                      "items": [
                        {
                          "vanId": 100000001,
                          "firstName": "Dashiell",
                          "lastName": "Dialtest",
                          "middleName": null,
                          "suffix": null,
                          "title": null,
                          "sourceFileTitle": null,
                          "sourceFileFirstName": null,
                          "sourceFileMiddleName": null,
                          "sourceFileLastName": null,
                          "sourceFileSuffix": null,
                          "contactSource": "API",
                          "contactMode": "Person",
                          "organizationContactCommonName": null,
                          "organizationContactOfficialName": null,
                          "salutation": null,
                          "formalSalutation": null,
                          "additionalSalutation": null,
                          "preferredPronoun": null,
                          "pronouns": null,
                          "namePronunciation": null,
                          "envelopeName": null,
                          "formalEnvelopeName": null,
                          "additionalEnvelopeName": null,
                          "contactMethodPreferenceCode": null,
                          "contactMethodPreferenceId": null,
                          "contactMethodPreferenceName": null,
                          "assistantName": null,
                          "nickname": null,
                          "website": null,
                          "professionalSuffix": null,
                          "party": null,
                          "employer": null,
                          "occupation": null,
                          "jobTitle": null,
                          "sex": null,
                          "dateOfBirth": null,
                          "isDeceased": false,
                          "dateCreated": "2026-01-01T00:00:00Z",
                          "dateAcquired": "0001-01-01T00:00:00Z",
                          "selfReportedRace": null,
                          "selfReportedEthnicity": null,
                          "selfReportedRaces": null,
                          "selfReportedEthnicities": null,
                          "selfReportedGenders": null,
                          "selfReportedSexualOrientations": null,
                          "selfReportedLanguagePreference": null,
                          "selfReportedLanguagePreferences": null,
                          "emails": null,
                          "phones": null,
                          "addresses": null,
                          "recordedAddresses": null,
                          "pollingLocation": null,
                          "earlyVoteLocation": null,
                          "identifiers": null,
                          "codes": null,
                          "customFields": null,
                          "primaryCustomField": null,
                          "contributionSummary": null,
                          "suppressions": null,
                          "caseworkCases": null,
                          "caseworkIssues": null,
                          "caseworkStories": null,
                          "notes": null,
                          "scores": null,
                          "customProperties": null,
                          "electionRecords": null,
                          "membershipStatus": null,
                          "organizationRoles": null,
                          "districts": null,
                          "surveyQuestionResponses": null,
                          "finderNumber": null,
                          "biographyImageUrl": null,
                          "biographyText": null,
                          "biographyHtml": null,
                          "primaryContact": null
                        }
                      ],
                      "nextPageLink": null,
                      "count": 1
                    }
                  },
                  "search-phone-must-be-bare-digits/2": {
                    "summary": "The same number formatted: accepted, no error — and no results.",
                    "description": "The comparison is against the stored 10-digit string, so `(907) 555-0137` is accepted as valid input and then silently matches no one. There is no error to catch — a formatted number just looks like a person who is not there.",
                    "x-transcript": "search-phone-must-be-bare-digits",
                    "value": {
                      "items": [],
                      "nextPageLink": null,
                      "count": 0
                    }
                  }
                }
              }
            },
            "links": {
              "getFirstPerson": {
                "operationId": "getPerson",
                "parameters": {
                  "vanId": "$response.body#/items/0/vanId"
                },
                "description": "Fetch the first matching person's full record (e.g. with the larger $expand set that getPerson accepts)."
              }
            }
          },
          "400": {
            "description": "Validation error. Most are INVALID_PARAMETER and name the offending query parameter in `properties`; the no-search-parameter case names the pseudo-property \"All Arguments\", and refusing an out-of-context $expand section uses code BAD_REQUEST with no `properties` or `hint` at all.",
            "x-provenance": {
              "lastProbed": "2026-08-04",
              "note": "All five examples are verbatim sandbox responses (My Campaign mode)."
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "noSearchParameter": {
                    "summary": "No search parameter set (here: only $top)",
                    "value": {
                      "errors": [
                        {
                          "code": "INVALID_PARAMETER",
                          "text": "This endpoint requires at least one search parameter to be set.",
                          "properties": [
                            "All Arguments"
                          ]
                        }
                      ]
                    }
                  },
                  "invalidPhoneNumber": {
                    "summary": "phoneNumber=555",
                    "value": {
                      "errors": [
                        {
                          "code": "INVALID_PARAMETER",
                          "text": "'phoneNumber' (555) is not a valid phone number for NorthAmerica",
                          "properties": [
                            "phoneNumber"
                          ],
                          "hint": "After non-numeric characters are removed, value must match the regular expression: ^1?[2-9][0-8]\\d[2-9]\\d{6,6}$"
                        }
                      ]
                    }
                  },
                  "invalidOrderby": {
                    "summary": "$orderby=lastName — only Name is sortable",
                    "value": {
                      "errors": [
                        {
                          "code": "INVALID_PARAMETER",
                          "text": "'lastName' is not a valid argument for the '$orderby' parameter",
                          "properties": [
                            "$orderby"
                          ],
                          "hint": "The only valid orderby property is: 'Name'"
                        }
                      ]
                    }
                  },
                  "invalidExpand": {
                    "summary": "$expand=scores — valid on GET /people/{vanId}, not here",
                    "value": {
                      "errors": [
                        {
                          "code": "INVALID_PARAMETER",
                          "text": "'scores' is not a valid argument for the '$expand' parameter",
                          "properties": [
                            "$expand"
                          ],
                          "hint": "The only valid expand sections are: 'Addresses', 'Emails', 'Phones', 'Districts', 'PollingLocation'"
                        }
                      ]
                    }
                  },
                  "expandNotAllowedInContext": {
                    "summary": "$expand=pollingLocation — listed in the hint above, but refused in My Campaign mode",
                    "value": {
                      "errors": [
                        {
                          "code": "BAD_REQUEST",
                          "text": "May not request 'pollingLocation' in this context"
                        }
                      ]
                    }
                  },
                  "search-requires-a-search-parameter/1": {
                    "summary": "Paging alone is not a search.",
                    "description": "A request with no search parameter is refused outright — even one that sets paging or filter parameters. `contactMode` is a filter, not a search parameter, so it alone does not satisfy the requirement either.",
                    "x-transcript": "search-requires-a-search-parameter",
                    "value": {
                      "errors": [
                        {
                          "code": "INVALID_PARAMETER",
                          "text": "This endpoint requires at least one search parameter to be set.",
                          "properties": [
                            "All Arguments"
                          ]
                        }
                      ]
                    }
                  },
                  "search-requires-a-search-parameter/2": {
                    "summary": "contactMode filters results but does not count as a search parameter.",
                    "description": "A request with no search parameter is refused outright — even one that sets paging or filter parameters. `contactMode` is a filter, not a search parameter, so it alone does not satisfy the requirement either.",
                    "x-transcript": "search-requires-a-search-parameter",
                    "value": {
                      "errors": [
                        {
                          "code": "INVALID_PARAMETER",
                          "text": "This endpoint requires at least one search parameter to be set.",
                          "properties": [
                            "All Arguments"
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/QueryStringTooLong"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "Text criteria match case-insensitive prefixes, never substrings",
            "source": "# Matching runs from the start of the field, ignoring case: `wilhel` finds\n# Wilhelmina, `helmina` finds nothing. Hits come back as full person records\n# in the pagination envelope, with collections null unless $expand asks for\n# them.\n\n# One person to search for. The scoped last name keeps other data out of the\n# results.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Wilhelmina\",\n    \"lastName\": \"Prefixling\",\n    \"emails\": [\n      {\n        \"email\": \"wilhelmina.prefixling@example.com\"\n      }\n    ]\n  }'\n# → 201  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Stored\"\n# }\n\n# A lowercase prefix of the first name is enough.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people?firstName=wilhel&lastName=Prefixling' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 200\n# {\n#   \"items\": [\n#     {\n#       \"vanId\": 100000001,\n#       \"firstName\": \"Wilhelmina\",\n#       \"lastName\": \"Prefixling\",\n#       \"middleName\": null,\n#       \"suffix\": null,\n#       \"title\": null,\n#       \"sourceFileTitle\": null,\n#       \"sourceFileFirstName\": null,\n#       \"sourceFileMiddleName\": null,\n#       \"sourceFileLastName\": null,\n#       \"sourceFileSuffix\": null,\n#       \"contactSource\": \"API\",\n#       \"contactMode\": \"Person\",\n#       \"organizationContactCommonName\": null,\n#       \"organizationContactOfficialName\": null,\n#       \"salutation\": null,\n#       \"formalSalutation\": null,\n#       \"additionalSalutation\": null,\n#       \"preferredPronoun\": null,\n#       \"pronouns\": null,\n#       \"namePronunciation\": null,\n#       \"envelopeName\": null,\n#       \"formalEnvelopeName\": null,\n#       \"additionalEnvelopeName\": null,\n#       \"contactMethodPreferenceCode\": null,\n#       \"contactMethodPreferenceId\": null,\n#       \"contactMethodPreferenceName\": null,\n#       \"assistantName\": null,\n#       \"nickname\": null,\n#       \"website\": null,\n#       \"professionalSuffix\": null,\n#       \"party\": null,\n#       \"employer\": null,\n#       \"occupation\": null,\n#       \"jobTitle\": null,\n#       \"sex\": null,\n#       \"dateOfBirth\": null,\n#       \"isDeceased\": false,\n#       \"dateCreated\": \"2026-01-01T00:00:00Z\",\n#       \"dateAcquired\": \"0001-01-01T00:00:00Z\",\n#       \"selfReportedRace\": null,\n#       \"selfReportedEthnicity\": null,\n#       \"selfReportedRaces\": null,\n#       \"selfReportedEthnicities\": null,\n#       \"selfReportedGenders\": null,\n#       \"selfReportedSexualOrientations\": null,\n#       \"selfReportedLanguagePreference\": null,\n#       \"selfReportedLanguagePreferences\": null,\n#       \"emails\": null,\n#       \"phones\": null,\n#       \"addresses\": null,\n#       \"recordedAddresses\": null,\n#       \"pollingLocation\": null,\n#       \"earlyVoteLocation\": null,\n#       \"identifiers\": null,\n#       \"codes\": null,\n#       \"customFields\": null,\n#       \"primaryCustomField\": null,\n#       \"contributionSummary\": null,\n#       \"suppressions\": null,\n#       \"caseworkCases\": null,\n#       \"caseworkIssues\": null,\n#       \"caseworkStories\": null,\n#       \"notes\": null,\n#       \"scores\": null,\n#       \"customProperties\": null,\n#       \"electionRecords\": null,\n#       \"membershipStatus\": null,\n#       \"organizationRoles\": null,\n#       \"districts\": null,\n#       \"surveyQuestionResponses\": null,\n#       \"finderNumber\": null,\n#       \"biographyImageUrl\": null,\n#       \"biographyText\": null,\n#       \"biographyHtml\": null,\n#       \"primaryContact\": null\n#     }\n#   ],\n#   \"nextPageLink\": null,\n#   \"count\": 1\n# }\n\n# The same characters from the middle of the name match nothing: prefix, not\n# contains.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people?firstName=helmina&lastName=Prefixling' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 200\n# {\n#   \"items\": [],\n#   \"nextPageLink\": null,\n#   \"count\": 0\n# }",
            "x-transcript": "search-is-a-case-insensitive-prefix-match"
          },
          {
            "lang": "Shell",
            "label": "Only a bare 10-digit phone number finds anyone",
            "source": "# The comparison is against the stored 10-digit string, so `(907) 555-0137`\n# is accepted as valid input and then silently matches no one. There is no\n# error to catch — a formatted number just looks like a person who is not\n# there.\n\n# A person reachable at one phone number.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Dashiell\",\n    \"lastName\": \"Dialtest\",\n    \"phones\": [\n      {\n        \"phoneNumber\": \"9075550137\"\n      }\n    ]\n  }'\n# → 201  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Stored\"\n# }\n\n# Bare 10 digits: found.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people?lastName=Dialtest&phoneNumber=9075550137' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 200\n# {\n#   \"items\": [\n#     {\n#       \"vanId\": 100000001,\n#       \"firstName\": \"Dashiell\",\n#       \"lastName\": \"Dialtest\",\n#       \"middleName\": null,\n#       \"suffix\": null,\n#       \"title\": null,\n#       \"sourceFileTitle\": null,\n#       \"sourceFileFirstName\": null,\n#       \"sourceFileMiddleName\": null,\n#       \"sourceFileLastName\": null,\n#       \"sourceFileSuffix\": null,\n#       \"contactSource\": \"API\",\n#       \"contactMode\": \"Person\",\n#       \"organizationContactCommonName\": null,\n#       \"organizationContactOfficialName\": null,\n#       \"salutation\": null,\n#       \"formalSalutation\": null,\n#       \"additionalSalutation\": null,\n#       \"preferredPronoun\": null,\n#       \"pronouns\": null,\n#       \"namePronunciation\": null,\n#       \"envelopeName\": null,\n#       \"formalEnvelopeName\": null,\n#       \"additionalEnvelopeName\": null,\n#       \"contactMethodPreferenceCode\": null,\n#       \"contactMethodPreferenceId\": null,\n#       \"contactMethodPreferenceName\": null,\n#       \"assistantName\": null,\n#       \"nickname\": null,\n#       \"website\": null,\n#       \"professionalSuffix\": null,\n#       \"party\": null,\n#       \"employer\": null,\n#       \"occupation\": null,\n#       \"jobTitle\": null,\n#       \"sex\": null,\n#       \"dateOfBirth\": null,\n#       \"isDeceased\": false,\n#       \"dateCreated\": \"2026-01-01T00:00:00Z\",\n#       \"dateAcquired\": \"0001-01-01T00:00:00Z\",\n#       \"selfReportedRace\": null,\n#       \"selfReportedEthnicity\": null,\n#       \"selfReportedRaces\": null,\n#       \"selfReportedEthnicities\": null,\n#       \"selfReportedGenders\": null,\n#       \"selfReportedSexualOrientations\": null,\n#       \"selfReportedLanguagePreference\": null,\n#       \"selfReportedLanguagePreferences\": null,\n#       \"emails\": null,\n#       \"phones\": null,\n#       \"addresses\": null,\n#       \"recordedAddresses\": null,\n#       \"pollingLocation\": null,\n#       \"earlyVoteLocation\": null,\n#       \"identifiers\": null,\n#       \"codes\": null,\n#       \"customFields\": null,\n#       \"primaryCustomField\": null,\n#       \"contributionSummary\": null,\n#       \"suppressions\": null,\n#       \"caseworkCases\": null,\n#       \"caseworkIssues\": null,\n#       \"caseworkStories\": null,\n#       \"notes\": null,\n#       \"scores\": null,\n#       \"customProperties\": null,\n#       \"electionRecords\": null,\n#       \"membershipStatus\": null,\n#       \"organizationRoles\": null,\n#       \"districts\": null,\n#       \"surveyQuestionResponses\": null,\n#       \"finderNumber\": null,\n#       \"biographyImageUrl\": null,\n#       \"biographyText\": null,\n#       \"biographyHtml\": null,\n#       \"primaryContact\": null\n#     }\n#   ],\n#   \"nextPageLink\": null,\n#   \"count\": 1\n# }\n\n# The same number formatted: accepted, no error — and no results.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people?lastName=Dialtest&phoneNumber=%28907%29+555-0137' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 200\n# {\n#   \"items\": [],\n#   \"nextPageLink\": null,\n#   \"count\": 0\n# }",
            "x-transcript": "search-phone-must-be-bare-digits"
          },
          {
            "lang": "Shell",
            "label": "At least one search parameter must be set, and filters don't count",
            "source": "# A request with no search parameter is refused outright — even one that\n# sets paging or filter parameters. `contactMode` is a filter, not a search\n# parameter, so it alone does not satisfy the requirement either.\n\n# Paging alone is not a search.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people?%24top=5' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 400\n# {\n#   \"errors\": [\n#     {\n#       \"code\": \"INVALID_PARAMETER\",\n#       \"text\": \"This endpoint requires at least one search parameter to be set.\",\n#       \"properties\": [\n#         \"All Arguments\"\n#       ]\n#     }\n#   ]\n# }\n\n# contactMode filters results but does not count as a search parameter.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people?contactMode=Person' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 400\n# {\n#   \"errors\": [\n#     {\n#       \"code\": \"INVALID_PARAMETER\",\n#       \"text\": \"This endpoint requires at least one search parameter to be set.\",\n#       \"properties\": [\n#         \"All Arguments\"\n#       ]\n#     }\n#   ]\n# }",
            "x-transcript": "search-requires-a-search-parameter"
          }
        ]
      }
    },
    "/people/find": {
      "post": {
        "operationId": "findPerson",
        "summary": "Find a person matching the given criteria",
        "description": "Attempts to match a person in the database. Read-only: never creates person records (use POST /people/findOrCreate for that).\n\nOutcomes:\n\n- **The body supplies a `vanId` that exists** — that person is returned as a **302** and every other criterion is ignored, no threshold involved.\n- **One person record matches** — **302 Found**, with a `Location` header pointing at `/people/{vanId}` and a small match-stub body, `{\"vanId\": …, \"status\": \"Matched\"}`.\n- **Several person records match** — still a **302** for exactly one of them, and nothing in the response says the match was ambiguous. Which one you get depends on the shape of the criteria; see **When more than one person record matches** below.\n- **Nothing matches** — **404** with `{\"vanId\": null, \"status\": \"Unmatched\"}` (a match stub, not the standard error envelope).\n- **The criteria fall short of the minimum combination** — **404 Unmatched** as well, not a 400, and indistinguishable from a genuine no-match. This is the common case to guard against; see **The criteria must reach a minimum combination** below.\n\n## The criteria must reach a minimum combination\n\nThis endpoint is deliberately conservative — it would rather return nothing than return the wrong person. It does not attempt a match at all until the criteria reach one of these combinations:\n\n- first name + last name + **email address**\n- first name + last name + **phone**\n- first name + last name + **zip5** + **date of birth**\n- first name + last name + **street number + street name + zip5**\n- **email address** on its own (a **phone** on its own matches too, though the docs list only email)\n\nAnything short of that — a name on its own, name + date of birth, name + zip — comes back **404 Unmatched** regardless of who is in the database.\n\n**A 404 here does not mean the person does not exist.** It usually means you did not supply enough to identify them. Do not treat Unmatched as \"not in the database\", and in particular do not follow it with a create — see POST /people/findOrCreate, which silently creates a duplicate for exactly this reason.\n\n**If all you have is a name, use GET /people instead.** That endpoint is a loose prefix search with no threshold: `GET /people?firstName=Harriet&lastName=Kowalski` returns full person records for every candidate, and you decide which one (if any) is your person by inspecting them. Use /people/find only once you hold a strong identifier.\n\n## How the criteria are compared\n\n- Everything you send must agree with the person record. Adding a **wrong** first name to a correct email turns a match into Unmatched — extra criteria narrow, they never widen.\n- Comparison is case- and format-insensitive: `HARRIET.KOWALSKI@EXAMPLE.COM` matches the stored lowercase address, `907-555-4242` matches the stored `9075554242`, and per the docs it is accent-insensitive too (\"Pérez\" matches \"Perez\"). Names may match on nicknames and variants unless the context has \"Disable Partial Matching\" turned on.\n- The address combination needs the street **number**: `742 Evergreen Terrace` + zip matched; `Evergreen Terrace` + the same zip did not. A wrong zip with a right street also fails.\n\n## When more than one person record matches\n\nDuplicates are common in VAN databases, and this endpoint does not warn you about them: **it returns exactly one vanId with no indication that others also matched.** A 302 is not proof that the match was unique.\n\nThe pick is deterministic, but the tiebreak depends on the shape of the criteria — with three identical person records (102719047 < 102719048 < 102720144, same name, email and phone):\n\n- criteria **including a name** (name+email, name+phone, name+dob+zip) → always the **lowest vanId**, i.e. the oldest person record\n- criteria **without a name** (email alone, phone alone) → always the **highest vanId**, i.e. the newest person record\n\nIt is not the best-matching person record and not the most recently updated one: enriching the newer duplicate so it matched the criteria at least as fully did not move a name-based match off the oldest person record, and touching either duplicate changed nothing.\n\nThe consequence to plan for: at the threshold you may be handed a stale or partial duplicate, and a follow-up write through POST /people/{vanId} then lands on whichever duplicate won the tiebreak while the other keeps drifting. When it matters that you have *the* person record rather than *a* person record, list the candidates with GET /people and reconcile them yourself.",
        "x-docs-discrepancy": "Official docs imply a 200 with a person object on match. Sandbox probing (2026-08-03) shows 302 + Location on match and 404 with a match stub on no match; no 400 was observed even for sparse criteria like firstName-only. Criteria below the documented minimum combinations are also answered 404 Unmatched rather than rejected, so under-specified requests are indistinguishable from genuine no-matches. The docs are also silent on ambiguous matches: when several person records satisfy the criteria the API returns one of them with no indication that others matched.",
        "x-provenance": {
          "lastProbed": "2026-08-04",
          "note": "Minimum combinations taken from the docs' Match Candidate common model (https://docs.ngpvan.com/reference/common-models) and confirmed one by one against a purpose-built sandbox person (vanId 102719047: Match Threshold, dob 1980-04-15, match.threshold@example.com, 9075554242, 742 Evergreen Terrace / 99501). Unmatched: lastName alone; firstName+lastName; firstName+lastName+dateOfBirth; firstName+lastName+zip; firstName+lastName+street-name-without-number+zip; firstName+lastName+street+wrong zip; wrong firstName + correct email. Matched: email alone; phone alone; name+email; name+phone; name+dob+zip; name+street+zip; uppercased email; phone with dashes; miscased names. Ambiguous-match behavior probed 2026-08-04 with three deliberately identical person records (102719047, 102719048, 102720144 — same name, email and phone): exactly one vanId is returned with no ambiguity signal; name-bearing criteria always returned the lowest vanId and name-less criteria (email alone, phone alone) always the highest, across repeated runs, after touching either person record, and after enriching the newer duplicate to match the criteria as fully as the older one."
        },
        "tags": [
          "People"
        ],
        "x-keywords": [
          "match",
          "identify",
          "resolve identity",
          "does this person exist",
          "lookup by email",
          "lookup by phone",
          "check for duplicate",
          "match without creating"
        ],
        "x-task": "Decide whether one specific person is already on file",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PersonMatchCriteria"
              },
              "examples": {
                "find-below-threshold-is-unmatched": {
                  "summary": "A name alone returns 404 Unmatched even when the person exists",
                  "description": "A 404 Unmatched does not mean the person is absent. Criteria that fall short of the minimum combination are never matched at all, and the answer is indistinguishable from a genuine no-match.",
                  "x-transcript": "find-below-threshold-is-unmatched",
                  "value": {
                    "firstName": "Harriet",
                    "lastName": "Kowalski"
                  }
                },
                "find-by-vanid-overrides-criteria": {
                  "summary": "A vanId in the body wins over every other criterion",
                  "description": "When the body carries a vanId, the rest of the criteria are not used to search — they are not even checked for agreement. A name that belongs to nobody still matches, so a caller who sends a stale vanId alongside fresh details gets the stale record back.",
                  "x-transcript": "find-by-vanid-overrides-criteria",
                  "value": {
                    "vanId": 100000001,
                    "firstName": "Desmond",
                    "lastName": "Pemberton"
                  }
                },
                "find-followed-redirect-returns-the-person": {
                  "summary": "Following the 302 returns the whole person, not the match stub",
                  "description": "A client that follows the redirect never sees the `{vanId, status}` stub — it ends up on GET /people/{vanId} and receives the full record with 200. This only works if the client converts to GET, as fetch and browsers do; `curl -X POST -L` keeps the method and gets 411.",
                  "x-transcript": "find-followed-redirect-returns-the-person",
                  "value": {
                    "firstName": "Harriet",
                    "lastName": "Kowalski",
                    "emails": [
                      {
                        "email": "harriet.kowalski@example.com"
                      }
                    ]
                  }
                },
                "find-minimum-match-combinations/1": {
                  "summary": "name + email → matched",
                  "description": "The endpoint does not attempt a match until the criteria reach one of a fixed set of combinations. Below that it answers 404 Unmatched rather than 400, so an under-specified query is silently indistinguishable from a person who is not there.",
                  "x-transcript": "find-minimum-match-combinations",
                  "value": {
                    "firstName": "Harriet",
                    "lastName": "Kowalski",
                    "emails": [
                      {
                        "email": "harriet.kowalski@example.com"
                      }
                    ]
                  }
                },
                "find-minimum-match-combinations/2": {
                  "summary": "name + phone → matched",
                  "description": "The endpoint does not attempt a match until the criteria reach one of a fixed set of combinations. Below that it answers 404 Unmatched rather than 400, so an under-specified query is silently indistinguishable from a person who is not there.",
                  "x-transcript": "find-minimum-match-combinations",
                  "value": {
                    "firstName": "Harriet",
                    "lastName": "Kowalski",
                    "phones": [
                      {
                        "phoneNumber": "9075554242"
                      }
                    ]
                  }
                },
                "find-minimum-match-combinations/3": {
                  "summary": "name + zip + dateOfBirth → matched",
                  "description": "The endpoint does not attempt a match until the criteria reach one of a fixed set of combinations. Below that it answers 404 Unmatched rather than 400, so an under-specified query is silently indistinguishable from a person who is not there.",
                  "x-transcript": "find-minimum-match-combinations",
                  "value": {
                    "firstName": "Harriet",
                    "lastName": "Kowalski",
                    "dateOfBirth": "1975-03-14",
                    "addresses": [
                      {
                        "zipOrPostalCode": "99501"
                      }
                    ]
                  }
                },
                "find-minimum-match-combinations/4": {
                  "summary": "name + street + zip → matched",
                  "description": "The endpoint does not attempt a match until the criteria reach one of a fixed set of combinations. Below that it answers 404 Unmatched rather than 400, so an under-specified query is silently indistinguishable from a person who is not there.",
                  "x-transcript": "find-minimum-match-combinations",
                  "value": {
                    "firstName": "Harriet",
                    "lastName": "Kowalski",
                    "addresses": [
                      {
                        "addressLine1": "742 Evergreen Terrace",
                        "city": "Springfield",
                        "stateOrProvince": "AK",
                        "zipOrPostalCode": "99501"
                      }
                    ]
                  }
                },
                "find-minimum-match-combinations/5": {
                  "summary": "email alone → matched",
                  "description": "The endpoint does not attempt a match until the criteria reach one of a fixed set of combinations. Below that it answers 404 Unmatched rather than 400, so an under-specified query is silently indistinguishable from a person who is not there.",
                  "x-transcript": "find-minimum-match-combinations",
                  "value": {
                    "emails": [
                      {
                        "email": "harriet.kowalski@example.com"
                      }
                    ]
                  }
                },
                "find-minimum-match-combinations/6": {
                  "summary": "phone alone → matched",
                  "description": "The endpoint does not attempt a match until the criteria reach one of a fixed set of combinations. Below that it answers 404 Unmatched rather than 400, so an under-specified query is silently indistinguishable from a person who is not there.",
                  "x-transcript": "find-minimum-match-combinations",
                  "value": {
                    "phones": [
                      {
                        "phoneNumber": "9075554242"
                      }
                    ]
                  }
                },
                "find-minimum-match-combinations/7": {
                  "summary": "name alone → unmatched",
                  "description": "The endpoint does not attempt a match until the criteria reach one of a fixed set of combinations. Below that it answers 404 Unmatched rather than 400, so an under-specified query is silently indistinguishable from a person who is not there.",
                  "x-transcript": "find-minimum-match-combinations",
                  "value": {
                    "firstName": "Harriet",
                    "lastName": "Kowalski"
                  }
                },
                "find-minimum-match-combinations/8": {
                  "summary": "name + dateOfBirth → unmatched",
                  "description": "The endpoint does not attempt a match until the criteria reach one of a fixed set of combinations. Below that it answers 404 Unmatched rather than 400, so an under-specified query is silently indistinguishable from a person who is not there.",
                  "x-transcript": "find-minimum-match-combinations",
                  "value": {
                    "firstName": "Harriet",
                    "lastName": "Kowalski",
                    "dateOfBirth": "1975-03-14"
                  }
                },
                "find-minimum-match-combinations/9": {
                  "summary": "name + zip → unmatched",
                  "description": "The endpoint does not attempt a match until the criteria reach one of a fixed set of combinations. Below that it answers 404 Unmatched rather than 400, so an under-specified query is silently indistinguishable from a person who is not there.",
                  "x-transcript": "find-minimum-match-combinations",
                  "value": {
                    "firstName": "Harriet",
                    "lastName": "Kowalski",
                    "addresses": [
                      {
                        "zipOrPostalCode": "99501"
                      }
                    ]
                  }
                },
                "find-minimum-match-combinations/10": {
                  "summary": "street + zip, no name → unmatched",
                  "description": "The endpoint does not attempt a match until the criteria reach one of a fixed set of combinations. Below that it answers 404 Unmatched rather than 400, so an under-specified query is silently indistinguishable from a person who is not there.",
                  "x-transcript": "find-minimum-match-combinations",
                  "value": {
                    "addresses": [
                      {
                        "addressLine1": "742 Evergreen Terrace",
                        "city": "Springfield",
                        "stateOrProvince": "AK",
                        "zipOrPostalCode": "99501"
                      }
                    ]
                  }
                },
                "find-minimum-match-combinations/11": {
                  "summary": "wrong name + right email → unmatched",
                  "description": "The endpoint does not attempt a match until the criteria reach one of a fixed set of combinations. Below that it answers 404 Unmatched rather than 400, so an under-specified query is silently indistinguishable from a person who is not there.",
                  "x-transcript": "find-minimum-match-combinations",
                  "value": {
                    "firstName": "Gregory",
                    "lastName": "Kowalski",
                    "emails": [
                      {
                        "email": "harriet.kowalski@example.com"
                      }
                    ]
                  }
                },
                "find-returns-first-created-duplicate": {
                  "summary": "With duplicates, name-based criteria return the first-created record",
                  "description": "When several records match, exactly one vanId comes back and nothing in the response says the match was ambiguous. Criteria including a name resolve to the oldest record.",
                  "x-transcript": "find-returns-first-created-duplicate",
                  "value": {
                    "firstName": "Harriet",
                    "lastName": "Kowalski",
                    "emails": [
                      {
                        "email": "harriet.kowalski@example.com"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Never sent by this endpoint. This is where a redirect-following client *lands* on a match:\n\n```\nPOST /people/find              {\"firstName\": \"Ada\", \"lastName\": \"Testperson\", …}\n  ← 302 Found\n    Location: https://api.securevan.com/v4/people/102714507\n    {\"vanId\": 102714507, \"status\": \"Matched\"}\n\nGET /people/102714507          ← client re-issues the request at Location\n  ← 200 OK\n    { full person record — the body documented here }\n```\n\nrequests, httpx, fetch and `curl -L` all follow that redirect and downgrade POST to GET by default, so a match reaches your code as this 200 and a full `Person`, never as the 302 and its two-field match stub. The no-match 404 is not a redirect, so the practical test is `resp.status_code == 200` vs `404`, not `302` vs `404`. The follow-up GET has no `$expand`, so its related collections come back null — re-fetch through the `getMatchedPerson` link if you need addresses, phones or emails.\n\nGotcha: `curl -X POST -L` keeps the method across the redirect and re-POSTs to `/people/{vanId}` — the *update* endpoint — where IIS answers `411 Length Required` because the re-issued request carries no body. Drop the explicit `-X POST` (`-d` already implies POST) and curl downgrades to GET like everything else.",
            "x-provenance": {
              "lastProbed": "2026-08-04",
              "note": "Chain observed end to end with httpx and requests (both: 302 → GET → 200 Person) and with curl 8.7.1 both ways (`-d` alone → GET → 200; `-X POST -L` → POST /people/{vanId} → 411). Documented alongside the raw 302 so both redirect-following clients and raw clients (including the schemathesis fuzzer) conform to this spec."
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Person"
                },
                "examples": {
                  "find-followed-redirect-returns-the-person": {
                    "summary": "Following the 302 returns the whole person, not the match stub",
                    "description": "A client that follows the redirect never sees the `{vanId, status}` stub — it ends up on GET /people/{vanId} and receives the full record with 200. This only works if the client converts to GET, as fetch and browsers do; `curl -X POST -L` keeps the method and gets 411.",
                    "x-transcript": "find-followed-redirect-returns-the-person",
                    "value": {
                      "vanId": 100000001,
                      "firstName": "Harriet",
                      "lastName": "Kowalski",
                      "middleName": null,
                      "suffix": null,
                      "title": null,
                      "sourceFileTitle": null,
                      "sourceFileFirstName": null,
                      "sourceFileMiddleName": null,
                      "sourceFileLastName": null,
                      "sourceFileSuffix": null,
                      "contactSource": "API",
                      "contactMode": "Person",
                      "organizationContactCommonName": null,
                      "organizationContactOfficialName": null,
                      "salutation": "Harriet",
                      "formalSalutation": "Harriet Kowalski",
                      "additionalSalutation": null,
                      "preferredPronoun": null,
                      "pronouns": null,
                      "namePronunciation": null,
                      "envelopeName": "Harriet Kowalski",
                      "formalEnvelopeName": "Harriet Kowalski",
                      "additionalEnvelopeName": null,
                      "contactMethodPreferenceCode": null,
                      "contactMethodPreferenceId": null,
                      "contactMethodPreferenceName": null,
                      "assistantName": null,
                      "nickname": null,
                      "website": null,
                      "professionalSuffix": null,
                      "party": null,
                      "employer": null,
                      "occupation": null,
                      "jobTitle": null,
                      "sex": null,
                      "dateOfBirth": "1975-03-14T00:00:00Z",
                      "isDeceased": false,
                      "partialDateOfBirth": {
                        "month": 3,
                        "day": 14,
                        "year": 1975
                      },
                      "dateCreated": "2026-01-01T00:00:00Z",
                      "dateAcquired": "0001-01-01T00:00:00Z",
                      "selfReportedRace": null,
                      "selfReportedEthnicity": null,
                      "selfReportedRaces": null,
                      "selfReportedEthnicities": null,
                      "selfReportedGenders": null,
                      "selfReportedSexualOrientations": null,
                      "selfReportedLanguagePreference": null,
                      "selfReportedLanguagePreferences": null,
                      "emails": null,
                      "phones": null,
                      "addresses": null,
                      "recordedAddresses": null,
                      "pollingLocation": null,
                      "earlyVoteLocation": null,
                      "identifiers": null,
                      "codes": null,
                      "customFields": null,
                      "primaryCustomField": null,
                      "contributionSummary": null,
                      "suppressions": null,
                      "caseworkCases": null,
                      "caseworkIssues": null,
                      "caseworkStories": null,
                      "notes": null,
                      "scores": null,
                      "customProperties": null,
                      "electionRecords": null,
                      "membershipStatus": null,
                      "organizationRoles": null,
                      "districts": null,
                      "surveyQuestionResponses": null,
                      "finderNumber": null,
                      "biographyImageUrl": null,
                      "biographyText": null,
                      "biographyHtml": null,
                      "primaryContact": null
                    }
                  }
                }
              }
            },
            "links": {
              "getMatchedPerson": {
                "operationId": "getPerson",
                "parameters": {
                  "vanId": "$response.body#/vanId"
                },
                "description": "Re-fetch the matched person by id (e.g. with $expand for related collections)."
              }
            }
          },
          "302": {
            "description": "A person matched the criteria. `Location` header points at the canonical person resource.",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/MatchedPersonLocation"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PersonMatched"
                },
                "examples": {
                  "find-by-vanid-overrides-criteria": {
                    "summary": "A vanId in the body wins over every other criterion",
                    "description": "When the body carries a vanId, the rest of the criteria are not used to search — they are not even checked for agreement. A name that belongs to nobody still matches, so a caller who sends a stale vanId alongside fresh details gets the stale record back.",
                    "x-transcript": "find-by-vanid-overrides-criteria",
                    "value": {
                      "vanId": 100000001,
                      "status": "Matched"
                    }
                  },
                  "find-minimum-match-combinations/1": {
                    "summary": "name + email → matched",
                    "description": "The endpoint does not attempt a match until the criteria reach one of a fixed set of combinations. Below that it answers 404 Unmatched rather than 400, so an under-specified query is silently indistinguishable from a person who is not there.",
                    "x-transcript": "find-minimum-match-combinations",
                    "value": {
                      "vanId": 100000001,
                      "status": "Matched"
                    }
                  },
                  "find-minimum-match-combinations/2": {
                    "summary": "name + phone → matched",
                    "description": "The endpoint does not attempt a match until the criteria reach one of a fixed set of combinations. Below that it answers 404 Unmatched rather than 400, so an under-specified query is silently indistinguishable from a person who is not there.",
                    "x-transcript": "find-minimum-match-combinations",
                    "value": {
                      "vanId": 100000001,
                      "status": "Matched"
                    }
                  },
                  "find-minimum-match-combinations/3": {
                    "summary": "name + zip + dateOfBirth → matched",
                    "description": "The endpoint does not attempt a match until the criteria reach one of a fixed set of combinations. Below that it answers 404 Unmatched rather than 400, so an under-specified query is silently indistinguishable from a person who is not there.",
                    "x-transcript": "find-minimum-match-combinations",
                    "value": {
                      "vanId": 100000001,
                      "status": "Matched"
                    }
                  },
                  "find-minimum-match-combinations/4": {
                    "summary": "name + street + zip → matched",
                    "description": "The endpoint does not attempt a match until the criteria reach one of a fixed set of combinations. Below that it answers 404 Unmatched rather than 400, so an under-specified query is silently indistinguishable from a person who is not there.",
                    "x-transcript": "find-minimum-match-combinations",
                    "value": {
                      "vanId": 100000001,
                      "status": "Matched"
                    }
                  },
                  "find-minimum-match-combinations/5": {
                    "summary": "email alone → matched",
                    "description": "The endpoint does not attempt a match until the criteria reach one of a fixed set of combinations. Below that it answers 404 Unmatched rather than 400, so an under-specified query is silently indistinguishable from a person who is not there.",
                    "x-transcript": "find-minimum-match-combinations",
                    "value": {
                      "vanId": 100000001,
                      "status": "Matched"
                    }
                  },
                  "find-minimum-match-combinations/6": {
                    "summary": "phone alone → matched",
                    "description": "The endpoint does not attempt a match until the criteria reach one of a fixed set of combinations. Below that it answers 404 Unmatched rather than 400, so an under-specified query is silently indistinguishable from a person who is not there.",
                    "x-transcript": "find-minimum-match-combinations",
                    "value": {
                      "vanId": 100000001,
                      "status": "Matched"
                    }
                  },
                  "find-returns-first-created-duplicate": {
                    "summary": "With duplicates, name-based criteria return the first-created record",
                    "description": "When several records match, exactly one vanId comes back and nothing in the response says the match was ambiguous. Criteria including a name resolve to the oldest record.",
                    "x-transcript": "find-returns-first-created-duplicate",
                    "value": {
                      "vanId": 100000001,
                      "status": "Matched"
                    }
                  }
                }
              }
            },
            "links": {
              "getMatchedPerson": {
                "operationId": "getPerson",
                "parameters": {
                  "vanId": "$response.body#/vanId"
                },
                "description": "Fetch the matched person's full record — equivalent to following the Location header."
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No person matched the criteria.\n\nThis is also the answer when the criteria never reached the minimum combination needed to attempt a match at all — there is no 400 and nothing in the body distinguishes the two cases. **Read it as \"not identified\", not \"not in the database\":** a person you can see through GET /people will still come back Unmatched here if all you sent was their name. See the operation description for the combinations that do trigger a match.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PersonUnmatched"
                },
                "examples": {
                  "find-below-threshold-is-unmatched": {
                    "summary": "A name alone returns 404 Unmatched even when the person exists",
                    "description": "A 404 Unmatched does not mean the person is absent. Criteria that fall short of the minimum combination are never matched at all, and the answer is indistinguishable from a genuine no-match.",
                    "x-transcript": "find-below-threshold-is-unmatched",
                    "value": {
                      "vanId": null,
                      "status": "Unmatched"
                    }
                  },
                  "find-minimum-match-combinations/7": {
                    "summary": "name alone → unmatched",
                    "description": "The endpoint does not attempt a match until the criteria reach one of a fixed set of combinations. Below that it answers 404 Unmatched rather than 400, so an under-specified query is silently indistinguishable from a person who is not there.",
                    "x-transcript": "find-minimum-match-combinations",
                    "value": {
                      "vanId": null,
                      "status": "Unmatched"
                    }
                  },
                  "find-minimum-match-combinations/8": {
                    "summary": "name + dateOfBirth → unmatched",
                    "description": "The endpoint does not attempt a match until the criteria reach one of a fixed set of combinations. Below that it answers 404 Unmatched rather than 400, so an under-specified query is silently indistinguishable from a person who is not there.",
                    "x-transcript": "find-minimum-match-combinations",
                    "value": {
                      "vanId": null,
                      "status": "Unmatched"
                    }
                  },
                  "find-minimum-match-combinations/9": {
                    "summary": "name + zip → unmatched",
                    "description": "The endpoint does not attempt a match until the criteria reach one of a fixed set of combinations. Below that it answers 404 Unmatched rather than 400, so an under-specified query is silently indistinguishable from a person who is not there.",
                    "x-transcript": "find-minimum-match-combinations",
                    "value": {
                      "vanId": null,
                      "status": "Unmatched"
                    }
                  },
                  "find-minimum-match-combinations/10": {
                    "summary": "street + zip, no name → unmatched",
                    "description": "The endpoint does not attempt a match until the criteria reach one of a fixed set of combinations. Below that it answers 404 Unmatched rather than 400, so an under-specified query is silently indistinguishable from a person who is not there.",
                    "x-transcript": "find-minimum-match-combinations",
                    "value": {
                      "vanId": null,
                      "status": "Unmatched"
                    }
                  },
                  "find-minimum-match-combinations/11": {
                    "summary": "wrong name + right email → unmatched",
                    "description": "The endpoint does not attempt a match until the criteria reach one of a fixed set of combinations. Below that it answers 404 Unmatched rather than 400, so an under-specified query is silently indistinguishable from a person who is not there.",
                    "x-transcript": "find-minimum-match-combinations",
                    "value": {
                      "vanId": null,
                      "status": "Unmatched"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "A name alone returns 404 Unmatched even when the person exists",
            "source": "# A 404 Unmatched does not mean the person is absent. Criteria that fall\n# short of the minimum combination are never matched at all, and the answer\n# is indistinguishable from a genuine no-match.\n\n# Put a person in the database, carrying every identifier the match can ask\n# for.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Harriet\",\n    \"lastName\": \"Kowalski\",\n    \"dateOfBirth\": \"1975-03-14\",\n    \"emails\": [\n      {\n        \"email\": \"harriet.kowalski@example.com\"\n      }\n    ],\n    \"phones\": [\n      {\n        \"phoneNumber\": \"9075554242\"\n      }\n    ],\n    \"addresses\": [\n      {\n        \"addressLine1\": \"742 Evergreen Terrace\",\n        \"city\": \"Springfield\",\n        \"stateOrProvince\": \"AK\",\n        \"zipOrPostalCode\": \"99501\"\n      }\n    ]\n  }'\n# → 201  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Stored\"\n# }\n\n# Now look for them by name alone. The person is unambiguously there — we\n# just created them — but name alone is below the minimum combination, so no\n# match is attempted at all.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/find' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Harriet\",\n    \"lastName\": \"Kowalski\"\n  }'\n# → 404\n# {\n#   \"vanId\": null,\n#   \"status\": \"Unmatched\"\n# }",
            "x-transcript": "find-below-threshold-is-unmatched"
          },
          {
            "lang": "Shell",
            "label": "A vanId in the body wins over every other criterion",
            "source": "# When the body carries a vanId, the rest of the criteria are not used to\n# search — they are not even checked for agreement. A name that belongs to\n# nobody still matches, so a caller who sends a stale vanId alongside fresh\n# details gets the stale record back.\n\n# One person to aim at.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Harriet\",\n    \"lastName\": \"Kowalski\",\n    \"dateOfBirth\": \"1975-03-14\",\n    \"emails\": [\n      {\n        \"email\": \"harriet.kowalski@example.com\"\n      }\n    ],\n    \"phones\": [\n      {\n        \"phoneNumber\": \"9075554242\"\n      }\n    ],\n    \"addresses\": [\n      {\n        \"addressLine1\": \"742 Evergreen Terrace\",\n        \"city\": \"Springfield\",\n        \"stateOrProvince\": \"AK\",\n        \"zipOrPostalCode\": \"99501\"\n      }\n    ]\n  }'\n# → 201  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Stored\"\n# }\n\n# Ask for that vanId while giving a name that matches no record at all. The\n# contradiction is ignored: the vanId decides the answer by itself.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/find' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"vanId\": 100000001,\n    \"firstName\": \"Desmond\",\n    \"lastName\": \"Pemberton\"\n  }'\n# → 302  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Matched\"\n# }",
            "x-transcript": "find-by-vanid-overrides-criteria"
          },
          {
            "lang": "Shell",
            "label": "Following the 302 returns the whole person, not the match stub",
            "source": "# A client that follows the redirect never sees the `{vanId, status}` stub —\n# it ends up on GET /people/{vanId} and receives the full record with 200.\n# This only works if the client converts to GET, as fetch and browsers do;\n# `curl -X POST -L` keeps the method and gets 411.\n\n# A person to match, carrying enough identifiers to clear the threshold.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Harriet\",\n    \"lastName\": \"Kowalski\",\n    \"dateOfBirth\": \"1975-03-14\",\n    \"emails\": [\n      {\n        \"email\": \"harriet.kowalski@example.com\"\n      }\n    ],\n    \"phones\": [\n      {\n        \"phoneNumber\": \"9075554242\"\n      }\n    ],\n    \"addresses\": [\n      {\n        \"addressLine1\": \"742 Evergreen Terrace\",\n        \"city\": \"Springfield\",\n        \"stateOrProvince\": \"AK\",\n        \"zipOrPostalCode\": \"99501\"\n      }\n    ]\n  }'\n# → 201  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Stored\"\n# }\n\n# Same find as ever, but this client follows the redirect. The 200 below\n# came from GET /people/{vanId} at the end of the chain, which is why it is\n# a whole person.\n\ncurl -sS -L 'https://api.securevan.com/v4/people/find' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Harriet\",\n    \"lastName\": \"Kowalski\",\n    \"emails\": [\n      {\n        \"email\": \"harriet.kowalski@example.com\"\n      }\n    ]\n  }'\n# → 200\n# {\n#   \"vanId\": 100000001,\n#   \"firstName\": \"Harriet\",\n#   \"lastName\": \"Kowalski\",\n#   \"middleName\": null,\n#   \"suffix\": null,\n#   \"title\": null,\n#   \"sourceFileTitle\": null,\n#   \"sourceFileFirstName\": null,\n#   \"sourceFileMiddleName\": null,\n#   \"sourceFileLastName\": null,\n#   \"sourceFileSuffix\": null,\n#   \"contactSource\": \"API\",\n#   \"contactMode\": \"Person\",\n#   \"organizationContactCommonName\": null,\n#   \"organizationContactOfficialName\": null,\n#   \"salutation\": \"Harriet\",\n#   \"formalSalutation\": \"Harriet Kowalski\",\n#   \"additionalSalutation\": null,\n#   \"preferredPronoun\": null,\n#   \"pronouns\": null,\n#   \"namePronunciation\": null,\n#   \"envelopeName\": \"Harriet Kowalski\",\n#   \"formalEnvelopeName\": \"Harriet Kowalski\",\n#   \"additionalEnvelopeName\": null,\n#   \"contactMethodPreferenceCode\": null,\n#   \"contactMethodPreferenceId\": null,\n#   \"contactMethodPreferenceName\": null,\n#   \"assistantName\": null,\n#   \"nickname\": null,\n#   \"website\": null,\n#   \"professionalSuffix\": null,\n#   \"party\": null,\n#   \"employer\": null,\n#   \"occupation\": null,\n#   \"jobTitle\": null,\n#   \"sex\": null,\n#   \"dateOfBirth\": \"1975-03-14T00:00:00Z\",\n#   \"isDeceased\": false,\n#   \"partialDateOfBirth\": {\n#     \"month\": 3,\n#     \"day\": 14,\n#     \"year\": 1975\n#   },\n#   \"dateCreated\": \"2026-01-01T00:00:00Z\",\n#   \"dateAcquired\": \"0001-01-01T00:00:00Z\",\n#   \"selfReportedRace\": null,\n#   \"selfReportedEthnicity\": null,\n#   \"selfReportedRaces\": null,\n#   \"selfReportedEthnicities\": null,\n#   \"selfReportedGenders\": null,\n#   \"selfReportedSexualOrientations\": null,\n#   \"selfReportedLanguagePreference\": null,\n#   \"selfReportedLanguagePreferences\": null,\n#   \"emails\": null,\n#   \"phones\": null,\n#   \"addresses\": null,\n#   \"recordedAddresses\": null,\n#   \"pollingLocation\": null,\n#   \"earlyVoteLocation\": null,\n#   \"identifiers\": null,\n#   \"codes\": null,\n#   \"customFields\": null,\n#   \"primaryCustomField\": null,\n#   \"contributionSummary\": null,\n#   \"suppressions\": null,\n#   \"caseworkCases\": null,\n#   \"caseworkIssues\": null,\n#   \"caseworkStories\": null,\n#   \"notes\": null,\n#   \"scores\": null,\n#   \"customProperties\": null,\n#   \"electionRecords\": null,\n#   \"membershipStatus\": null,\n#   \"organizationRoles\": null,\n#   \"districts\": null,\n#   \"surveyQuestionResponses\": null,\n#   \"finderNumber\": null,\n#   \"biographyImageUrl\": null,\n#   \"biographyText\": null,\n#   \"biographyHtml\": null,\n#   \"primaryContact\": null\n# }",
            "x-transcript": "find-followed-redirect-returns-the-person"
          },
          {
            "lang": "Shell",
            "label": "Only certain criteria combinations are matched at all",
            "source": "# The endpoint does not attempt a match until the criteria reach one of a\n# fixed set of combinations. Below that it answers 404 Unmatched rather than\n# 400, so an under-specified query is silently indistinguishable from a\n# person who is not there.\n\n# One person, holding every identifier, so only the criteria vary below.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Harriet\",\n    \"lastName\": \"Kowalski\",\n    \"dateOfBirth\": \"1975-03-14\",\n    \"emails\": [\n      {\n        \"email\": \"harriet.kowalski@example.com\"\n      }\n    ],\n    \"phones\": [\n      {\n        \"phoneNumber\": \"9075554242\"\n      }\n    ],\n    \"addresses\": [\n      {\n        \"addressLine1\": \"742 Evergreen Terrace\",\n        \"city\": \"Springfield\",\n        \"stateOrProvince\": \"AK\",\n        \"zipOrPostalCode\": \"99501\"\n      }\n    ]\n  }'\n# → 201  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Stored\"\n# }\n\n# name + email → matched\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/find' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Harriet\",\n    \"lastName\": \"Kowalski\",\n    \"emails\": [\n      {\n        \"email\": \"harriet.kowalski@example.com\"\n      }\n    ]\n  }'\n# → 302  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Matched\"\n# }\n\n# name + phone → matched\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/find' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Harriet\",\n    \"lastName\": \"Kowalski\",\n    \"phones\": [\n      {\n        \"phoneNumber\": \"9075554242\"\n      }\n    ]\n  }'\n# → 302  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Matched\"\n# }\n\n# name + zip + dateOfBirth → matched\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/find' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Harriet\",\n    \"lastName\": \"Kowalski\",\n    \"dateOfBirth\": \"1975-03-14\",\n    \"addresses\": [\n      {\n        \"zipOrPostalCode\": \"99501\"\n      }\n    ]\n  }'\n# → 302  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Matched\"\n# }\n\n# name + street + zip → matched\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/find' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Harriet\",\n    \"lastName\": \"Kowalski\",\n    \"addresses\": [\n      {\n        \"addressLine1\": \"742 Evergreen Terrace\",\n        \"city\": \"Springfield\",\n        \"stateOrProvince\": \"AK\",\n        \"zipOrPostalCode\": \"99501\"\n      }\n    ]\n  }'\n# → 302  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Matched\"\n# }\n\n# email alone → matched\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/find' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"emails\": [\n      {\n        \"email\": \"harriet.kowalski@example.com\"\n      }\n    ]\n  }'\n# → 302  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Matched\"\n# }\n\n# phone alone → matched\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/find' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"phones\": [\n      {\n        \"phoneNumber\": \"9075554242\"\n      }\n    ]\n  }'\n# → 302  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Matched\"\n# }\n\n# name alone → unmatched\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/find' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Harriet\",\n    \"lastName\": \"Kowalski\"\n  }'\n# → 404\n# {\n#   \"vanId\": null,\n#   \"status\": \"Unmatched\"\n# }\n\n# name + dateOfBirth → unmatched\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/find' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Harriet\",\n    \"lastName\": \"Kowalski\",\n    \"dateOfBirth\": \"1975-03-14\"\n  }'\n# → 404\n# {\n#   \"vanId\": null,\n#   \"status\": \"Unmatched\"\n# }\n\n# name + zip → unmatched\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/find' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Harriet\",\n    \"lastName\": \"Kowalski\",\n    \"addresses\": [\n      {\n        \"zipOrPostalCode\": \"99501\"\n      }\n    ]\n  }'\n# → 404\n# {\n#   \"vanId\": null,\n#   \"status\": \"Unmatched\"\n# }\n\n# street + zip, no name → unmatched\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/find' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"addresses\": [\n      {\n        \"addressLine1\": \"742 Evergreen Terrace\",\n        \"city\": \"Springfield\",\n        \"stateOrProvince\": \"AK\",\n        \"zipOrPostalCode\": \"99501\"\n      }\n    ]\n  }'\n# → 404\n# {\n#   \"vanId\": null,\n#   \"status\": \"Unmatched\"\n# }\n\n# wrong name + right email → unmatched\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/find' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Gregory\",\n    \"lastName\": \"Kowalski\",\n    \"emails\": [\n      {\n        \"email\": \"harriet.kowalski@example.com\"\n      }\n    ]\n  }'\n# → 404\n# {\n#   \"vanId\": null,\n#   \"status\": \"Unmatched\"\n# }",
            "x-transcript": "find-minimum-match-combinations"
          },
          {
            "lang": "Shell",
            "label": "With duplicates, name-based criteria return the first-created record",
            "source": "# When several records match, exactly one vanId comes back and nothing in\n# the response says the match was ambiguous. Criteria including a name\n# resolve to the oldest record.\n\nCREATE_BODY='{\n  \"firstName\": \"Harriet\",\n  \"lastName\": \"Kowalski\",\n  \"dateOfBirth\": \"1975-03-14\",\n  \"emails\": [\n    {\n      \"email\": \"harriet.kowalski@example.com\"\n    }\n  ],\n  \"phones\": [\n    {\n      \"phoneNumber\": \"9075554242\"\n    }\n  ],\n  \"addresses\": [\n    {\n      \"addressLine1\": \"742 Evergreen Terrace\",\n      \"city\": \"Springfield\",\n      \"stateOrProvince\": \"AK\",\n      \"zipOrPostalCode\": \"99501\"\n    }\n  ]\n}'\n\n# Create three records that are identical in every field.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"$CREATE_BODY\"\n# → 201  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Stored\"\n# }\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"$CREATE_BODY\"\n# → 201  Location: https://api.securevan.com/v4/people/100000002\n# {\n#   \"vanId\": 100000002,\n#   \"status\": \"Stored\"\n# }\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"$CREATE_BODY\"\n# → 201  Location: https://api.securevan.com/v4/people/100000003\n# {\n#   \"vanId\": 100000003,\n#   \"status\": \"Stored\"\n# }\n\n# All three match these criteria equally well. Exactly one vanId comes back,\n# with nothing to say the other two exist — and it is the first one created.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/find' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Harriet\",\n    \"lastName\": \"Kowalski\",\n    \"emails\": [\n      {\n        \"email\": \"harriet.kowalski@example.com\"\n      }\n    ]\n  }'\n# → 302  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Matched\"\n# }",
            "x-transcript": "find-returns-first-created-duplicate"
          }
        ]
      }
    },
    "/people/findOrCreate": {
      "post": {
        "operationId": "findOrCreatePerson",
        "summary": "Find a person, or create one if nothing matches",
        "description": "Runs the same match as POST /people/find and, when nothing matches, stores the payload as a new person record.\n\nOutcomes:\n\n- **The body supplies a `vanId` that exists** — the match is short-circuited, that person is returned as **302 Found**, and nothing is created.\n- **The body supplies a `vanId` that matches nothing** — no error, and none of POST /people/create's blind echo: the id is ignored and the ordinary match runs on the rest of the payload — 302 when that matches, 201 UnmatchedStored when it does not.\n- **One person record matches** — **302 Found**, with a `Location` header and `{\"vanId\": …, \"status\": \"Matched\"}`.\n- **Several person records match** — still a **302** for exactly one of them, with nothing in the response to say the match was ambiguous. See POST /people/find for which one you get.\n- **Nothing matches** — **201 Created** with `{\"vanId\": …, \"status\": \"UnmatchedStored\"}`, and the payload is stored as a new person record. Unlike find, this never returns 404 — the no-match case is the create case.\n- **The criteria fall short of the minimum combination** — **201 Created** as well: a brand-new person record, even when the person is already in the database. This is the duplicate trap; see **The match half has a minimum threshold** below.\n- **The body is empty (`{}`)** — every field is optional, including the name, so this is a no-match: **201** and a blank person record is created.\n\n## The match half has a minimum threshold — below it, you create duplicates\n\nThe match runs under the same rules as POST /people/find: nothing is searched until the payload reaches one of these combinations:\n\n- first name + last name + **email address**\n- first name + last name + **phone**\n- first name + last name + **zip5** + **date of birth**\n- first name + last name + **street number + street name + zip5**\n- **email address** on its own (a **phone** on its own works too)\n\n**Below the threshold there is no \"unmatched\" to inspect — the API just creates a second person record.** Posting `{\"firstName\": \"Harriet\", \"lastName\": \"Kowalski\"}` for a person who is already in the database returns 201 with a fresh vanId, and the two person records now both exist. This is the main way duplicate person records get into a VAN database through the API.\n\nSo: only send a payload here that carries a strong identifier. If all you have is a name, search with GET /people first, decide for yourself whether a candidate is your person, and update it by id through POST /people/{vanId} instead.",
        "x-provenance": {
          "lastProbed": "2026-08-04",
          "note": "Not in the official docs' page index; the path comes from van-cli (people.ts findOrCreate), which requires firstName and lastName client-side. The API itself requires neither — an empty body was accepted (observed 2026-08-03). Threshold behavior confirmed 2026-08-04: firstName+lastName for existing vanId 102719047 created duplicate 102719048 (201 UnmatchedStored); the same name plus the person's email returned 302 Matched."
        },
        "x-docs-discrepancy": "The docs present the minimum match combinations as a matching quality note; in practice, on this endpoint, falling short of them is what silently produces duplicate person records (observed 2026-08-04).",
        "tags": [
          "People"
        ],
        "x-keywords": [
          "upsert",
          "match or create",
          "get or create",
          "signup",
          "intake",
          "add if missing",
          "register a supporter",
          "form submission"
        ],
        "x-task": "Create a person, reusing an existing record when there is one",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PersonInput"
              },
              "examples": {
                "nameAndEmail": {
                  "summary": "Name + email",
                  "value": {
                    "firstName": "Grace",
                    "lastName": "Testperson",
                    "emails": [
                      {
                        "email": "grace.testperson@example.com",
                        "type": "W",
                        "isPreferred": true
                      }
                    ]
                  }
                },
                "fullContact": {
                  "summary": "Name + phone + address",
                  "value": {
                    "firstName": "Grace",
                    "lastName": "Testperson",
                    "phones": [
                      {
                        "phoneNumber": "907-555-0142",
                        "phoneType": "C",
                        "ext": "123",
                        "isPreferred": true,
                        "phoneOptInStatus": "I"
                      }
                    ],
                    "addresses": [
                      {
                        "addressLine1": "123 Test St",
                        "addressLine2": "Apt 4",
                        "city": "Anchorage",
                        "stateOrProvince": "AK",
                        "zipOrPostalCode": "99501",
                        "type": "Home"
                      }
                    ]
                  }
                },
                "empty-bodies-create-blank-people": {
                  "summary": "An empty body creates a blank person record",
                  "description": "Every field is optional, including the name, so `{}` is a valid payload on both create endpoints: create answers 201 Stored, and findOrCreate — with no criteria to match on — answers 201 UnmatchedStored. Each call leaves a nameless person record behind.",
                  "x-transcript": "empty-bodies-create-blank-people",
                  "value": {}
                },
                "findorcreate-below-threshold-creates-a-duplicate": {
                  "summary": "Below the match threshold, findOrCreate quietly creates a duplicate",
                  "description": "A name alone never reaches the minimum match combination, so no match is attempted: the payload is stored as a brand-new person record even though the person is already in the database. There is no 'unmatched' to inspect — the no-match case is the create case.",
                  "x-transcript": "findorcreate-below-threshold-creates-a-duplicate",
                  "value": {
                    "firstName": "Harriet",
                    "lastName": "Duplicata"
                  }
                },
                "findorcreate-ignores-an-unknown-vanid": {
                  "summary": "findOrCreate drops a vanId that matches nothing",
                  "description": "Where create echoes a plausible unknown vanId back as a phantom match, findOrCreate just drops it: the ordinary match runs on the rest of the payload — here finding the existing person by name and email — and would have created a person had it found nothing. The vanId only matters when it names a real person.",
                  "x-transcript": "findorcreate-ignores-an-unknown-vanid",
                  "value": {
                    "vanId": 100777777,
                    "firstName": "Ignesia",
                    "lastName": "Vanidless",
                    "emails": [
                      {
                        "email": "ignesia.vanidless@example.com"
                      }
                    ]
                  }
                },
                "findorcreate-returns-the-existing-match": {
                  "summary": "Above the match threshold, findOrCreate returns the existing person",
                  "description": "Name plus email clears the minimum match combination, so the existing person comes back as a 302 match stub with a Location header, and nothing is written.",
                  "x-transcript": "findorcreate-returns-the-existing-match",
                  "value": {
                    "firstName": "Marisol",
                    "lastName": "Vega",
                    "emails": [
                      {
                        "email": "marisol.vega@example.com"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Never sent by this endpoint. This is where a redirect-following client *lands* after a match:\n\n```\nPOST /people/findOrCreate      {\"vanId\": 102714558}\n  ← 302 Found\n    Location: https://api.securevan.com/v4/people/102714558\n    {\"vanId\": 102714558, \"status\": \"Matched\"}\n\nGET /people/102714558          ← client re-issues the request at Location\n  ← 200 OK\n    { full person record — the body documented here }\n```\n\nSo on a match your code sees this 200 and a full `Person`, not the 302 and its two-field match stub. `resp.history` (requests/httpx) or `resp.redirected` (fetch) is how you tell this apart from the 201 create path, which sends no `Location` and is never rewritten this way. See POST /people/find for the full redirect-following notes, including the `curl -X POST -L` gotcha.",
            "x-provenance": {
              "lastProbed": "2026-08-04",
              "note": "Chain observed end to end with httpx and requests (both: 302 → GET → 200 Person) and with curl 8.7.1 both ways (`-d` alone → GET → 200; `-X POST -L` → POST /people/{vanId} → 411)."
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Person"
                }
              }
            }
          },
          "201": {
            "description": "Nothing matched, so a new person record was created. No `Location` header is sent — the new id is in the body, and redirect-following clients see this response unchanged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PersonUnmatchedStored"
                },
                "examples": {
                  "empty-bodies-create-blank-people": {
                    "summary": "An empty body creates a blank person record",
                    "description": "Every field is optional, including the name, so `{}` is a valid payload on both create endpoints: create answers 201 Stored, and findOrCreate — with no criteria to match on — answers 201 UnmatchedStored. Each call leaves a nameless person record behind.",
                    "x-transcript": "empty-bodies-create-blank-people",
                    "value": {
                      "vanId": 100000002,
                      "status": "UnmatchedStored"
                    }
                  },
                  "findorcreate-below-threshold-creates-a-duplicate": {
                    "summary": "Below the match threshold, findOrCreate quietly creates a duplicate",
                    "description": "A name alone never reaches the minimum match combination, so no match is attempted: the payload is stored as a brand-new person record even though the person is already in the database. There is no 'unmatched' to inspect — the no-match case is the create case.",
                    "x-transcript": "findorcreate-below-threshold-creates-a-duplicate",
                    "value": {
                      "vanId": 100000002,
                      "status": "UnmatchedStored"
                    }
                  }
                }
              }
            },
            "links": {
              "getCreatedPerson": {
                "operationId": "getPerson",
                "parameters": {
                  "vanId": "$response.body#/vanId"
                },
                "description": "Fetch the person record that was just created."
              }
            }
          },
          "302": {
            "description": "An existing person matched, so nothing was written.",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/MatchedPersonLocation"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PersonMatched"
                },
                "examples": {
                  "findorcreate-ignores-an-unknown-vanid": {
                    "summary": "findOrCreate drops a vanId that matches nothing",
                    "description": "Where create echoes a plausible unknown vanId back as a phantom match, findOrCreate just drops it: the ordinary match runs on the rest of the payload — here finding the existing person by name and email — and would have created a person had it found nothing. The vanId only matters when it names a real person.",
                    "x-transcript": "findorcreate-ignores-an-unknown-vanid",
                    "value": {
                      "vanId": 100000001,
                      "status": "Matched"
                    }
                  },
                  "findorcreate-returns-the-existing-match": {
                    "summary": "Above the match threshold, findOrCreate returns the existing person",
                    "description": "Name plus email clears the minimum match combination, so the existing person comes back as a 302 match stub with a Location header, and nothing is written.",
                    "x-transcript": "findorcreate-returns-the-existing-match",
                    "value": {
                      "vanId": 100000001,
                      "status": "Matched"
                    }
                  }
                }
              }
            },
            "links": {
              "getMatchedPerson": {
                "operationId": "getPerson",
                "parameters": {
                  "vanId": "$response.body#/vanId"
                },
                "description": "Fetch the matched person's full record."
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "An empty body creates a blank person record",
            "source": "# Every field is optional, including the name, so `{}` is a valid payload on\n# both create endpoints: create answers 201 Stored, and findOrCreate — with\n# no criteria to match on — answers 201 UnmatchedStored. Each call leaves a\n# nameless person record behind.\n\nCREATE_BODY='{}'\n\n# Create from nothing.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"$CREATE_BODY\"\n# → 201  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Stored\"\n# }\n\n# findOrCreate from nothing: no criteria means no match, which means create.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/findOrCreate' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"$CREATE_BODY\"\n# → 201  Location: https://api.securevan.com/v4/people/100000002\n# {\n#   \"vanId\": 100000002,\n#   \"status\": \"UnmatchedStored\"\n# }",
            "x-transcript": "empty-bodies-create-blank-people"
          },
          {
            "lang": "Shell",
            "label": "Below the match threshold, findOrCreate quietly creates a duplicate",
            "source": "# A name alone never reaches the minimum match combination, so no match is\n# attempted: the payload is stored as a brand-new person record even though\n# the person is already in the database. There is no 'unmatched' to inspect\n# — the no-match case is the create case.\n\n# The person is in the database, carrying identifiers a match could use.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Harriet\",\n    \"lastName\": \"Duplicata\",\n    \"emails\": [\n      {\n        \"email\": \"harriet.duplicata@example.com\"\n      }\n    ]\n  }'\n# → 201  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Stored\"\n# }\n\n# findOrCreate with the name alone. Below the threshold, so: created, not\n# found.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/findOrCreate' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Harriet\",\n    \"lastName\": \"Duplicata\"\n  }'\n# → 201  Location: https://api.securevan.com/v4/people/100000002\n# {\n#   \"vanId\": 100000002,\n#   \"status\": \"UnmatchedStored\"\n# }\n\n# Both person records now exist under the same name.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people?lastName=Duplicata' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 200\n# {\n#   \"items\": [\n#     {\n#       \"vanId\": 100000001,\n#       \"firstName\": \"Harriet\",\n#       \"lastName\": \"Duplicata\",\n#       \"middleName\": null,\n#       \"suffix\": null,\n#       \"title\": null,\n#       \"sourceFileTitle\": null,\n#       \"sourceFileFirstName\": null,\n#       \"sourceFileMiddleName\": null,\n#       \"sourceFileLastName\": null,\n#       \"sourceFileSuffix\": null,\n#       \"contactSource\": \"API\",\n#       \"contactMode\": \"Person\",\n#       \"organizationContactCommonName\": null,\n#       \"organizationContactOfficialName\": null,\n#       \"salutation\": null,\n#       \"formalSalutation\": null,\n#       \"additionalSalutation\": null,\n#       \"preferredPronoun\": null,\n#       \"pronouns\": null,\n#       \"namePronunciation\": null,\n#       \"envelopeName\": null,\n#       \"formalEnvelopeName\": null,\n#       \"additionalEnvelopeName\": null,\n#       \"contactMethodPreferenceCode\": null,\n#       \"contactMethodPreferenceId\": null,\n#       \"contactMethodPreferenceName\": null,\n#       \"assistantName\": null,\n#       \"nickname\": null,\n#       \"website\": null,\n#       \"professionalSuffix\": null,\n#       \"party\": null,\n#       \"employer\": null,\n#       \"occupation\": null,\n#       \"jobTitle\": null,\n#       \"sex\": null,\n#       \"dateOfBirth\": null,\n#       \"isDeceased\": false,\n#       \"dateCreated\": \"2026-01-01T00:00:00Z\",\n#       \"dateAcquired\": \"0001-01-01T00:00:00Z\",\n#       \"selfReportedRace\": null,\n#       \"selfReportedEthnicity\": null,\n#       \"selfReportedRaces\": null,\n#       \"selfReportedEthnicities\": null,\n#       \"selfReportedGenders\": null,\n#       \"selfReportedSexualOrientations\": null,\n#       \"selfReportedLanguagePreference\": null,\n#       \"selfReportedLanguagePreferences\": null,\n#       \"emails\": null,\n#       \"phones\": null,\n#       \"addresses\": null,\n#       \"recordedAddresses\": null,\n#       \"pollingLocation\": null,\n#       \"earlyVoteLocation\": null,\n#       \"identifiers\": null,\n#       \"codes\": null,\n#       \"customFields\": null,\n#       \"primaryCustomField\": null,\n#       \"contributionSummary\": null,\n#       \"suppressions\": null,\n#       \"caseworkCases\": null,\n#       \"caseworkIssues\": null,\n#       \"caseworkStories\": null,\n#       \"notes\": null,\n#       \"scores\": null,\n#       \"customProperties\": null,\n#       \"electionRecords\": null,\n#       \"membershipStatus\": null,\n#       \"organizationRoles\": null,\n#       \"districts\": null,\n#       \"surveyQuestionResponses\": null,\n#       \"finderNumber\": null,\n#       \"biographyImageUrl\": null,\n#       \"biographyText\": null,\n#       \"biographyHtml\": null,\n#       \"primaryContact\": null\n#     },\n#     {\n#       \"vanId\": 100000002,\n#       \"firstName\": \"Harriet\",\n#       \"lastName\": \"Duplicata\",\n#       \"middleName\": null,\n#       \"suffix\": null,\n#       \"title\": null,\n#       \"sourceFileTitle\": null,\n#       \"sourceFileFirstName\": null,\n#       \"sourceFileMiddleName\": null,\n#       \"sourceFileLastName\": null,\n#       \"sourceFileSuffix\": null,\n#       \"contactSource\": \"API\",\n#       \"contactMode\": \"Person\",\n#       \"organizationContactCommonName\": null,\n#       \"organizationContactOfficialName\": null,\n#       \"salutation\": null,\n#       \"formalSalutation\": null,\n#       \"additionalSalutation\": null,\n#       \"preferredPronoun\": null,\n#       \"pronouns\": null,\n#       \"namePronunciation\": null,\n#       \"envelopeName\": null,\n#       \"formalEnvelopeName\": null,\n#       \"additionalEnvelopeName\": null,\n#       \"contactMethodPreferenceCode\": null,\n#       \"contactMethodPreferenceId\": null,\n#       \"contactMethodPreferenceName\": null,\n#       \"assistantName\": null,\n#       \"nickname\": null,\n#       \"website\": null,\n#       \"professionalSuffix\": null,\n#       \"party\": null,\n#       \"employer\": null,\n#       \"occupation\": null,\n#       \"jobTitle\": null,\n#       \"sex\": null,\n#       \"dateOfBirth\": null,\n#       \"isDeceased\": false,\n#       \"dateCreated\": \"2026-01-01T00:00:00Z\",\n#       \"dateAcquired\": \"0001-01-01T00:00:00Z\",\n#       \"selfReportedRace\": null,\n#       \"selfReportedEthnicity\": null,\n#       \"selfReportedRaces\": null,\n#       \"selfReportedEthnicities\": null,\n#       \"selfReportedGenders\": null,\n#       \"selfReportedSexualOrientations\": null,\n#       \"selfReportedLanguagePreference\": null,\n#       \"selfReportedLanguagePreferences\": null,\n#       \"emails\": null,\n#       \"phones\": null,\n#       \"addresses\": null,\n#       \"recordedAddresses\": null,\n#       \"pollingLocation\": null,\n#       \"earlyVoteLocation\": null,\n#       \"identifiers\": null,\n#       \"codes\": null,\n#       \"customFields\": null,\n#       \"primaryCustomField\": null,\n#       \"contributionSummary\": null,\n#       \"suppressions\": null,\n#       \"caseworkCases\": null,\n#       \"caseworkIssues\": null,\n#       \"caseworkStories\": null,\n#       \"notes\": null,\n#       \"scores\": null,\n#       \"customProperties\": null,\n#       \"electionRecords\": null,\n#       \"membershipStatus\": null,\n#       \"organizationRoles\": null,\n#       \"districts\": null,\n#       \"surveyQuestionResponses\": null,\n#       \"finderNumber\": null,\n#       \"biographyImageUrl\": null,\n#       \"biographyText\": null,\n#       \"biographyHtml\": null,\n#       \"primaryContact\": null\n#     }\n#   ],\n#   \"nextPageLink\": null,\n#   \"count\": 2\n# }",
            "x-transcript": "findorcreate-below-threshold-creates-a-duplicate"
          },
          {
            "lang": "Shell",
            "label": "findOrCreate drops a vanId that matches nothing",
            "source": "# Where create echoes a plausible unknown vanId back as a phantom match,\n# findOrCreate just drops it: the ordinary match runs on the rest of the\n# payload — here finding the existing person by name and email — and would\n# have created a person had it found nothing. The vanId only matters when it\n# names a real person.\n\n# The person is in the database, under some other vanId.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Ignesia\",\n    \"lastName\": \"Vanidless\",\n    \"emails\": [\n      {\n        \"email\": \"ignesia.vanidless@example.com\"\n      }\n    ]\n  }'\n# → 201  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Stored\"\n# }\n\n# findOrCreate naming a vanId that exists nowhere, plus their real name and\n# email.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/findOrCreate' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"vanId\": 100777777,\n    \"firstName\": \"Ignesia\",\n    \"lastName\": \"Vanidless\",\n    \"emails\": [\n      {\n        \"email\": \"ignesia.vanidless@example.com\"\n      }\n    ]\n  }'\n# → 302  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Matched\"\n# }",
            "x-transcript": "findorcreate-ignores-an-unknown-vanid"
          },
          {
            "lang": "Shell",
            "label": "Above the match threshold, findOrCreate returns the existing person",
            "source": "# Name plus email clears the minimum match combination, so the existing\n# person comes back as a 302 match stub with a Location header, and nothing\n# is written.\n\nCREATE_BODY='{\n  \"firstName\": \"Marisol\",\n  \"lastName\": \"Vega\",\n  \"emails\": [\n    {\n      \"email\": \"marisol.vega@example.com\"\n    }\n  ]\n}'\n\n# The person is already in the database.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"$CREATE_BODY\"\n# → 201  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Stored\"\n# }\n\n# findOrCreate with the same name and email: found, not created.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/findOrCreate' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"$CREATE_BODY\"\n# → 302  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Matched\"\n# }",
            "x-transcript": "findorcreate-returns-the-existing-match"
          }
        ]
      }
    },
    "/people/create": {
      "post": {
        "operationId": "createPerson",
        "summary": "Create a person without matching",
        "description": "Stores the payload as a new person record. **No de-duplication happens**: posting a name and email identical to an existing person's creates a second person record. Use POST /people/findOrCreate when you want matching — bearing in mind that it too creates a second person record unless your payload reaches the minimum match combination documented there (name alone never does).\n\nOutcomes:\n\n- **The body supplies a `vanId` that exists** — nothing is created and that person is returned as **302 Found**, exactly as findOrCreate would answer.\n- **The body supplies a plausible `vanId` that matches nothing** — still **302 Found**, echoing the id straight back. The id is never checked against the database: anything from 100000000 (where this database's ids start) up through the newest id ever assigned answers `{\"vanId\": <as sent>, \"status\": \"Matched\"}`, with a `Location` that then answers 404. Nothing is created. This case has also been seen to answer **404** directly instead — rarely; see that response below.\n- **The body supplies an implausible `vanId`** (below 100000000, negative, or beyond the newest assigned id) — the id is ignored, but the request is not refused: the rest of the payload **is stored as a new person record**, and the answer is still **302 Found** with `\"status\": \"Matched\"` and a `Location` pointing at the person just created — not a 201. The status code cannot tell you whether a create happened; a `vanId` in the response you never sent can.\n- **The body supplies `\"vanId\": 0`** — the id is ignored entirely and the ordinary create runs: **201 Created**, as if the field were absent.\n- **Anything else** — **201 Created** with `{\"vanId\": …, \"status\": \"Stored\"}`. A payload identical to an existing person is not a special case: it creates a duplicate.\n- **The body is empty (`{}`)** — every field is optional, so this too returns **201**, creating a blank person record with no name.",
        "x-provenance": {
          "lastProbed": "2026-08-03",
          "note": "Not in the official docs' page index; the path comes from van-cli (people.ts create), which requires firstName and lastName client-side. The API requires neither. Duplicate behaviour confirmed by posting an exact copy of an existing person's name and email and receiving a new vanId (observed 2026-08-03)."
        },
        "tags": [
          "People"
        ],
        "x-keywords": [
          "create",
          "add person",
          "insert",
          "new record",
          "new contact",
          "import one person",
          "unconditional create"
        ],
        "x-task": "Create unconditionally, duplicates and all",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PersonInput"
              },
              "examples": {
                "minimal": {
                  "summary": "Name only",
                  "value": {
                    "firstName": "Cre",
                    "lastName": "Atetest"
                  }
                },
                "withDetails": {
                  "summary": "Name plus demographics and contact details",
                  "value": {
                    "firstName": "Cre",
                    "lastName": "Atetest",
                    "sex": "F",
                    "dateOfBirth": "1975-04-12",
                    "party": "D",
                    "contactMethodPreferenceCode": "E",
                    "employer": "Ship Creek Group",
                    "occupation": "Engineer",
                    "emails": [
                      {
                        "email": "cre@example.com",
                        "type": "W",
                        "subscriptionStatus": "S"
                      }
                    ]
                  }
                },
                "create-echoes-a-plausible-vanid-blindly": {
                  "summary": "A plausible vanId is echoed back as matched, existent or not",
                  "description": "The vanId in the body is never checked against the database: any id in the range this database has ever assigned answers 302 Matched with the id echoed straight back, even when it names no one — the Location it points at answers 404. Nothing is created.",
                  "x-transcript": "create-echoes-a-plausible-vanid-blindly",
                  "value": {
                    "vanId": 100777777,
                    "firstName": "Phantom"
                  }
                },
                "create-never-deduplicates/1": {
                  "summary": "Create a person.",
                  "description": "No de-duplication happens: posting a payload identical to an existing person's — same name, same email — returns 201 with a fresh vanId, and both person records now exist.",
                  "x-transcript": "create-never-deduplicates",
                  "value": {
                    "firstName": "Beatrix",
                    "lastName": "Falkner",
                    "emails": [
                      {
                        "email": "beatrix.falkner@example.com"
                      }
                    ]
                  }
                },
                "create-never-deduplicates/2": {
                  "summary": "Create them again, byte for byte. Nothing objects: a duplicate is born.",
                  "description": "No de-duplication happens: posting a payload identical to an existing person's — same name, same email — returns 201 with a fresh vanId, and both person records now exist.",
                  "x-transcript": "create-never-deduplicates",
                  "value": {
                    "firstName": "Beatrix",
                    "lastName": "Falkner",
                    "emails": [
                      {
                        "email": "beatrix.falkner@example.com"
                      }
                    ]
                  }
                },
                "create-with-a-vanid-matches-instead": {
                  "summary": "A vanId that exists matches instead of creating",
                  "description": "When the body carries a vanId that exists, nothing is created: the answer is the same 302 match stub findOrCreate gives, with a Location pointing at the existing person.",
                  "x-transcript": "create-with-a-vanid-matches-instead",
                  "value": {
                    "vanId": 100000001,
                    "firstName": "Soren"
                  }
                },
                "create-with-an-implausible-vanid-creates-anyway": {
                  "summary": "An implausible vanId hides a create behind the 302",
                  "description": "A vanId outside the range the database has ever assigned is ignored — but the request is not refused: the rest of the payload is stored as a new person record, and the answer is still the 302 Matched stub, pointing at the person just created. Only the unfamiliar vanId in the response betrays that something was written.",
                  "x-transcript": "create-with-an-implausible-vanid-creates-anyway",
                  "value": {
                    "vanId": 2147483646,
                    "firstName": "Implausia",
                    "lastName": "Storedanyway"
                  }
                },
                "empty-bodies-create-blank-people": {
                  "summary": "An empty body creates a blank person record",
                  "description": "Every field is optional, including the name, so `{}` is a valid payload on both create endpoints: create answers 201 Stored, and findOrCreate — with no criteria to match on — answers 201 UnmatchedStored. Each call leaves a nameless person record behind.",
                  "x-transcript": "empty-bodies-create-blank-people",
                  "value": {}
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Never sent by this endpoint. This is where a redirect-following client *lands* when the body carried a `vanId` that already exists:\n\n```\nPOST /people/create            {\"vanId\": 102714558, …}\n  ← 302 Found\n    Location: https://api.securevan.com/v4/people/102714558\n    {\"vanId\": 102714558, \"status\": \"Matched\"}\n\nGET /people/102714558          ← client re-issues the request at Location\n  ← 200 OK\n    { full person record — the body documented here }\n```\n\nSo on the vanId path your code sees this 200 and a full `Person` — and, critically, a response that looks nothing like the 201 you get when a person record really was created. Check `resp.history` / `resp.redirected`, or just don't send a `vanId` to a create endpoint. And when the echoed `vanId` names no person — see the outcomes above — the redirect-following client lands on a **404** here instead of this 200. See POST /people/find for the full redirect-following notes, including the `curl -X POST -L` gotcha.",
            "x-provenance": {
              "lastProbed": "2026-08-04",
              "note": "Chain observed end to end with httpx (302 → GET → 200 Person) by posting an existing vanId; identical to the POST /people/findOrCreate and POST /people/find redirects."
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Person"
                },
                "examples": {
                  "existingVanIdFollowed": {
                    "summary": "What a redirect-following client receives when the posted vanId already exists (abridged: null-only fields omitted)",
                    "value": {
                      "vanId": 102714558,
                      "firstName": "Dup",
                      "lastName": "Testperson",
                      "contactSource": "API",
                      "contactMode": "Person",
                      "salutation": "Dup",
                      "formalSalutation": "Dup Testperson",
                      "envelopeName": "Dup Testperson",
                      "formalEnvelopeName": "Dup Testperson",
                      "isDeceased": false,
                      "dateCreated": "2026-08-03T16:31:00Z",
                      "dateAcquired": "0001-01-01T00:00:00Z"
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "A new person record was created. No `Location` header is sent — the new id is in the body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PersonStored"
                },
                "examples": {
                  "created": {
                    "summary": "New person record stored",
                    "value": {
                      "vanId": 102714580,
                      "status": "Stored"
                    }
                  },
                  "create-never-deduplicates/1": {
                    "summary": "Create a person.",
                    "description": "No de-duplication happens: posting a payload identical to an existing person's — same name, same email — returns 201 with a fresh vanId, and both person records now exist.",
                    "x-transcript": "create-never-deduplicates",
                    "value": {
                      "vanId": 100000001,
                      "status": "Stored"
                    }
                  },
                  "create-never-deduplicates/2": {
                    "summary": "Create them again, byte for byte. Nothing objects: a duplicate is born.",
                    "description": "No de-duplication happens: posting a payload identical to an existing person's — same name, same email — returns 201 with a fresh vanId, and both person records now exist.",
                    "x-transcript": "create-never-deduplicates",
                    "value": {
                      "vanId": 100000002,
                      "status": "Stored"
                    }
                  },
                  "empty-bodies-create-blank-people": {
                    "summary": "An empty body creates a blank person record",
                    "description": "Every field is optional, including the name, so `{}` is a valid payload on both create endpoints: create answers 201 Stored, and findOrCreate — with no criteria to match on — answers 201 UnmatchedStored. Each call leaves a nameless person record behind.",
                    "x-transcript": "empty-bodies-create-blank-people",
                    "value": {
                      "vanId": 100000001,
                      "status": "Stored"
                    }
                  }
                }
              }
            },
            "links": {
              "getCreatedPerson": {
                "operationId": "getPerson",
                "parameters": {
                  "vanId": "$response.body#/vanId"
                },
                "description": "Fetch the person record that was just created."
              }
            }
          },
          "302": {
            "description": "The body carried a `vanId`, and nothing else in the payload was considered. Sent whether or not that id exists — a plausible id is a genuine match or a blind echo whose `Location` answers 404, and an implausible one quietly hides a create, with the new person's id (not the one sent) in the body. See the outcomes above.",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/MatchedPersonLocation"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PersonMatched"
                },
                "examples": {
                  "create-echoes-a-plausible-vanid-blindly": {
                    "summary": "A plausible vanId is echoed back as matched, existent or not",
                    "description": "The vanId in the body is never checked against the database: any id in the range this database has ever assigned answers 302 Matched with the id echoed straight back, even when it names no one — the Location it points at answers 404. Nothing is created.",
                    "x-transcript": "create-echoes-a-plausible-vanid-blindly",
                    "value": {
                      "vanId": 100777777,
                      "status": "Matched"
                    }
                  },
                  "create-with-a-vanid-matches-instead": {
                    "summary": "A vanId that exists matches instead of creating",
                    "description": "When the body carries a vanId that exists, nothing is created: the answer is the same 302 match stub findOrCreate gives, with a Location pointing at the existing person.",
                    "x-transcript": "create-with-a-vanid-matches-instead",
                    "value": {
                      "vanId": 100000001,
                      "status": "Matched"
                    }
                  },
                  "create-with-an-implausible-vanid-creates-anyway": {
                    "summary": "An implausible vanId hides a create behind the 302",
                    "description": "A vanId outside the range the database has ever assigned is ignored — but the request is not refused: the rest of the payload is stored as a new person record, and the answer is still the 302 Matched stub, pointing at the person just created. Only the unfamiliar vanId in the response betrays that something was written.",
                    "x-transcript": "create-with-an-implausible-vanid-creates-anyway",
                    "value": {
                      "vanId": 100000001,
                      "status": "Matched"
                    }
                  }
                }
              }
            },
            "links": {
              "getMatchedPerson": {
                "operationId": "getPerson",
                "parameters": {
                  "vanId": "$response.body#/vanId"
                },
                "description": "Fetch the existing person's full record."
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "A body `vanId` that matches no person has been seen to answer this way — the standard error envelope, nothing created — in place of the blind 302 echo the identical request normally gets. Rare and not reproducible on demand; code that sends a `vanId` here should treat a 404 as possible.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "notFound": {
                    "summary": "Unknown body vanId, refused instead of echoed",
                    "value": {
                      "errors": [
                        {
                          "code": "NOT_FOUND",
                          "text": "The specified resource cannot be found."
                        }
                      ]
                    }
                  }
                }
              }
            },
            "x-provenance": {
              "lastProbed": "2026-08-08",
              "note": "Observed only in CI (schemathesis, run 31282824344, 2026-08-08 22:56-23:02 UTC), where {\"vanId\": 100000001, \"firstName\": \"Soren\"} answered 404 in both the Examples and Coverage phases. Fifteen minutes later the identical request — with and without a session cookie — answered 302 in every attempt, as did every other unknown in-range id probed (100000000-102500000 at several points, and the boundary cases). The sandbox had served a bare 502 half an hour earlier, so this may be an infrastructure mode rather than API logic; documented so a recurrence does not fail conformance."
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "A plausible vanId is echoed back as matched, existent or not",
            "source": "# The vanId in the body is never checked against the database: any id in the\n# range this database has ever assigned answers 302 Matched with the id\n# echoed straight back, even when it names no one — the Location it points\n# at answers 404. Nothing is created.\n\n# An id in the assigned range that names no person.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people/100777777' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 404\n# {\n#   \"errors\": [\n#     {\n#       \"code\": \"NOT_FOUND\",\n#       \"text\": \"The specified resource cannot be found.\"\n#     }\n#   ]\n# }\n\n# Create with that id: matched, apparently.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"vanId\": 100777777,\n    \"firstName\": \"Phantom\"\n  }'\n# → 302  Location: https://api.securevan.com/v4/people/100777777\n# {\n#   \"vanId\": 100777777,\n#   \"status\": \"Matched\"\n# }\n\n# But the person the Location points at still does not exist.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people/100777777' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 404\n# {\n#   \"errors\": [\n#     {\n#       \"code\": \"NOT_FOUND\",\n#       \"text\": \"The specified resource cannot be found.\"\n#     }\n#   ]\n# }",
            "x-transcript": "create-echoes-a-plausible-vanid-blindly"
          },
          {
            "lang": "Shell",
            "label": "An identical payload creates a second person record",
            "source": "# No de-duplication happens: posting a payload identical to an existing\n# person's — same name, same email — returns 201 with a fresh vanId, and\n# both person records now exist.\n\nCREATE_BODY='{\n  \"firstName\": \"Beatrix\",\n  \"lastName\": \"Falkner\",\n  \"emails\": [\n    {\n      \"email\": \"beatrix.falkner@example.com\"\n    }\n  ]\n}'\n\n# Create a person.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"$CREATE_BODY\"\n# → 201  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Stored\"\n# }\n\n# Create them again, byte for byte. Nothing objects: a duplicate is born.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"$CREATE_BODY\"\n# → 201  Location: https://api.securevan.com/v4/people/100000002\n# {\n#   \"vanId\": 100000002,\n#   \"status\": \"Stored\"\n# }",
            "x-transcript": "create-never-deduplicates"
          },
          {
            "lang": "Shell",
            "label": "A vanId that exists matches instead of creating",
            "source": "# When the body carries a vanId that exists, nothing is created: the answer\n# is the same 302 match stub findOrCreate gives, with a Location pointing at\n# the existing person.\n\n# An existing person to name in the body.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Soren\",\n    \"lastName\": \"Lindqvist\"\n  }'\n# → 201  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Stored\"\n# }\n\n# A create request that names them. No record is created.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"vanId\": 100000001,\n    \"firstName\": \"Soren\"\n  }'\n# → 302  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Matched\"\n# }",
            "x-transcript": "create-with-a-vanid-matches-instead"
          },
          {
            "lang": "Shell",
            "label": "An implausible vanId hides a create behind the 302",
            "source": "# A vanId outside the range the database has ever assigned is ignored — but\n# the request is not refused: the rest of the payload is stored as a new\n# person record, and the answer is still the 302 Matched stub, pointing at\n# the person just created. Only the unfamiliar vanId in the response betrays\n# that something was written.\n\n# An id no record has ever had, far beyond the assigned range.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"vanId\": 2147483646,\n    \"firstName\": \"Implausia\",\n    \"lastName\": \"Storedanyway\"\n  }'\n# → 302  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Matched\"\n# }\n\n# The 'match' is a person that did not exist a moment ago.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people/100000001' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 200\n# {\n#   \"vanId\": 100000001,\n#   \"firstName\": \"Implausia\",\n#   \"lastName\": \"Storedanyway\",\n#   \"middleName\": null,\n#   \"suffix\": null,\n#   \"title\": null,\n#   \"sourceFileTitle\": null,\n#   \"sourceFileFirstName\": null,\n#   \"sourceFileMiddleName\": null,\n#   \"sourceFileLastName\": null,\n#   \"sourceFileSuffix\": null,\n#   \"contactSource\": \"API\",\n#   \"contactMode\": \"Person\",\n#   \"organizationContactCommonName\": null,\n#   \"organizationContactOfficialName\": null,\n#   \"salutation\": \"Implausia\",\n#   \"formalSalutation\": \"Implausia Storedanyway\",\n#   \"additionalSalutation\": null,\n#   \"preferredPronoun\": null,\n#   \"pronouns\": null,\n#   \"namePronunciation\": null,\n#   \"envelopeName\": \"Implausia Storedanyway\",\n#   \"formalEnvelopeName\": \"Implausia Storedanyway\",\n#   \"additionalEnvelopeName\": null,\n#   \"contactMethodPreferenceCode\": null,\n#   \"contactMethodPreferenceId\": null,\n#   \"contactMethodPreferenceName\": null,\n#   \"assistantName\": null,\n#   \"nickname\": null,\n#   \"website\": null,\n#   \"professionalSuffix\": null,\n#   \"party\": null,\n#   \"employer\": null,\n#   \"occupation\": null,\n#   \"jobTitle\": null,\n#   \"sex\": null,\n#   \"dateOfBirth\": null,\n#   \"isDeceased\": false,\n#   \"dateCreated\": \"2026-01-01T00:00:00Z\",\n#   \"dateAcquired\": \"0001-01-01T00:00:00Z\",\n#   \"selfReportedRace\": null,\n#   \"selfReportedEthnicity\": null,\n#   \"selfReportedRaces\": null,\n#   \"selfReportedEthnicities\": null,\n#   \"selfReportedGenders\": null,\n#   \"selfReportedSexualOrientations\": null,\n#   \"selfReportedLanguagePreference\": null,\n#   \"selfReportedLanguagePreferences\": null,\n#   \"emails\": null,\n#   \"phones\": null,\n#   \"addresses\": null,\n#   \"recordedAddresses\": null,\n#   \"pollingLocation\": null,\n#   \"earlyVoteLocation\": null,\n#   \"identifiers\": null,\n#   \"codes\": null,\n#   \"customFields\": null,\n#   \"primaryCustomField\": null,\n#   \"contributionSummary\": null,\n#   \"suppressions\": null,\n#   \"caseworkCases\": null,\n#   \"caseworkIssues\": null,\n#   \"caseworkStories\": null,\n#   \"notes\": null,\n#   \"scores\": null,\n#   \"customProperties\": null,\n#   \"electionRecords\": null,\n#   \"membershipStatus\": null,\n#   \"organizationRoles\": null,\n#   \"districts\": null,\n#   \"surveyQuestionResponses\": null,\n#   \"finderNumber\": null,\n#   \"biographyImageUrl\": null,\n#   \"biographyText\": null,\n#   \"biographyHtml\": null,\n#   \"primaryContact\": null\n# }",
            "x-transcript": "create-with-an-implausible-vanid-creates-anyway"
          },
          {
            "lang": "Shell",
            "label": "An empty body creates a blank person record",
            "source": "# Every field is optional, including the name, so `{}` is a valid payload on\n# both create endpoints: create answers 201 Stored, and findOrCreate — with\n# no criteria to match on — answers 201 UnmatchedStored. Each call leaves a\n# nameless person record behind.\n\nCREATE_BODY='{}'\n\n# Create from nothing.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"$CREATE_BODY\"\n# → 201  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Stored\"\n# }\n\n# findOrCreate from nothing: no criteria means no match, which means create.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/findOrCreate' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"$CREATE_BODY\"\n# → 201  Location: https://api.securevan.com/v4/people/100000002\n# {\n#   \"vanId\": 100000002,\n#   \"status\": \"UnmatchedStored\"\n# }",
            "x-transcript": "empty-bodies-create-blank-people"
          }
        ]
      }
    },
    "/people/{vanId}/mergeInto": {
      "put": {
        "operationId": "mergePerson",
        "summary": "Merge one person into another",
        "description": "Merges the **secondary** person named in the path into the **primary** person named in the body. The secondary is deleted; the primary survives and keeps its own vanId.\n\n> **Merges are permanent and cannot be undone.** There is no API to reverse one. Afterwards `GET /people/{secondaryVanId}` answers 404 and the id can never be used again. Send `?whatIf=true` first to find out whether a pair is mergeable — but read the warning on that parameter, because only the literal value `true` simulates.\n\n**What happens to the data**, observed on pairs built with conflicting values on both sides:\n\n- Scalar fields the two people disagree on keep the **primary's** value (`firstName`, `sex`, `dateOfBirth`…) — the same defaults the Contacts Merge Wizard applies in the UI.\n- Scalar fields the primary left empty are **filled in from the secondary** (`middleName`, `party`, `employer`, `occupation`…), so the primary can come out of a merge holding more data than it went in with.\n- `emails`, `phones` and `addresses` are all **combined**, and exact duplicates are collapsed rather than doubled:\n  - **Emails** dedupe case-insensitively and regardless of `type`. The primary's copy is the one kept, so its `type` is what survives.\n  - **Phones** dedupe on the normalized number — formatting and a leading `1` are ignored — but only within the same `phoneType`. The same number held once as `Personal` and once as `Work` stays as two entries.\n  - **Addresses** are combined too, but you will usually not be able to see it. `$expand=addresses` only ever surfaces the best Voting and the best Mailing address, and the primary's own address takes both slots whenever it has one, so a merged-in address is masked rather than missing — `POST /people/find` still matches it. Whether identical addresses are deduped cannot be determined through the API.\n- **Notes move to the primary**, keeping their `noteId`.\n- The primary inherits the secondary's reachability: `POST /people/find` with an email, phone or address that belonged only to the secondary now resolves to the primary's vanId.\n\n**The preferred email follows the ordinary rule, not a merge-specific one.** The two sets of addresses are pooled and the newest address in the combined set carries the flag — so the primary loses its preferred address whenever the secondary brings in a more recently added one. The exception is an address pinned by an explicit `isPreferred: true` write, which keeps the flag even against a newer incoming address. Phones are unaffected: they only ever take the flag from an explicit write, and where both people had one the primary's survived. Phone ordering after a merge is not stable enough to rely on.\n\nTo keep a secondary value the primary overwrote, read both people before merging and write the value back with `POST /people/{vanId}` afterwards.\n\n**Merged-away ids are remembered, but only here.** A vanId that has been merged away is refused on either side of any later merge with `One or more of these contacts has already been merged.` — a different message from the one an id that never existed gets. `GET /people/{vanId}` does not expose that distinction: both simply answer 404. So this endpoint, called with `?whatIf=true`, is the only way to tell a merged-away vanId from one that never existed.\n\nOutcomes:\n\n- **Both ids exist, share a `contactMode`, and neither has been merged before** — **200** with the primary's vanId and a `Location` header pointing at it.\n- **Anything else** — **400** with the reason in `text`. Unknown ids are a **400**, not a 404; this endpoint never returns a JSON 404.\n- **A secondary equal to the primary** — **500**.",
        "x-provenance": {
          "source": "docs + sandbox probe",
          "lastProbed": "2026-08-05",
          "note": "Not in van-cli (no merge command exists there); path and body from the official docs, all behavior from live probing. Scalar semantics observed by merging 102720707 into 102720708, two purpose-built people with deliberately conflicting values: the primary's firstName/sex/dateOfBirth won, its empty middleName/party/employer/occupation were filled from the secondary, and the note moved with its noteId. Merged-away ids were confirmed permanently unusable on both sides against a freshly created person.\n\nContact-method semantics re-probed 2026-08-06 across 17 purpose-built pairs. Dedup: an email shared by both people came back once — also when the two differed only in case, and when they carried different `type` values, where the primary's type survived; a phone shared as `(907) 555-2001` and `9075552001`, and as `19075552011` and `907-555-2011`, came back once keeping the primary's phoneId; the same number under two different phoneTypes came back twice.\n\nThe preferred-email behaviour was probed with the two people created 65 seconds apart, so their addresses carry different dateCreated values: with the secondary's address newer the flag moved to it, with the primary's newer the flag stayed, and with the primary's address explicitly pinned the flag stayed even though the secondary's was newer. Nothing merge-specific is happening — it is the ordinary rule that a newly arrived address takes the flag unless one is pinned.\n\nAn earlier pass over the same question (also 2026-08-06) built every pair inside a single minute, and since dateCreated has only minute resolution the addresses tied and the flag appeared to obey a positional 'second entry wins' rule across a dozen pairs. That reading was wrong and has been removed; space the writes out when re-probing anything that depends on address ordering.\n\nCorrection: an earlier probe (2026-08-05) concluded the secondary's address was discarded. That was an instrument error — it used GET /people?streetAddress=, which indexes only the Voting address. Re-tested 2026-08-06 with POST /people/find, which matches every address type: merging into a primary that had no address of its own surfaced the secondary's address on the primary, keeping its addressId, and where the primary did have one, find still matched the secondary's address on the merged person even though $expand=addresses showed only the primary's. Addresses are combined, as the docs say; the readback is what hides them."
        },
        "x-docs-discrepancy": "Official docs say emails, phones and addresses are all combined into the primary, which holds — though a merged-in address is normally invisible afterwards, since $expand=addresses surfaces only the best Voting and Mailing address and the primary's own takes both slots (POST /people/find still matches it). The docs are silent on four further behaviours: duplicate emails and phones are collapsed rather than doubled, the primary can lose its preferred email address to a more recently added one coming from the secondary, notes move to the primary, and unknown vanIds are answered 400 rather than 404 (observed 2026-08-06).",
        "tags": [
          "People"
        ],
        "x-keywords": [
          "merge",
          "dedupe",
          "deduplicate",
          "combine records",
          "consolidate duplicates",
          "delete a duplicate",
          "whatIf",
          "dry run"
        ],
        "x-task": "Collapse two records into one",
        "parameters": [
          {
            "name": "vanId",
            "in": "path",
            "required": true,
            "description": "VAN id of the **secondary** person record — the one that is deleted by the merge.\n\nZero is rejected with 400. Negative values return 500, so this schema requires a positive id.",
            "schema": {
              "type": "integer",
              "format": "int32",
              "minimum": 1
            },
            "example": 102720707,
            "x-docs-discrepancy": "Official docs place no constraint on this parameter; a negative id returns 500 rather than a validation error, and a non-integer segment matches no route and returns an IIS HTML 404 page (observed 2026-08-05)."
          },
          {
            "name": "whatIf",
            "in": "query",
            "required": false,
            "description": "Simulate the merge rather than performing it. The mergeability checks run and the response is the same, but nothing is written.\n\n**Only the exact string `true`, case-insensitive, simulates.** Every other non-empty value — including `1` and `yes` — is read as `false` and **performs the merge for real**. The response to a simulation is byte-identical to the response to a completed merge (same 200, same body, same `Location`), so nothing in it reveals which one happened. An empty value (`?whatIf=`) is rejected with 400, and omitting the parameter performs the merge.\n\nBecause a typo here silently destroys a person record, send the literal `true` or leave the parameter off — never a computed truthy value.",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "example": true,
            "x-docs-discrepancy": "Official docs type this as a plain boolean and say \"if true, simulates the merge request without actually executing the merge\", implying any truthy value is safe. Only case-insensitive `true` simulates: `whatIf=1`, `whatIf=yes` and `whatIf=xyz` each performed a real, irreversible merge, and `whatIf=` returned 400 (each value confirmed on its own freshly created pair, 2026-08-05)."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PersonMergeInput"
              },
              "examples": {
                "merge-combines-emails-and-moves-reachability": {
                  "summary": "Emails are combined onto the primary, and shared ones are not doubled",
                  "description": "The two people's emails are pooled onto the primary. An address both held is collapsed to one entry — matched case-insensitively, keeping the primary's copy — and an email that belonged only to the secondary now resolves to the primary through POST /people/find.",
                  "x-transcript": "merge-combines-emails-and-moves-reachability",
                  "value": {
                    "vanId": 100000001
                  }
                },
                "merge-deletes-secondary-and-answers-with-primary": {
                  "summary": "A merge keeps the primary, deletes the secondary, and answers with the survivor",
                  "description": "The secondary named in the path is merged into the primary named in the body. The 200 carries the primary's vanId — the survivor, not the id from the path — with a Location pointing at it, and the secondary answers 404 from then on.",
                  "x-transcript": "merge-deletes-secondary-and-answers-with-primary",
                  "value": {
                    "vanId": 100000001
                  }
                },
                "merge-empty-whatif-is-rejected": {
                  "summary": "An empty whatIf is rejected outright",
                  "description": "`?whatIf=` is the one value that neither simulates nor merges: it is refused with a bare BAD_REQUEST. Every other non-empty value performs the merge, so the empty string is the only typo here that is safe.",
                  "x-transcript": "merge-empty-whatif-is-rejected",
                  "value": {
                    "vanId": 100000001
                  }
                },
                "merge-keeps-primary-values-and-fills-its-gaps": {
                  "summary": "Conflicting fields keep the primary's value; the primary's gaps fill from the secondary",
                  "description": "Scalar fields the two people disagree on keep the primary's value, and fields the primary left empty are filled in from the secondary — so the primary can come out of a merge holding more data than it went in with.",
                  "x-transcript": "merge-keeps-primary-values-and-fills-its-gaps",
                  "value": {
                    "vanId": 100000001
                  }
                },
                "merge-refuses-mismatched-contact-modes": {
                  "summary": "A person and an organization cannot be merged",
                  "description": "Both records must be the same kind of contact. The refusal names both vanIds and tells the caller to change the contactMode in the UI first, so it is the only 400 here that identifies which records were at fault.",
                  "x-transcript": "merge-refuses-mismatched-contact-modes",
                  "value": {
                    "vanId": 100000001
                  }
                },
                "merge-refuses-unusable-bodies/1": {
                  "summary": "A JSON object that parses fine but names no counterpart.",
                  "description": "A well-formed object that simply has no vanId is refused differently from a body that is not an object at all, so the message distinguishes 'you forgot the id' from 'I could not read this'.",
                  "x-transcript": "merge-refuses-unusable-bodies",
                  "value": {}
                },
                "merge-refuses-unusable-bodies/2": {
                  "summary": "A body that is valid JSON but not an object at all.",
                  "description": "A well-formed object that simply has no vanId is refused differently from a body that is not an object at all, so the message distinguishes 'you forgot the id' from 'I could not read this'.",
                  "x-transcript": "merge-refuses-unusable-bodies",
                  "value": "nope"
                },
                "merge-remembers-merged-away-ids/1": {
                  "summary": "Reuse that merged-away id in a fresh merge. It is remembered, permanently.",
                  "description": "A vanId that has been merged away is refused on either side of any later merge with a different message from the one an id that never existed gets. Since GET /people/{vanId} answers 404 for both, this endpoint is the only way to tell them apart.",
                  "x-transcript": "merge-remembers-merged-away-ids",
                  "value": {
                    "vanId": 100000003
                  }
                },
                "merge-remembers-merged-away-ids/2": {
                  "summary": "An id that never existed is refused too, but with different text. That difference is the only way to tell the two apart — GET /people/{vanId} answers 404 for both.",
                  "description": "A vanId that has been merged away is refused on either side of any later merge with a different message from the one an id that never existed gets. Since GET /people/{vanId} answers 404 for both, this endpoint is the only way to tell them apart.",
                  "x-transcript": "merge-remembers-merged-away-ids",
                  "value": {
                    "vanId": 100000003
                  }
                },
                "merge-whatif-requires-literal-true": {
                  "summary": "whatIf only simulates for the literal string 'true'",
                  "description": "Only the exact value `true` simulates. Every other non-empty value — including `1` and `yes` — is read as false and performs the merge for real, and the response is identical either way, so nothing in it reveals which one happened.",
                  "x-transcript": "merge-whatif-requires-literal-true",
                  "value": {
                    "vanId": 100000001
                  }
                },
                "merge-whatif-true-simulates-without-writing": {
                  "summary": "whatIf=true returns the completed-merge response without merging",
                  "description": "A simulation answers exactly as a real merge does — same 200, same body, same Location pointing at the primary — while both records survive. The response is therefore no evidence that a merge happened.",
                  "x-transcript": "merge-whatif-true-simulates-without-writing",
                  "value": {
                    "vanId": 100000001
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The two people are mergeable. The body carries the **primary's** vanId — the person that survived — not the secondary's.\n\nThis is also the response to `?whatIf=true`, where nothing was written. The two are indistinguishable: same status, same body, same `Location`. Whether the merge actually happened depends entirely on the request you sent.",
            "headers": {
              "Location": {
                "description": "Absolute URL of the surviving primary person.",
                "schema": {
                  "type": "string",
                  "format": "uri"
                },
                "example": "https://api.securevan.com/v4/people/102720708"
              }
            },
            "x-docs-discrepancy": "Official docs document only the JSON body; the response also carries a Location header pointing at the surviving primary (observed 2026-08-05).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PersonMergeResult"
                },
                "examples": {
                  "merge-combines-emails-and-moves-reachability": {
                    "summary": "Emails are combined onto the primary, and shared ones are not doubled",
                    "description": "The two people's emails are pooled onto the primary. An address both held is collapsed to one entry — matched case-insensitively, keeping the primary's copy — and an email that belonged only to the secondary now resolves to the primary through POST /people/find.",
                    "x-transcript": "merge-combines-emails-and-moves-reachability",
                    "value": {
                      "vanId": 100000001
                    }
                  },
                  "merge-deletes-secondary-and-answers-with-primary": {
                    "summary": "A merge keeps the primary, deletes the secondary, and answers with the survivor",
                    "description": "The secondary named in the path is merged into the primary named in the body. The 200 carries the primary's vanId — the survivor, not the id from the path — with a Location pointing at it, and the secondary answers 404 from then on.",
                    "x-transcript": "merge-deletes-secondary-and-answers-with-primary",
                    "value": {
                      "vanId": 100000001
                    }
                  },
                  "merge-keeps-primary-values-and-fills-its-gaps": {
                    "summary": "Conflicting fields keep the primary's value; the primary's gaps fill from the secondary",
                    "description": "Scalar fields the two people disagree on keep the primary's value, and fields the primary left empty are filled in from the secondary — so the primary can come out of a merge holding more data than it went in with.",
                    "x-transcript": "merge-keeps-primary-values-and-fills-its-gaps",
                    "value": {
                      "vanId": 100000001
                    }
                  },
                  "merge-whatif-requires-literal-true": {
                    "summary": "whatIf only simulates for the literal string 'true'",
                    "description": "Only the exact value `true` simulates. Every other non-empty value — including `1` and `yes` — is read as false and performs the merge for real, and the response is identical either way, so nothing in it reveals which one happened.",
                    "x-transcript": "merge-whatif-requires-literal-true",
                    "value": {
                      "vanId": 100000001
                    }
                  },
                  "merge-whatif-true-simulates-without-writing": {
                    "summary": "whatIf=true returns the completed-merge response without merging",
                    "description": "A simulation answers exactly as a real merge does — same 200, same body, same Location pointing at the primary — while both records survive. The response is therefore no evidence that a merge happened.",
                    "x-transcript": "merge-whatif-true-simulates-without-writing",
                    "value": {
                      "vanId": 100000001
                    }
                  }
                }
              }
            },
            "links": {
              "getMergedPerson": {
                "operationId": "getPerson",
                "parameters": {
                  "vanId": "$response.body#/vanId"
                },
                "description": "Fetch the surviving primary to see the merged result — the merge response carries only its id."
              }
            }
          },
          "302": {
            "$ref": "#/components/responses/RequestValidationRedirect"
          },
          "400": {
            "description": "The merge was refused, with the reason in `text`. This is the endpoint's catch-all failure status: it covers unknown ids, which are **not** answered 404.\n\nRefusals observed live:\n\n| `text` | Cause |\n|---|---|\n| `You must have access to both contacts to merge them.` | Either id does not exist, or is outside the key's committee. |\n| `One or more of these contacts has already been merged.` | Either id was merged away by an earlier call. Permanent, and applies whichever side the id is on. |\n| `Must specify VanIDs for merging` | The body is missing `vanId`, or it is null, `0`, or too large for `int32`. |\n| `The body of the request is null or cannot be parsed.` | No body, or a body that is not a JSON object. |\n| `VANID {a} and VANID {b} cannot be be merged as they are not the same type of Contact…` | One contact is a person and the other an organization. (The doubled \"be be\" is the API's own wording.) |\n\n`?whatIf=` with an empty value is also rejected here, with the generic `BAD_REQUEST` / `The request is invalid.`\n\nTwo cases answer `text/html` instead, because the request is rejected in front of the API: a percent-encoded control character such as `%7F` in the path gets IIS's \"Bad Request - Invalid URL\" page, and `%00` gets Cloudflare's. Check the content type before parsing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "merge-empty-whatif-is-rejected": {
                    "summary": "An empty whatIf is rejected outright",
                    "description": "`?whatIf=` is the one value that neither simulates nor merges: it is refused with a bare BAD_REQUEST. Every other non-empty value performs the merge, so the empty string is the only typo here that is safe.",
                    "x-transcript": "merge-empty-whatif-is-rejected",
                    "value": {
                      "errors": [
                        {
                          "code": "BAD_REQUEST",
                          "text": "The request is invalid."
                        }
                      ]
                    }
                  },
                  "merge-refuses-mismatched-contact-modes": {
                    "summary": "A person and an organization cannot be merged",
                    "description": "Both records must be the same kind of contact. The refusal names both vanIds and tells the caller to change the contactMode in the UI first, so it is the only 400 here that identifies which records were at fault.",
                    "x-transcript": "merge-refuses-mismatched-contact-modes",
                    "value": {
                      "errors": [
                        {
                          "code": "INVALID_PARAMETER",
                          "text": "VANID 100000002 and VANID 100000001 cannot be be merged as they are not the same type of Contact. In order to merge contacts, both records must either be people or organizations. To enable the merge, navigate to the incorrectly typed record and change its type."
                        }
                      ]
                    }
                  },
                  "merge-refuses-unusable-bodies/1": {
                    "summary": "A JSON object that parses fine but names no counterpart.",
                    "description": "A well-formed object that simply has no vanId is refused differently from a body that is not an object at all, so the message distinguishes 'you forgot the id' from 'I could not read this'.",
                    "x-transcript": "merge-refuses-unusable-bodies",
                    "value": {
                      "errors": [
                        {
                          "code": "INVALID_PARAMETER",
                          "text": "Must specify VanIDs for merging"
                        }
                      ]
                    }
                  },
                  "merge-refuses-unusable-bodies/2": {
                    "summary": "A body that is valid JSON but not an object at all.",
                    "description": "A well-formed object that simply has no vanId is refused differently from a body that is not an object at all, so the message distinguishes 'you forgot the id' from 'I could not read this'.",
                    "x-transcript": "merge-refuses-unusable-bodies",
                    "value": {
                      "errors": [
                        {
                          "code": "INVALID_PARAMETER",
                          "text": "The body of the request is null or cannot be parsed."
                        }
                      ]
                    }
                  },
                  "merge-remembers-merged-away-ids/1": {
                    "summary": "Reuse that merged-away id in a fresh merge. It is remembered, permanently.",
                    "description": "A vanId that has been merged away is refused on either side of any later merge with a different message from the one an id that never existed gets. Since GET /people/{vanId} answers 404 for both, this endpoint is the only way to tell them apart.",
                    "x-transcript": "merge-remembers-merged-away-ids",
                    "value": {
                      "errors": [
                        {
                          "code": "INVALID_PARAMETER",
                          "text": "One or more of these contacts has already been merged."
                        }
                      ]
                    }
                  },
                  "merge-remembers-merged-away-ids/2": {
                    "summary": "An id that never existed is refused too, but with different text. That difference is the only way to tell the two apart — GET /people/{vanId} answers 404 for both.",
                    "description": "A vanId that has been merged away is refused on either side of any later merge with a different message from the one an id that never existed gets. Since GET /people/{vanId} answers 404 for both, this endpoint is the only way to tell them apart.",
                    "x-transcript": "merge-remembers-merged-away-ids",
                    "value": {
                      "errors": [
                        {
                          "code": "INVALID_PARAMETER",
                          "text": "You must have access to both contacts to merge them."
                        }
                      ]
                    }
                  }
                }
              },
              "text/html": {
                "schema": {
                  "type": "string"
                },
                "x-provenance": {
                  "note": "IIS and Cloudflare rejection pages for control characters in the path; see the shared BadRequest response for the full story and examples. Not specific to this operation."
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Never returned by the API itself — an unknown vanId is a **400** here, not a 404. This status only comes from IIS, in front of the API, and always as HTML: a non-integer path segment matches no route, and a query string longer than ~2048 characters is rejected outright.",
            "x-provenance": {
              "source": "sandbox probe",
              "lastProbed": "2026-08-05",
              "note": "PUT /people/abc/mergeInto returns the IIS \"404 - File or directory not found\" page. Unlike the other person endpoints, there is no JSON 404 to pair with it: unknown, zero and already-merged ids are all answered 400."
            },
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "Emails are combined onto the primary, and shared ones are not doubled",
            "source": "# The two people's emails are pooled onto the primary. An address both held\n# is collapsed to one entry — matched case-insensitively, keeping the\n# primary's copy — and an email that belonged only to the secondary now\n# resolves to the primary through POST /people/find.\n\n# Each person holds one email of their own, plus one they share — spelled\n# with different case on each side.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Fern\",\n    \"lastName\": \"Aldana\",\n    \"emails\": [\n      {\n        \"email\": \"fern.primary@example.com\"\n      },\n      {\n        \"email\": \"fern.shared@example.com\"\n      }\n    ]\n  }'\n# → 201  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Stored\"\n# }\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Fern\",\n    \"lastName\": \"Aldana\",\n    \"emails\": [\n      {\n        \"email\": \"fern.secondary@example.com\"\n      },\n      {\n        \"email\": \"FERN.SHARED@example.com\"\n      }\n    ]\n  }'\n# → 201  Location: https://api.securevan.com/v4/people/100000002\n# {\n#   \"vanId\": 100000002,\n#   \"status\": \"Stored\"\n# }\n\ncurl -sS -X PUT 'https://api.securevan.com/v4/people/100000002/mergeInto' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"vanId\": 100000001\n  }'\n# → 200  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001\n# }\n\n# Three emails, not four: the shared address collapsed to a single entry, in\n# the primary's spelling.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people/100000001?%24expand=emails' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 200\n# {\n#   \"vanId\": 100000001,\n#   \"firstName\": \"Fern\",\n#   \"lastName\": \"Aldana\",\n#   \"middleName\": null,\n#   \"suffix\": null,\n#   \"title\": null,\n#   \"sourceFileTitle\": null,\n#   \"sourceFileFirstName\": null,\n#   \"sourceFileMiddleName\": null,\n#   \"sourceFileLastName\": null,\n#   \"sourceFileSuffix\": null,\n#   \"contactSource\": \"API\",\n#   \"contactMode\": \"Person\",\n#   \"organizationContactCommonName\": null,\n#   \"organizationContactOfficialName\": null,\n#   \"salutation\": \"Fern\",\n#   \"formalSalutation\": \"Fern Aldana\",\n#   \"additionalSalutation\": null,\n#   \"preferredPronoun\": null,\n#   \"pronouns\": null,\n#   \"namePronunciation\": null,\n#   \"envelopeName\": \"Fern Aldana\",\n#   \"formalEnvelopeName\": \"Fern Aldana\",\n#   \"additionalEnvelopeName\": null,\n#   \"contactMethodPreferenceCode\": null,\n#   \"contactMethodPreferenceId\": null,\n#   \"contactMethodPreferenceName\": null,\n#   \"assistantName\": null,\n#   \"nickname\": null,\n#   \"website\": null,\n#   \"professionalSuffix\": null,\n#   \"party\": null,\n#   \"employer\": null,\n#   \"occupation\": null,\n#   \"jobTitle\": null,\n#   \"sex\": null,\n#   \"dateOfBirth\": null,\n#   \"isDeceased\": false,\n#   \"dateCreated\": \"2026-01-01T00:00:00Z\",\n#   \"dateAcquired\": \"0001-01-01T00:00:00Z\",\n#   \"selfReportedRace\": null,\n#   \"selfReportedEthnicity\": null,\n#   \"selfReportedRaces\": null,\n#   \"selfReportedEthnicities\": null,\n#   \"selfReportedGenders\": null,\n#   \"selfReportedSexualOrientations\": null,\n#   \"selfReportedLanguagePreference\": null,\n#   \"selfReportedLanguagePreferences\": null,\n#   \"emails\": [\n#     {\n#       \"type\": \"P\",\n#       \"email\": \"fern.primary@example.com\",\n#       \"dateCreated\": \"2026-01-01T00:00:00Z\",\n#       \"isPreferred\": false,\n#       \"isSubscribed\": true,\n#       \"subscriptionStatus\": \"S\"\n#     },\n#     {\n#       \"type\": \"P\",\n#       \"email\": \"fern.shared@example.com\",\n#       \"dateCreated\": \"2026-01-01T00:00:00Z\",\n#       \"isPreferred\": true,\n#       \"isSubscribed\": true,\n#       \"subscriptionStatus\": \"S\"\n#     },\n#     {\n#       \"type\": \"P\",\n#       \"email\": \"fern.secondary@example.com\",\n#       \"dateCreated\": \"2026-01-01T00:00:00Z\",\n#       \"isPreferred\": false,\n#       \"isSubscribed\": true,\n#       \"subscriptionStatus\": \"S\"\n#     }\n#   ],\n#   \"phones\": null,\n#   \"addresses\": null,\n#   \"recordedAddresses\": null,\n#   \"pollingLocation\": null,\n#   \"earlyVoteLocation\": null,\n#   \"identifiers\": null,\n#   \"codes\": null,\n#   \"customFields\": null,\n#   \"primaryCustomField\": null,\n#   \"contributionSummary\": null,\n#   \"suppressions\": null,\n#   \"caseworkCases\": null,\n#   \"caseworkIssues\": null,\n#   \"caseworkStories\": null,\n#   \"notes\": null,\n#   \"scores\": null,\n#   \"customProperties\": null,\n#   \"electionRecords\": null,\n#   \"membershipStatus\": null,\n#   \"organizationRoles\": null,\n#   \"districts\": null,\n#   \"surveyQuestionResponses\": null,\n#   \"finderNumber\": null,\n#   \"biographyImageUrl\": null,\n#   \"biographyText\": null,\n#   \"biographyHtml\": null,\n#   \"primaryContact\": null\n# }\n\n# Reachability moved too: the secondary's own email now finds the primary.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/find' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"emails\": [\n      {\n        \"email\": \"fern.secondary@example.com\"\n      }\n    ]\n  }'\n# → 302  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Matched\"\n# }",
            "x-transcript": "merge-combines-emails-and-moves-reachability"
          },
          {
            "lang": "Shell",
            "label": "A merge keeps the primary, deletes the secondary, and answers with the survivor",
            "source": "# The secondary named in the path is merged into the primary named in the\n# body. The 200 carries the primary's vanId — the survivor, not the id from\n# the path — with a Location pointing at it, and the secondary answers 404\n# from then on.\n\nCREATE_BODY='{\n  \"firstName\": \"Lena\",\n  \"lastName\": \"Voss\"\n}'\n\n# Two duplicates of one person. The primary survives; the secondary is\n# consumed.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"$CREATE_BODY\"\n# → 201  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Stored\"\n# }\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"$CREATE_BODY\"\n# → 201  Location: https://api.securevan.com/v4/people/100000002\n# {\n#   \"vanId\": 100000002,\n#   \"status\": \"Stored\"\n# }\n\n# The secondary goes in the path; the body names the primary that survives.\n\ncurl -sS -X PUT 'https://api.securevan.com/v4/people/100000002/mergeInto' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"vanId\": 100000001\n  }'\n# → 200  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001\n# }\n\n# The primary is still there under its own vanId.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people/100000001' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 200\n# {\n#   \"vanId\": 100000001,\n#   \"firstName\": \"Lena\",\n#   \"lastName\": \"Voss\",\n#   \"middleName\": null,\n#   \"suffix\": null,\n#   \"title\": null,\n#   \"sourceFileTitle\": null,\n#   \"sourceFileFirstName\": null,\n#   \"sourceFileMiddleName\": null,\n#   \"sourceFileLastName\": null,\n#   \"sourceFileSuffix\": null,\n#   \"contactSource\": \"API\",\n#   \"contactMode\": \"Person\",\n#   \"organizationContactCommonName\": null,\n#   \"organizationContactOfficialName\": null,\n#   \"salutation\": \"Lena\",\n#   \"formalSalutation\": \"Lena Voss\",\n#   \"additionalSalutation\": null,\n#   \"preferredPronoun\": null,\n#   \"pronouns\": null,\n#   \"namePronunciation\": null,\n#   \"envelopeName\": \"Lena Voss\",\n#   \"formalEnvelopeName\": \"Lena Voss\",\n#   \"additionalEnvelopeName\": null,\n#   \"contactMethodPreferenceCode\": null,\n#   \"contactMethodPreferenceId\": null,\n#   \"contactMethodPreferenceName\": null,\n#   \"assistantName\": null,\n#   \"nickname\": null,\n#   \"website\": null,\n#   \"professionalSuffix\": null,\n#   \"party\": null,\n#   \"employer\": null,\n#   \"occupation\": null,\n#   \"jobTitle\": null,\n#   \"sex\": null,\n#   \"dateOfBirth\": null,\n#   \"isDeceased\": false,\n#   \"dateCreated\": \"2026-01-01T00:00:00Z\",\n#   \"dateAcquired\": \"0001-01-01T00:00:00Z\",\n#   \"selfReportedRace\": null,\n#   \"selfReportedEthnicity\": null,\n#   \"selfReportedRaces\": null,\n#   \"selfReportedEthnicities\": null,\n#   \"selfReportedGenders\": null,\n#   \"selfReportedSexualOrientations\": null,\n#   \"selfReportedLanguagePreference\": null,\n#   \"selfReportedLanguagePreferences\": null,\n#   \"emails\": null,\n#   \"phones\": null,\n#   \"addresses\": null,\n#   \"recordedAddresses\": null,\n#   \"pollingLocation\": null,\n#   \"earlyVoteLocation\": null,\n#   \"identifiers\": null,\n#   \"codes\": null,\n#   \"customFields\": null,\n#   \"primaryCustomField\": null,\n#   \"contributionSummary\": null,\n#   \"suppressions\": null,\n#   \"caseworkCases\": null,\n#   \"caseworkIssues\": null,\n#   \"caseworkStories\": null,\n#   \"notes\": null,\n#   \"scores\": null,\n#   \"customProperties\": null,\n#   \"electionRecords\": null,\n#   \"membershipStatus\": null,\n#   \"organizationRoles\": null,\n#   \"districts\": null,\n#   \"surveyQuestionResponses\": null,\n#   \"finderNumber\": null,\n#   \"biographyImageUrl\": null,\n#   \"biographyText\": null,\n#   \"biographyHtml\": null,\n#   \"primaryContact\": null\n# }\n\n# The secondary is not, and never will be — merges cannot be undone.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people/100000002' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 404\n# {\n#   \"errors\": [\n#     {\n#       \"code\": \"NOT_FOUND\",\n#       \"text\": \"The specified resource cannot be found.\"\n#     }\n#   ]\n# }",
            "x-transcript": "merge-deletes-secondary-and-answers-with-primary"
          },
          {
            "lang": "Shell",
            "label": "An empty whatIf is rejected outright",
            "source": "# `?whatIf=` is the one value that neither simulates nor merges: it is\n# refused with a bare BAD_REQUEST. Every other non-empty value performs the\n# merge, so the empty string is the only typo here that is safe.\n\nCREATE_BODY='{\n  \"firstName\": \"Dana\",\n  \"lastName\": \"Whitfield\"\n}'\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"$CREATE_BODY\"\n# → 201  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Stored\"\n# }\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"$CREATE_BODY\"\n# → 201  Location: https://api.securevan.com/v4/people/100000002\n# {\n#   \"vanId\": 100000002,\n#   \"status\": \"Stored\"\n# }\n\n# Send the parameter with no value. Nothing is merged and nothing is\n# simulated.\n\ncurl -sS -X PUT 'https://api.securevan.com/v4/people/100000002/mergeInto?whatIf=' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"vanId\": 100000001\n  }'\n# → 400\n# {\n#   \"errors\": [\n#     {\n#       \"code\": \"BAD_REQUEST\",\n#       \"text\": \"The request is invalid.\"\n#     }\n#   ]\n# }\n\n# Both records survive, confirming the request was refused before anything\n# was written.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people/100000002' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 200\n# {\n#   \"vanId\": 100000002,\n#   \"firstName\": \"Dana\",\n#   \"lastName\": \"Whitfield\",\n#   \"middleName\": null,\n#   \"suffix\": null,\n#   \"title\": null,\n#   \"sourceFileTitle\": null,\n#   \"sourceFileFirstName\": null,\n#   \"sourceFileMiddleName\": null,\n#   \"sourceFileLastName\": null,\n#   \"sourceFileSuffix\": null,\n#   \"contactSource\": \"API\",\n#   \"contactMode\": \"Person\",\n#   \"organizationContactCommonName\": null,\n#   \"organizationContactOfficialName\": null,\n#   \"salutation\": \"Dana\",\n#   \"formalSalutation\": \"Dana Whitfield\",\n#   \"additionalSalutation\": null,\n#   \"preferredPronoun\": null,\n#   \"pronouns\": null,\n#   \"namePronunciation\": null,\n#   \"envelopeName\": \"Dana Whitfield\",\n#   \"formalEnvelopeName\": \"Dana Whitfield\",\n#   \"additionalEnvelopeName\": null,\n#   \"contactMethodPreferenceCode\": null,\n#   \"contactMethodPreferenceId\": null,\n#   \"contactMethodPreferenceName\": null,\n#   \"assistantName\": null,\n#   \"nickname\": null,\n#   \"website\": null,\n#   \"professionalSuffix\": null,\n#   \"party\": null,\n#   \"employer\": null,\n#   \"occupation\": null,\n#   \"jobTitle\": null,\n#   \"sex\": null,\n#   \"dateOfBirth\": null,\n#   \"isDeceased\": false,\n#   \"dateCreated\": \"2026-01-01T00:00:00Z\",\n#   \"dateAcquired\": \"0001-01-01T00:00:00Z\",\n#   \"selfReportedRace\": null,\n#   \"selfReportedEthnicity\": null,\n#   \"selfReportedRaces\": null,\n#   \"selfReportedEthnicities\": null,\n#   \"selfReportedGenders\": null,\n#   \"selfReportedSexualOrientations\": null,\n#   \"selfReportedLanguagePreference\": null,\n#   \"selfReportedLanguagePreferences\": null,\n#   \"emails\": null,\n#   \"phones\": null,\n#   \"addresses\": null,\n#   \"recordedAddresses\": null,\n#   \"pollingLocation\": null,\n#   \"earlyVoteLocation\": null,\n#   \"identifiers\": null,\n#   \"codes\": null,\n#   \"customFields\": null,\n#   \"primaryCustomField\": null,\n#   \"contributionSummary\": null,\n#   \"suppressions\": null,\n#   \"caseworkCases\": null,\n#   \"caseworkIssues\": null,\n#   \"caseworkStories\": null,\n#   \"notes\": null,\n#   \"scores\": null,\n#   \"customProperties\": null,\n#   \"electionRecords\": null,\n#   \"membershipStatus\": null,\n#   \"organizationRoles\": null,\n#   \"districts\": null,\n#   \"surveyQuestionResponses\": null,\n#   \"finderNumber\": null,\n#   \"biographyImageUrl\": null,\n#   \"biographyText\": null,\n#   \"biographyHtml\": null,\n#   \"primaryContact\": null\n# }",
            "x-transcript": "merge-empty-whatif-is-rejected"
          },
          {
            "lang": "Shell",
            "label": "Conflicting fields keep the primary's value; the primary's gaps fill from the secondary",
            "source": "# Scalar fields the two people disagree on keep the primary's value, and\n# fields the primary left empty are filled in from the secondary — so the\n# primary can come out of a merge holding more data than it went in with.\n\n# The two disagree on firstName, and the primary lacks the middleName and\n# occupation the secondary holds.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Beatriz\",\n    \"lastName\": \"Fontaine\"\n  }'\n# → 201  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Stored\"\n# }\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Bea\",\n    \"middleName\": \"Lucia\",\n    \"lastName\": \"Fontaine\",\n    \"occupation\": \"Archivist\"\n  }'\n# → 201  Location: https://api.securevan.com/v4/people/100000002\n# {\n#   \"vanId\": 100000002,\n#   \"status\": \"Stored\"\n# }\n\ncurl -sS -X PUT 'https://api.securevan.com/v4/people/100000002/mergeInto' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"vanId\": 100000001\n  }'\n# → 200  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001\n# }\n\n# The disputed firstName kept the primary's value; the middleName and\n# occupation the primary lacked were filled in from the secondary.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people/100000001' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 200\n# {\n#   \"vanId\": 100000001,\n#   \"firstName\": \"Beatriz\",\n#   \"lastName\": \"Fontaine\",\n#   \"middleName\": \"Lucia\",\n#   \"suffix\": null,\n#   \"title\": null,\n#   \"sourceFileTitle\": null,\n#   \"sourceFileFirstName\": null,\n#   \"sourceFileMiddleName\": null,\n#   \"sourceFileLastName\": null,\n#   \"sourceFileSuffix\": null,\n#   \"contactSource\": \"API\",\n#   \"contactMode\": \"Person\",\n#   \"organizationContactCommonName\": null,\n#   \"organizationContactOfficialName\": null,\n#   \"salutation\": \"Beatriz\",\n#   \"formalSalutation\": \"Beatriz Fontaine\",\n#   \"additionalSalutation\": null,\n#   \"preferredPronoun\": null,\n#   \"pronouns\": null,\n#   \"namePronunciation\": null,\n#   \"envelopeName\": \"Beatriz L. Fontaine\",\n#   \"formalEnvelopeName\": \"Beatriz L. Fontaine\",\n#   \"additionalEnvelopeName\": null,\n#   \"contactMethodPreferenceCode\": null,\n#   \"contactMethodPreferenceId\": null,\n#   \"contactMethodPreferenceName\": null,\n#   \"assistantName\": null,\n#   \"nickname\": null,\n#   \"website\": null,\n#   \"professionalSuffix\": null,\n#   \"party\": null,\n#   \"employer\": null,\n#   \"occupation\": \"Archivist\",\n#   \"jobTitle\": null,\n#   \"sex\": null,\n#   \"dateOfBirth\": null,\n#   \"isDeceased\": false,\n#   \"dateCreated\": \"2026-01-01T00:00:00Z\",\n#   \"dateAcquired\": \"0001-01-01T00:00:00Z\",\n#   \"selfReportedRace\": null,\n#   \"selfReportedEthnicity\": null,\n#   \"selfReportedRaces\": null,\n#   \"selfReportedEthnicities\": null,\n#   \"selfReportedGenders\": null,\n#   \"selfReportedSexualOrientations\": null,\n#   \"selfReportedLanguagePreference\": null,\n#   \"selfReportedLanguagePreferences\": null,\n#   \"emails\": null,\n#   \"phones\": null,\n#   \"addresses\": null,\n#   \"recordedAddresses\": null,\n#   \"pollingLocation\": null,\n#   \"earlyVoteLocation\": null,\n#   \"identifiers\": null,\n#   \"codes\": null,\n#   \"customFields\": null,\n#   \"primaryCustomField\": null,\n#   \"contributionSummary\": null,\n#   \"suppressions\": null,\n#   \"caseworkCases\": null,\n#   \"caseworkIssues\": null,\n#   \"caseworkStories\": null,\n#   \"notes\": null,\n#   \"scores\": null,\n#   \"customProperties\": null,\n#   \"electionRecords\": null,\n#   \"membershipStatus\": null,\n#   \"organizationRoles\": null,\n#   \"districts\": null,\n#   \"surveyQuestionResponses\": null,\n#   \"finderNumber\": null,\n#   \"biographyImageUrl\": null,\n#   \"biographyText\": null,\n#   \"biographyHtml\": null,\n#   \"primaryContact\": null\n# }",
            "x-transcript": "merge-keeps-primary-values-and-fills-its-gaps"
          },
          {
            "lang": "Shell",
            "label": "A person and an organization cannot be merged",
            "source": "# Both records must be the same kind of contact. The refusal names both\n# vanIds and tells the caller to change the contactMode in the UI first, so\n# it is the only 400 here that identifies which records were at fault.\n\n# One person and one organization — the same database, two kinds of contact.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"contactMode\": \"Organization\",\n    \"lastName\": \"Harborview Tenants Union\"\n  }'\n# → 201  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Stored\"\n# }\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Theo\",\n    \"lastName\": \"Marsh\"\n  }'\n# → 201  Location: https://api.securevan.com/v4/people/100000002\n# {\n#   \"vanId\": 100000002,\n#   \"status\": \"Stored\"\n# }\n\n# Simulate the merge, so the refusal is the only thing this behavior can\n# possibly do. The kinds are checked before anything else about the pair.\n\ncurl -sS -X PUT 'https://api.securevan.com/v4/people/100000002/mergeInto?whatIf=true' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"vanId\": 100000001\n  }'\n# → 400\n# {\n#   \"errors\": [\n#     {\n#       \"code\": \"INVALID_PARAMETER\",\n#       \"text\": \"VANID 100000002 and VANID 100000001 cannot be be merged as they are not the same type of Contact. In order to merge contacts, both records must either be people or organizations. To enable the merge, navigate to the incorrectly typed record and change its type.\"\n#     }\n#   ]\n# }",
            "x-transcript": "merge-refuses-mismatched-contact-modes"
          },
          {
            "lang": "Shell",
            "label": "A body without a usable vanId is refused, with two different messages",
            "source": "# A well-formed object that simply has no vanId is refused differently from\n# a body that is not an object at all, so the message distinguishes 'you\n# forgot the id' from 'I could not read this'.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Priya\",\n    \"lastName\": \"Raman\"\n  }'\n# → 201  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Stored\"\n# }\n\n# A JSON object that parses fine but names no counterpart.\n\ncurl -sS -X PUT 'https://api.securevan.com/v4/people/100000001/mergeInto' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{}\n  {}'\n# → 400\n# {\n#   \"errors\": [\n#     {\n#       \"code\": \"INVALID_PARAMETER\",\n#       \"text\": \"Must specify VanIDs for merging\"\n#     }\n#   ]\n# }\n\n# A body that is valid JSON but not an object at all.\n\ncurl -sS -X PUT 'https://api.securevan.com/v4/people/100000001/mergeInto' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '\"nope\"\n  \"nope\"'\n# → 400\n# {\n#   \"errors\": [\n#     {\n#       \"code\": \"INVALID_PARAMETER\",\n#       \"text\": \"The body of the request is null or cannot be parsed.\"\n#     }\n#   ]\n# }",
            "x-transcript": "merge-refuses-unusable-bodies"
          },
          {
            "lang": "Shell",
            "label": "A merged-away vanId is refused forever, with its own message",
            "source": "# A vanId that has been merged away is refused on either side of any later\n# merge with a different message from the one an id that never existed gets.\n# Since GET /people/{vanId} answers 404 for both, this endpoint is the only\n# way to tell them apart.\n\nCREATE_BODY='{\n  \"firstName\": \"Ivy\",\n  \"lastName\": \"Calloway\"\n}'\n\nMERGEINTO_BODY='{\n  \"vanId\": 100000003\n}'\n\n# Three records: two to merge now, one to attempt a second merge against\n# later.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"$CREATE_BODY\"\n# → 201  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Stored\"\n# }\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"$CREATE_BODY\"\n# → 201  Location: https://api.securevan.com/v4/people/100000002\n# {\n#   \"vanId\": 100000002,\n#   \"status\": \"Stored\"\n# }\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Omar\",\n    \"lastName\": \"Haddad\"\n  }'\n# → 201  Location: https://api.securevan.com/v4/people/100000003\n# {\n#   \"vanId\": 100000003,\n#   \"status\": \"Stored\"\n# }\n\n# Merge the secondary away. Its vanId now 404s on GET /people/{vanId}.\n\ncurl -sS -X PUT 'https://api.securevan.com/v4/people/100000002/mergeInto' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"vanId\": 100000001\n  }'\n# → 200  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001\n# }\n\n# Reuse that merged-away id in a fresh merge. It is remembered, permanently.\n\ncurl -sS -X PUT 'https://api.securevan.com/v4/people/100000002/mergeInto' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"$MERGEINTO_BODY\"\n# → 400\n# {\n#   \"errors\": [\n#     {\n#       \"code\": \"INVALID_PARAMETER\",\n#       \"text\": \"One or more of these contacts has already been merged.\"\n#     }\n#   ]\n# }\n\n# An id that never existed is refused too, but with different text. That\n# difference is the only way to tell the two apart — GET /people/{vanId}\n# answers 404 for both.\n\ncurl -sS -X PUT 'https://api.securevan.com/v4/people/2147483646/mergeInto' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"$MERGEINTO_BODY\"\n# → 400\n# {\n#   \"errors\": [\n#     {\n#       \"code\": \"INVALID_PARAMETER\",\n#       \"text\": \"You must have access to both contacts to merge them.\"\n#     }\n#   ]\n# }",
            "x-transcript": "merge-remembers-merged-away-ids"
          },
          {
            "lang": "Shell",
            "label": "whatIf only simulates for the literal string 'true'",
            "source": "# Only the exact value `true` simulates. Every other non-empty value —\n# including `1` and `yes` — is read as false and performs the merge for\n# real, and the response is identical either way, so nothing in it reveals\n# which one happened.\n\n# Two records to merge: the primary survives, the secondary is consumed.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Rosa\",\n    \"lastName\": \"Delgado\",\n    \"emails\": [\n      {\n        \"email\": \"rosa.delgado@example.com\"\n      }\n    ]\n  }'\n# → 201  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Stored\"\n# }\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Rosa\",\n    \"lastName\": \"Delgado\",\n    \"emails\": [\n      {\n        \"email\": \"rdelgado@example.com\"\n      }\n    ]\n  }'\n# → 201  Location: https://api.securevan.com/v4/people/100000002\n# {\n#   \"vanId\": 100000002,\n#   \"status\": \"Stored\"\n# }\n\n# Ask for a simulation with whatIf=yes — truthy in every language a caller\n# might write this in. The 200 below is exactly what a real simulation\n# returns.\n\ncurl -sS -X PUT 'https://api.securevan.com/v4/people/100000002/mergeInto?whatIf=yes' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"vanId\": 100000001\n  }'\n# → 200  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001\n# }\n\n# But nothing was simulated. The secondary is gone for good — only the\n# literal string `true` suppresses the write.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people/100000002' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 404\n# {\n#   \"errors\": [\n#     {\n#       \"code\": \"NOT_FOUND\",\n#       \"text\": \"The specified resource cannot be found.\"\n#     }\n#   ]\n# }",
            "x-transcript": "merge-whatif-requires-literal-true"
          },
          {
            "lang": "Shell",
            "label": "whatIf=true returns the completed-merge response without merging",
            "source": "# A simulation answers exactly as a real merge does — same 200, same body,\n# same Location pointing at the primary — while both records survive. The\n# response is therefore no evidence that a merge happened.\n\nCREATE_BODY='{\n  \"firstName\": \"Miles\",\n  \"lastName\": \"Okafor\"\n}'\n\n# Two records to merge: the primary would survive, the secondary would be\n# consumed.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"$CREATE_BODY\"\n# → 201  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Stored\"\n# }\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"$CREATE_BODY\"\n# → 201  Location: https://api.securevan.com/v4/people/100000002\n# {\n#   \"vanId\": 100000002,\n#   \"status\": \"Stored\"\n# }\n\n# Simulate with the literal string `true` — the only value that suppresses\n# the write.\n\ncurl -sS -X PUT 'https://api.securevan.com/v4/people/100000002/mergeInto?whatIf=true' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"vanId\": 100000001\n  }'\n# → 200  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001\n# }\n\n# Nothing was written: the secondary is still there, unlike after a real\n# merge.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people/100000002' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 200\n# {\n#   \"vanId\": 100000002,\n#   \"firstName\": \"Miles\",\n#   \"lastName\": \"Okafor\",\n#   \"middleName\": null,\n#   \"suffix\": null,\n#   \"title\": null,\n#   \"sourceFileTitle\": null,\n#   \"sourceFileFirstName\": null,\n#   \"sourceFileMiddleName\": null,\n#   \"sourceFileLastName\": null,\n#   \"sourceFileSuffix\": null,\n#   \"contactSource\": \"API\",\n#   \"contactMode\": \"Person\",\n#   \"organizationContactCommonName\": null,\n#   \"organizationContactOfficialName\": null,\n#   \"salutation\": \"Miles\",\n#   \"formalSalutation\": \"Miles Okafor\",\n#   \"additionalSalutation\": null,\n#   \"preferredPronoun\": null,\n#   \"pronouns\": null,\n#   \"namePronunciation\": null,\n#   \"envelopeName\": \"Miles Okafor\",\n#   \"formalEnvelopeName\": \"Miles Okafor\",\n#   \"additionalEnvelopeName\": null,\n#   \"contactMethodPreferenceCode\": null,\n#   \"contactMethodPreferenceId\": null,\n#   \"contactMethodPreferenceName\": null,\n#   \"assistantName\": null,\n#   \"nickname\": null,\n#   \"website\": null,\n#   \"professionalSuffix\": null,\n#   \"party\": null,\n#   \"employer\": null,\n#   \"occupation\": null,\n#   \"jobTitle\": null,\n#   \"sex\": null,\n#   \"dateOfBirth\": null,\n#   \"isDeceased\": false,\n#   \"dateCreated\": \"2026-01-01T00:00:00Z\",\n#   \"dateAcquired\": \"0001-01-01T00:00:00Z\",\n#   \"selfReportedRace\": null,\n#   \"selfReportedEthnicity\": null,\n#   \"selfReportedRaces\": null,\n#   \"selfReportedEthnicities\": null,\n#   \"selfReportedGenders\": null,\n#   \"selfReportedSexualOrientations\": null,\n#   \"selfReportedLanguagePreference\": null,\n#   \"selfReportedLanguagePreferences\": null,\n#   \"emails\": null,\n#   \"phones\": null,\n#   \"addresses\": null,\n#   \"recordedAddresses\": null,\n#   \"pollingLocation\": null,\n#   \"earlyVoteLocation\": null,\n#   \"identifiers\": null,\n#   \"codes\": null,\n#   \"customFields\": null,\n#   \"primaryCustomField\": null,\n#   \"contributionSummary\": null,\n#   \"suppressions\": null,\n#   \"caseworkCases\": null,\n#   \"caseworkIssues\": null,\n#   \"caseworkStories\": null,\n#   \"notes\": null,\n#   \"scores\": null,\n#   \"customProperties\": null,\n#   \"electionRecords\": null,\n#   \"membershipStatus\": null,\n#   \"organizationRoles\": null,\n#   \"districts\": null,\n#   \"surveyQuestionResponses\": null,\n#   \"finderNumber\": null,\n#   \"biographyImageUrl\": null,\n#   \"biographyText\": null,\n#   \"biographyHtml\": null,\n#   \"primaryContact\": null\n# }",
            "x-transcript": "merge-whatif-true-simulates-without-writing"
          }
        ]
      }
    },
    "/people/{vanId}/notes": {
      "get": {
        "operationId": "listPersonNotes",
        "summary": "List a person's notes",
        "description": "Returns the person's notes in the standard pagination envelope.\n\nView-restricted notes are withheld from API keys: a note saved with `isViewRestricted: true` is absent from `items` and is not counted in `count`, so every note in the response has `isViewRestricted` false. `contactHistory` is always null, even for a note created with one, and `$expand=noteDetails` — the only value the parameter accepts — returns a byte-identical body.\n\nItems come back oldest first by `createdDate`, ties broken by descending `noteId`. `$orderby` is validated against its two allowed properties but has no observable effect: `CreatedDate desc` returns the same order as the default.\n\nAn unknown, zero or negative vanId returns the standard 404 envelope; a non-integer path segment matches no route and returns an HTML 404 page.",
        "tags": [
          "Notes"
        ],
        "x-keywords": [
          "notes",
          "list notes",
          "read notes",
          "comments",
          "annotations",
          "note history"
        ],
        "x-task": "Read the notes on a person",
        "parameters": [
          {
            "name": "vanId",
            "in": "path",
            "required": true,
            "description": "VAN id of the person.",
            "x-docs-discrepancy": "Official docs type this path parameter as string (default \"100476252\"); the route only matches integers — a non-integer segment returns an IIS HTML 404 page (observed 2026-08-04).",
            "schema": {
              "type": "integer",
              "format": "int32",
              "minimum": 1
            },
            "example": 102714507
          },
          {
            "name": "$top",
            "in": "query",
            "description": "Limits the number of results. Default 25, maximum 50. A value of 0 or less returns 400; so does a non-numeric value, with the same message as an over-maximum one.",
            "schema": {
              "type": "integer",
              "format": "int32",
              "minimum": 1,
              "maximum": 50
            },
            "example": 25
          },
          {
            "name": "$skip",
            "in": "query",
            "description": "Number of results to skip. Must be 0 or greater.",
            "schema": {
              "type": "integer",
              "format": "int32",
              "minimum": 0
            },
            "example": 0
          },
          {
            "name": "$orderby",
            "in": "query",
            "description": "Accepted but ignored. The API validates the value — only `CreatedDate` and `IsPinned` pass, case-insensitively, optionally followed by ` desc` — and then returns the default order regardless, including for `desc`.",
            "x-provenance": {
              "source": "sandbox probe",
              "lastProbed": "2026-08-04",
              "note": "Valid values come from the API's own INVALID_PARAMETER hint on `$orderby=noteId`. All four accepted values, plus `createddate` in lower case, returned an identical item order on a person with six notes."
            },
            "schema": {
              "type": "string",
              "enum": [
                "CreatedDate",
                "CreatedDate desc",
                "IsPinned",
                "IsPinned desc"
              ]
            },
            "example": "CreatedDate"
          },
          {
            "name": "$expand",
            "in": "query",
            "description": "`noteDetails` is the only value the API accepts; anything else returns 400 INVALID_PARAMETER with a hint saying so. Expanding has no observable effect — the response is identical with and without it, `contactHistory` included.",
            "schema": {
              "type": "string",
              "enum": [
                "noteDetails"
              ]
            },
            "example": "noteDetails"
          }
        ],
        "responses": {
          "200": {
            "description": "A paginated list of the person's notes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NoteList"
                },
                "examples": {
                  "note-create-is-silent": {
                    "summary": "Creating a note returns nothing — the id has to be read back",
                    "description": "Success is a bare 204: no body, no Location header, no noteId. The only way to learn the new id is GET /people/{vanId}/notes. The read-back also shows `isPinned` was accepted and ignored, and that an uncategorized note reads as the `{noteCategoryId: 0, name: null}` stub.",
                    "x-transcript": "note-create-is-silent",
                    "value": {
                      "items": [
                        {
                          "contactHistory": null,
                          "noteId": 100000002,
                          "text": "Spoke at the door; wants a yard sign.",
                          "isViewRestricted": false,
                          "category": {
                            "noteCategoryId": 0,
                            "name": null
                          },
                          "createdDate": "2026-01-01T00:00:00Z",
                          "isPinned": false
                        }
                      ],
                      "nextPageLink": null,
                      "count": 1
                    }
                  },
                  "notes-list-tuning-parameters-are-inert/1": {
                    "summary": "$orderby and $expand are validated, then change nothing",
                    "description": "`$orderby=CreatedDate desc` and `$expand=noteDetails` both pass validation and both return a body identical to the plain request — the sort never reorders and the expand never populates `contactHistory`. Values outside the accepted sets are refused with INVALID_PARAMETER, so the parameters are checked strictly and then ignored.",
                    "x-transcript": "notes-list-tuning-parameters-are-inert",
                    "value": {
                      "items": [
                        {
                          "contactHistory": null,
                          "noteId": 100000002,
                          "text": "Interested in canvassing.",
                          "isViewRestricted": false,
                          "category": {
                            "noteCategoryId": 0,
                            "name": null
                          },
                          "createdDate": "2026-01-01T00:00:00Z",
                          "isPinned": false
                        }
                      ],
                      "nextPageLink": null,
                      "count": 1
                    }
                  },
                  "notes-list-tuning-parameters-are-inert/2": {
                    "summary": "Descending sort: accepted, and the body comes back identical to the plain call.",
                    "description": "`$orderby=CreatedDate desc` and `$expand=noteDetails` both pass validation and both return a body identical to the plain request — the sort never reorders and the expand never populates `contactHistory`. Values outside the accepted sets are refused with INVALID_PARAMETER, so the parameters are checked strictly and then ignored.",
                    "x-transcript": "notes-list-tuning-parameters-are-inert",
                    "value": {
                      "items": [
                        {
                          "contactHistory": null,
                          "noteId": 100000002,
                          "text": "Interested in canvassing.",
                          "isViewRestricted": false,
                          "category": {
                            "noteCategoryId": 0,
                            "name": null
                          },
                          "createdDate": "2026-01-01T00:00:00Z",
                          "isPinned": false
                        }
                      ],
                      "nextPageLink": null,
                      "count": 1
                    }
                  },
                  "notes-list-tuning-parameters-are-inert/3": {
                    "summary": "The one accepted $expand value: also identical, contactHistory still null.",
                    "description": "`$orderby=CreatedDate desc` and `$expand=noteDetails` both pass validation and both return a body identical to the plain request — the sort never reorders and the expand never populates `contactHistory`. Values outside the accepted sets are refused with INVALID_PARAMETER, so the parameters are checked strictly and then ignored.",
                    "x-transcript": "notes-list-tuning-parameters-are-inert",
                    "value": {
                      "items": [
                        {
                          "contactHistory": null,
                          "noteId": 100000002,
                          "text": "Interested in canvassing.",
                          "isViewRestricted": false,
                          "category": {
                            "noteCategoryId": 0,
                            "name": null
                          },
                          "createdDate": "2026-01-01T00:00:00Z",
                          "isPinned": false
                        }
                      ],
                      "nextPageLink": null,
                      "count": 1
                    }
                  },
                  "restricted-notes-vanish-from-the-api": {
                    "summary": "A view-restricted note can be written but never read back",
                    "description": "`isViewRestricted: true` is accepted with the same 204 as any other note, and the note is then withheld from API keys entirely: absent from items and not counted in count, so every note the API ever shows has the flag false.",
                    "x-transcript": "restricted-notes-vanish-from-the-api",
                    "value": {
                      "items": [
                        {
                          "contactHistory": null,
                          "noteId": 100000002,
                          "text": "Volunteered at the phone bank.",
                          "isViewRestricted": false,
                          "category": {
                            "noteCategoryId": 0,
                            "name": null
                          },
                          "createdDate": "2026-01-01T00:00:00Z",
                          "isPinned": false
                        }
                      ],
                      "nextPageLink": null,
                      "count": 1
                    }
                  }
                }
              },
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "302": {
            "$ref": "#/components/responses/RequestValidationRedirect"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/PersonNotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "Creating a note returns nothing — the id has to be read back",
            "source": "# Success is a bare 204: no body, no Location header, no noteId. The only\n# way to learn the new id is GET /people/{vanId}/notes. The read-back also\n# shows `isPinned` was accepted and ignored, and that an uncategorized note\n# reads as the `{noteCategoryId: 0, name: null}` stub.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Lucinda\",\n    \"lastName\": \"Farrow\"\n  }'\n# → 201  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Stored\"\n# }\n\n# Create a note, asking for a pin the API will ignore.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/100000001/notes' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"text\": \"Spoke at the door; wants a yard sign.\",\n    \"isViewRestricted\": false,\n    \"isPinned\": true\n  }'\n# → 204\n\n# Reading the list back is the only way to learn the noteId.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people/100000001/notes' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 200\n# {\n#   \"items\": [\n#     {\n#       \"contactHistory\": null,\n#       \"noteId\": 100000002,\n#       \"text\": \"Spoke at the door; wants a yard sign.\",\n#       \"isViewRestricted\": false,\n#       \"category\": {\n#         \"noteCategoryId\": 0,\n#         \"name\": null\n#       },\n#       \"createdDate\": \"2026-01-01T00:00:00Z\",\n#       \"isPinned\": false\n#     }\n#   ],\n#   \"nextPageLink\": null,\n#   \"count\": 1\n# }",
            "x-transcript": "note-create-is-silent"
          },
          {
            "lang": "Shell",
            "label": "$orderby and $expand are validated, then change nothing",
            "source": "# `$orderby=CreatedDate desc` and `$expand=noteDetails` both pass validation\n# and both return a body identical to the plain request — the sort never\n# reorders and the expand never populates `contactHistory`. Values outside\n# the accepted sets are refused with INVALID_PARAMETER, so the parameters\n# are checked strictly and then ignored.\n\n# A person with one note to list.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Prudence\",\n    \"lastName\": \"Ashby\"\n  }'\n# → 201  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Stored\"\n# }\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/100000001/notes' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"text\": \"Interested in canvassing.\",\n    \"isViewRestricted\": false\n  }'\n# → 204\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people/100000001/notes' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 200\n# {\n#   \"items\": [\n#     {\n#       \"contactHistory\": null,\n#       \"noteId\": 100000002,\n#       \"text\": \"Interested in canvassing.\",\n#       \"isViewRestricted\": false,\n#       \"category\": {\n#         \"noteCategoryId\": 0,\n#         \"name\": null\n#       },\n#       \"createdDate\": \"2026-01-01T00:00:00Z\",\n#       \"isPinned\": false\n#     }\n#   ],\n#   \"nextPageLink\": null,\n#   \"count\": 1\n# }\n\n# Descending sort: accepted, and the body comes back identical to the plain\n# call.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people/100000001/notes?%24orderby=CreatedDate+desc' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 200\n# {\n#   \"items\": [\n#     {\n#       \"contactHistory\": null,\n#       \"noteId\": 100000002,\n#       \"text\": \"Interested in canvassing.\",\n#       \"isViewRestricted\": false,\n#       \"category\": {\n#         \"noteCategoryId\": 0,\n#         \"name\": null\n#       },\n#       \"createdDate\": \"2026-01-01T00:00:00Z\",\n#       \"isPinned\": false\n#     }\n#   ],\n#   \"nextPageLink\": null,\n#   \"count\": 1\n# }\n\n# The one accepted $expand value: also identical, contactHistory still null.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people/100000001/notes?%24expand=noteDetails' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 200\n# {\n#   \"items\": [\n#     {\n#       \"contactHistory\": null,\n#       \"noteId\": 100000002,\n#       \"text\": \"Interested in canvassing.\",\n#       \"isViewRestricted\": false,\n#       \"category\": {\n#         \"noteCategoryId\": 0,\n#         \"name\": null\n#       },\n#       \"createdDate\": \"2026-01-01T00:00:00Z\",\n#       \"isPinned\": false\n#     }\n#   ],\n#   \"nextPageLink\": null,\n#   \"count\": 1\n# }\n\n# Anything outside the accepted sets is refused, not ignored.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people/100000001/notes?%24orderby=Text' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 400\n# {\n#   \"errors\": [\n#     {\n#       \"code\": \"INVALID_PARAMETER\",\n#       \"text\": \"'Text' is not a valid argument for the '$orderby' parameter\",\n#       \"properties\": [\n#         \"$orderby\"\n#       ],\n#       \"hint\": \"The only valid orderby properties are: 'CreatedDate', 'IsPinned'\"\n#     }\n#   ]\n# }\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people/100000001/notes?%24expand=contactHistory' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 400\n# {\n#   \"errors\": [\n#     {\n#       \"code\": \"INVALID_PARAMETER\",\n#       \"text\": \"'contactHistory' is not a valid argument for the '$expand' parameter\",\n#       \"properties\": [\n#         \"$expand\"\n#       ],\n#       \"hint\": \"The only valid expand section is: 'noteDetails'\"\n#     }\n#   ]\n# }",
            "x-transcript": "notes-list-tuning-parameters-are-inert"
          },
          {
            "lang": "Shell",
            "label": "A view-restricted note can be written but never read back",
            "source": "# `isViewRestricted: true` is accepted with the same 204 as any other note,\n# and the note is then withheld from API keys entirely: absent from items\n# and not counted in count, so every note the API ever shows has the flag\n# false.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Barnaby\",\n    \"lastName\": \"Quill\"\n  }'\n# → 201  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Stored\"\n# }\n\n# One ordinary note, one restricted. Both are accepted identically.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/100000001/notes' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"text\": \"Volunteered at the phone bank.\",\n    \"isViewRestricted\": false\n  }'\n# → 204\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/100000001/notes' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"text\": \"Do not publish this.\",\n    \"isViewRestricted\": true\n  }'\n# → 204\n\n# The list has one note. The restricted one is not hidden — it is simply not\n# there.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people/100000001/notes' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 200\n# {\n#   \"items\": [\n#     {\n#       \"contactHistory\": null,\n#       \"noteId\": 100000002,\n#       \"text\": \"Volunteered at the phone bank.\",\n#       \"isViewRestricted\": false,\n#       \"category\": {\n#         \"noteCategoryId\": 0,\n#         \"name\": null\n#       },\n#       \"createdDate\": \"2026-01-01T00:00:00Z\",\n#       \"isPinned\": false\n#     }\n#   ],\n#   \"nextPageLink\": null,\n#   \"count\": 1\n# }",
            "x-transcript": "restricted-notes-vanish-from-the-api"
          }
        ]
      },
      "post": {
        "operationId": "createPersonNote",
        "summary": "Add a note to a person",
        "description": "Creates a note on the person.\n\nOn success the response is **204 No Content** with an empty body: the new `noteId` is not returned and there is no `Location` header, so the only way to learn it is to read the notes back. Two notes with identical text are two separate notes — the endpoint is not idempotent.\n\n`isPinned` is accepted and ignored; notes always read back `isPinned: false`. Unknown fields are ignored too. A `contactHistory` object records a Contact History entry alongside the note, but the note's own `contactHistory` stays null in every response.\n\nA note saved with `isViewRestricted: true` can be written but never read back through the API — it is excluded from `GET /people/{vanId}/notes` and from `$expand=notes` on the person.",
        "tags": [
          "Notes"
        ],
        "x-keywords": [
          "add note",
          "write note",
          "leave a comment",
          "annotate",
          "log a call",
          "contact history",
          "record an interaction"
        ],
        "x-task": "Add a note to a person",
        "parameters": [
          {
            "name": "vanId",
            "in": "path",
            "required": true,
            "description": "VAN id of the person to attach the note to. An unknown, zero or negative id returns 404.",
            "x-docs-discrepancy": "Official docs type this path parameter as string (default \"100476252\"); the route only matches integers (observed 2026-08-04).",
            "schema": {
              "type": "integer",
              "format": "int32",
              "minimum": 1
            },
            "example": 102714507
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NoteInput"
              },
              "examples": {
                "minimal": {
                  "summary": "Text only",
                  "value": {
                    "text": "Great chat! This person will be able to volunteer next year."
                  }
                },
                "categorized": {
                  "summary": "With a category",
                  "description": "The sandbox committee has no note categories, so this one is illustrative — every id tried there returned 400.",
                  "value": {
                    "text": "Wants to host a house party.",
                    "isViewRestricted": false,
                    "category": {
                      "noteCategoryId": 24
                    }
                  }
                },
                "withContactHistory": {
                  "summary": "Recording a contact alongside the note",
                  "value": {
                    "text": "Spoke by phone; will vote early.",
                    "contactHistory": {
                      "contactTypeId": "1",
                      "inputTypeId": "11",
                      "resultCodeId": "14",
                      "dateCanvassed": "2026-08-01T00:00:00Z"
                    }
                  }
                },
                "note-create-is-silent": {
                  "summary": "Creating a note returns nothing — the id has to be read back",
                  "description": "Success is a bare 204: no body, no Location header, no noteId. The only way to learn the new id is GET /people/{vanId}/notes. The read-back also shows `isPinned` was accepted and ignored, and that an uncategorized note reads as the `{noteCategoryId: 0, name: null}` stub.",
                  "x-transcript": "note-create-is-silent",
                  "value": {
                    "text": "Spoke at the door; wants a yard sign.",
                    "isViewRestricted": false,
                    "isPinned": true
                  }
                },
                "restricted-notes-vanish-from-the-api/1": {
                  "summary": "One ordinary note, one restricted. Both are accepted identically.",
                  "description": "`isViewRestricted: true` is accepted with the same 204 as any other note, and the note is then withheld from API keys entirely: absent from items and not counted in count, so every note the API ever shows has the flag false.",
                  "x-transcript": "restricted-notes-vanish-from-the-api",
                  "value": {
                    "text": "Volunteered at the phone bank.",
                    "isViewRestricted": false
                  }
                },
                "restricted-notes-vanish-from-the-api/2": {
                  "summary": "A view-restricted note can be written but never read back",
                  "description": "`isViewRestricted: true` is accepted with the same 204 as any other note, and the note is then withheld from API keys entirely: absent from items and not counted in count, so every note the API ever shows has the flag false.",
                  "x-transcript": "restricted-notes-vanish-from-the-api",
                  "value": {
                    "text": "Do not publish this.",
                    "isViewRestricted": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "The note was created. Empty body, no Location header.",
            "links": {
              "listCreatedNote": {
                "operationId": "listPersonNotes",
                "parameters": {
                  "vanId": "$request.path.vanId"
                },
                "description": "Read the person's notes back — the create response does not identify the note it made."
              }
            }
          },
          "302": {
            "$ref": "#/components/responses/RequestValidationRedirect"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/PersonNotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "Creating a note returns nothing — the id has to be read back",
            "source": "# Success is a bare 204: no body, no Location header, no noteId. The only\n# way to learn the new id is GET /people/{vanId}/notes. The read-back also\n# shows `isPinned` was accepted and ignored, and that an uncategorized note\n# reads as the `{noteCategoryId: 0, name: null}` stub.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Lucinda\",\n    \"lastName\": \"Farrow\"\n  }'\n# → 201  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Stored\"\n# }\n\n# Create a note, asking for a pin the API will ignore.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/100000001/notes' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"text\": \"Spoke at the door; wants a yard sign.\",\n    \"isViewRestricted\": false,\n    \"isPinned\": true\n  }'\n# → 204\n\n# Reading the list back is the only way to learn the noteId.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people/100000001/notes' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 200\n# {\n#   \"items\": [\n#     {\n#       \"contactHistory\": null,\n#       \"noteId\": 100000002,\n#       \"text\": \"Spoke at the door; wants a yard sign.\",\n#       \"isViewRestricted\": false,\n#       \"category\": {\n#         \"noteCategoryId\": 0,\n#         \"name\": null\n#       },\n#       \"createdDate\": \"2026-01-01T00:00:00Z\",\n#       \"isPinned\": false\n#     }\n#   ],\n#   \"nextPageLink\": null,\n#   \"count\": 1\n# }",
            "x-transcript": "note-create-is-silent"
          },
          {
            "lang": "Shell",
            "label": "A view-restricted note can be written but never read back",
            "source": "# `isViewRestricted: true` is accepted with the same 204 as any other note,\n# and the note is then withheld from API keys entirely: absent from items\n# and not counted in count, so every note the API ever shows has the flag\n# false.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/create' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"firstName\": \"Barnaby\",\n    \"lastName\": \"Quill\"\n  }'\n# → 201  Location: https://api.securevan.com/v4/people/100000001\n# {\n#   \"vanId\": 100000001,\n#   \"status\": \"Stored\"\n# }\n\n# One ordinary note, one restricted. Both are accepted identically.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/100000001/notes' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"text\": \"Volunteered at the phone bank.\",\n    \"isViewRestricted\": false\n  }'\n# → 204\n\ncurl -sS -X POST 'https://api.securevan.com/v4/people/100000001/notes' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"text\": \"Do not publish this.\",\n    \"isViewRestricted\": true\n  }'\n# → 204\n\n# The list has one note. The restricted one is not hidden — it is simply not\n# there.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/people/100000001/notes' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 200\n# {\n#   \"items\": [\n#     {\n#       \"contactHistory\": null,\n#       \"noteId\": 100000002,\n#       \"text\": \"Volunteered at the phone bank.\",\n#       \"isViewRestricted\": false,\n#       \"category\": {\n#         \"noteCategoryId\": 0,\n#         \"name\": null\n#       },\n#       \"createdDate\": \"2026-01-01T00:00:00Z\",\n#       \"isPinned\": false\n#     }\n#   ],\n#   \"nextPageLink\": null,\n#   \"count\": 1\n# }",
            "x-transcript": "restricted-notes-vanish-from-the-api"
          }
        ]
      }
    },
    "/people/{vanId}/notes/{noteId}": {
      "put": {
        "operationId": "updatePersonNote",
        "summary": "Update a note on a person",
        "description": "Updates an existing note. Only `text`, `isViewRestricted` and `category` can be changed; `isPinned` and the note's contact history cannot.\n\n**This action is restricted for the key used to research this spec.** Every request returns 403 FORBIDDEN \"Access to this action is restricted\", whether or not the note exists, so the success path has not been observed live — the request body and the 204 below come from the official docs. `GET` and `DELETE` on this same path are restricted the same way; they are left out of this spec because their success shapes are unknown and undocumented.",
        "x-provenance": {
          "source": "docs, van-cli",
          "lastProbed": "2026-08-04",
          "note": "The route exists: it answers 403, not the 404 an unrouted path gives. PUT with a valid body against a real note (184579 on vanId 102714507) and against a nonexistent noteId both returned 403, so the restriction is applied before the note is looked up. The 204 success response is from https://docs.ngpvan.com/reference/peoplevanidnotesnoteid — not yet observed live."
        },
        "tags": [
          "Notes"
        ],
        "x-keywords": [
          "edit note",
          "update note",
          "change note text"
        ],
        "x-task": "Edit an existing note",
        "parameters": [
          {
            "name": "vanId",
            "in": "path",
            "required": true,
            "description": "VAN id of the person the note belongs to.",
            "schema": {
              "type": "integer",
              "format": "int32",
              "minimum": 1
            },
            "example": 102714507
          },
          {
            "name": "noteId",
            "in": "path",
            "required": true,
            "description": "Id of the note to edit, as returned by GET /people/{vanId}/notes.",
            "x-docs-discrepancy": "Official docs type this path parameter as string (default \"225\"); the route only matches integers (observed 2026-08-04).",
            "schema": {
              "type": "integer",
              "format": "int32",
              "minimum": 1
            },
            "example": 184579
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NoteUpdateInput"
              },
              "examples": {
                "editText": {
                  "summary": "Change the text",
                  "value": {
                    "text": "Updated after a follow-up call."
                  }
                },
                "recategorize": {
                  "summary": "Change text, visibility and category together",
                  "value": {
                    "text": "Updated after a follow-up call.",
                    "isViewRestricted": false,
                    "category": {
                      "noteCategoryId": 24
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "The note was updated. Empty body.",
            "x-provenance": {
              "source": "docs",
              "note": "From the official docs; not observed live — the sandbox key gets 403 for this action."
            }
          },
          "302": {
            "$ref": "#/components/responses/RequestValidationRedirect"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ActionRestricted"
          },
          "404": {
            "$ref": "#/components/responses/PersonNotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/notes/categories": {
      "get": {
        "operationId": "listNoteCategories",
        "summary": "List note categories",
        "description": "Returns every note category available in the current context as a **bare JSON array** — this endpoint does not use the pagination envelope, and it ignores query parameters such as `$top`.\n\nA category only appears here once it has been opted in to the current context's committee through the Committees picker on its detail page in the VAN UI; being listed on the Note Categories page is not enough. The sandbox committee has none opted in, so only the empty array has been observed live.\n\nOnly a category whose `assignableTypes` contain `Person` can be used on a person note; sending any other id to `POST /people/{vanId}/notes` returns 400. See `GET /notes/categoryTypes` for the full vocabulary of `assignableTypes`.",
        "tags": [
          "Notes"
        ],
        "x-keywords": [
          "note categories",
          "list categories",
          "category ids"
        ],
        "x-task": "List the note categories this committee has",
        "responses": {
          "200": {
            "description": "All note categories in the context, as a bare array.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/NoteCategory"
                  }
                },
                "examples": {
                  "populated": {
                    "summary": "Two categories",
                    "x-provenance": {
                      "source": "docs",
                      "note": "From the official docs; the item shape has not been observed live."
                    },
                    "value": [
                      {
                        "assignableTypes": [
                          "Event"
                        ],
                        "noteCategoryId": 24,
                        "name": "Event Details"
                      },
                      {
                        "assignableTypes": [
                          "Event",
                          "Organization"
                        ],
                        "noteCategoryId": 23,
                        "name": "Venue Directions"
                      }
                    ]
                  },
                  "empty": {
                    "summary": "No categories opted in (sandbox)",
                    "value": []
                  },
                  "note-categories-are-a-bare-array/1": {
                    "summary": "No envelope: the body itself is the array.",
                    "description": "The list is a bare JSON array, not the pagination envelope, and query parameters like `$top` are ignored rather than applied or rejected. The sandbox committee has no categories opted in, so the empty array is all it can answer.",
                    "x-transcript": "note-categories-are-a-bare-array",
                    "value": []
                  },
                  "note-categories-are-a-bare-array/2": {
                    "summary": "Paging parameters are accepted and ignored — the response is identical.",
                    "description": "The list is a bare JSON array, not the pagination envelope, and query parameters like `$top` are ignored rather than applied or rejected. The sandbox committee has no categories opted in, so the empty array is all it can answer.",
                    "x-transcript": "note-categories-are-a-bare-array",
                    "value": []
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/QueryStringTooLong"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "Note categories come back as a bare array that ignores paging",
            "source": "# The list is a bare JSON array, not the pagination envelope, and query\n# parameters like `$top` are ignored rather than applied or rejected. The\n# sandbox committee has no categories opted in, so the empty array is all it\n# can answer.\n\n# No envelope: the body itself is the array.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/notes/categories' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 200\n# []\n\n# Paging parameters are accepted and ignored — the response is identical.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/notes/categories?%24top=1&%24skip=5' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 200\n# []",
            "x-transcript": "note-categories-are-a-bare-array"
          }
        ]
      }
    },
    "/notes/categories/{noteCategoryId}": {
      "get": {
        "operationId": "getNoteCategory",
        "summary": "Get a note category",
        "description": "Returns a single note category as a bare object, in the same shape as the items of `GET /notes/categories`.\n\nUnlike the list endpoint, this one is not filtered by the committee opt-in: it addresses a category by id directly. The sandbox committee has no categories at all, so every id probed answered 404 and the populated shape has still not been observed live.\n\nOnly ids in the int32 range route here. An id of `0` or a negative id reaches the handler and 500s; anything above 2147483647 or non-numeric matches no route and gets an IIS HTML 404.",
        "x-provenance": {
          "source": "docs, sandbox probe",
          "lastProbed": "2026-08-08",
          "note": "Route confirmed live: ids 1, 10, 999999999 and 2147483647 all returned the JSON 404 envelope (not the 403 the restricted note actions give, and not the IIS 404 an unrouted path gives), so the sandbox key is permitted this action — the committee simply has no categories. Ids 0 and -1 returned 500 INTERNAL_SERVER_ERROR with a referenceCode. The 200 shape is from https://docs.ngpvan.com/reference/notescategoriesnotecategoryid."
        },
        "tags": [
          "Notes"
        ],
        "x-keywords": [
          "note category",
          "category by id"
        ],
        "x-task": "Look up one note category by id",
        "parameters": [
          {
            "name": "noteCategoryId",
            "in": "path",
            "required": true,
            "description": "Id of the note category, as returned by GET /notes/categories.",
            "schema": {
              "type": "integer",
              "format": "int32",
              "minimum": 1
            },
            "example": 10
          }
        ],
        "responses": {
          "200": {
            "description": "The note category, as a bare object.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NoteCategory"
                },
                "examples": {
                  "ask": {
                    "summary": "A category assignable to organizations and people",
                    "x-provenance": {
                      "source": "docs",
                      "note": "From the official docs; not observed live — the sandbox committee has no note categories."
                    },
                    "value": {
                      "assignableTypes": [
                        "Organization",
                        "Person"
                      ],
                      "noteCategoryId": 10,
                      "name": "Ask"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NoteCategoryNotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "An unknown category 404s with the envelope; a non-int32 id gets HTML",
            "source": "# Only ids in the int32 range route to the handler, which answers the\n# standard 404 envelope for a category that does not exist. An id above\n# 2147483647 matches no route at all and gets IIS's HTML 404 page instead —\n# a different content type, not just a different body.\n\n# A well-formed id that names no category — this committee has none at all.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/notes/categories/10' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 404\n# {\n#   \"errors\": [\n#     {\n#       \"code\": \"NOT_FOUND\",\n#       \"text\": \"The specified resource cannot be found.\"\n#     }\n#   ]\n# }\n\n# One past int32: the route no longer matches, and IIS answers with an HTML\n# page.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/notes/categories/2147483648' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 404\n# <!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Strict//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd\">\r\n<html xmlns=\"http://www.w3.org/1999/xhtml\">\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=iso-8859-1\"/>\r\n<title>404 - File or directory not found.</title>\r\n<style type=\"text/css\">\r\n<!--\r\nbody{margin:0;font-size:.7em;font-family:Verdana, Arial, Helvetica, sans-serif;background:#EEEEEE;}\r\nfieldset{padding:0 15px 10px 15px;} \r\nh1{font-size:2.4em;margin:0;color:#FFF;}\r\nh2{font-size:1.7em;margin:0;color:#CC0000;} \r\nh3{font-size:1.2em;margin:10px 0 0 0;color:#000000;} \r\n#header{width:96%;margin:0 0 0 0;padding:6px 2% 6px 2%;font-family:\"trebuchet MS\", Verdana, sans-serif;color:#FFF;\r\nbackground-color:#555555;}\r\n#content{margin:0 0 0 2%;position:relative;}\r\n.content-container{background:#FFF;width:96%;margin-top:8px;padding:10px;position:relative;}\r\n-->\r\n</style>\r\n</head>\r\n<body>\r\n<div id=\"header\"><h1>Server Error</h1></div>\r\n<div id=\"content\">\r\n <div class=\"content-container\"><fieldset>\r\n  <h2>404 - File or directory not found.</h2>\r\n  <h3>The resource you are looking for might have been removed, had its name changed, or is temporarily unavailable.</h3>\r\n </fieldset></div>\r\n</div>\r\n</body>\r\n</html>\r\n",
            "x-transcript": "note-category-404s-come-in-two-shapes"
          }
        ]
      }
    },
    "/notes/categoryTypes": {
      "get": {
        "operationId": "listNoteCategoryTypes",
        "summary": "List note category types",
        "description": "Returns the entity types a note category can be assigned to — the vocabulary of `NoteCategory.assignableTypes` — as a **bare JSON array of strings**, with no pagination envelope.\n\nThe official docs state that \"in almost all cases\" the available types are `Event`, `Location`, `Person` and `Organization`, and give `[\"Person\", \"Organization\", \"Event\", \"Location\"]` as the example response. They are singular and PascalCase. Because a context can in principle expose a different set, this endpoint is the authoritative list for a given context and the schema below does not close the set with an `enum`.\n\n**This action is restricted for the key used to research this spec.** Every request returns 403 FORBIDDEN \"Access to this action is restricted\", so the live response has never been observed — the 200 below comes from the official docs.",
        "x-provenance": {
          "source": "docs, sandbox probe",
          "lastProbed": "2026-08-08",
          "note": "The route exists: it answers 403, not the IIS HTML 404 an unrouted path such as /notes/types gives. Both /notes/categoryTypes and /notes/categorytypes 403, with and without query parameters. The 200 response and the four type names are from https://docs.ngpvan.com/reference/notescategorytypes."
        },
        "tags": [
          "Notes"
        ],
        "x-keywords": [
          "note category types",
          "assignable types"
        ],
        "x-task": "List the note category types",
        "responses": {
          "200": {
            "description": "All note category types available in the context, as a bare array of strings.",
            "x-provenance": {
              "source": "docs",
              "note": "From the official docs; not observed live — the sandbox key gets 403 for this action."
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/NoteCategoryType"
                  }
                },
                "examples": {
                  "typical": {
                    "summary": "The usual four types",
                    "value": [
                      "Person",
                      "Organization",
                      "Event",
                      "Location"
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ActionRestricted"
          },
          "404": {
            "$ref": "#/components/responses/QueryStringTooLong"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/surveyQuestions": {
      "get": {
        "operationId": "listSurveyQuestions",
        "summary": "List survey questions",
        "description": "Returns the context's survey questions, each with its canned responses, in the standard pagination envelope. Every filter is optional; with none set, Active questions are returned. The sandbox committee has no survey questions, so only the empty page has been observed live.",
        "tags": [
          "Survey Questions"
        ],
        "x-keywords": [
          "survey questions",
          "questions",
          "canvass questions",
          "script questions",
          "responses"
        ],
        "x-task": "List survey questions",
        "parameters": [
          {
            "name": "statuses",
            "in": "query",
            "description": "Statuses to include, comma-delimited. Defaults to Active.",
            "style": "form",
            "explode": false,
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/SurveyQuestionStatus"
              }
            },
            "example": [
              "Active",
              "Archived"
            ]
          },
          {
            "name": "name",
            "in": "query",
            "description": "Filters to survey questions whose name starts with the given input.",
            "schema": {
              "type": "string"
            },
            "example": "Gun Control"
          },
          {
            "name": "type",
            "in": "query",
            "description": "Filters to survey questions of the given type.",
            "schema": {
              "type": "string"
            },
            "example": "GOTV"
          },
          {
            "name": "question",
            "in": "query",
            "description": "Filters to survey questions whose script question contains the given input.",
            "schema": {
              "type": "string"
            },
            "example": "Will you vote"
          },
          {
            "name": "cycle",
            "in": "query",
            "description": "A year in the format YYYY.",
            "schema": {
              "type": "integer",
              "format": "int32",
              "minimum": 1900,
              "maximum": 2100
            },
            "example": 2026
          },
          {
            "name": "$top",
            "in": "query",
            "description": "Limits the number of results. Default 50, maximum 200.",
            "x-docs-discrepancy": "Official docs claim a default of 40; the API's own INVALID_PARAMETER hint (observed 2026-08-03) states default 50, maximum 200.",
            "schema": {
              "type": "integer",
              "format": "int32",
              "minimum": 1,
              "maximum": 200
            },
            "example": 50
          }
        ],
        "responses": {
          "200": {
            "description": "A paginated list of survey questions.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SurveyQuestionList"
                },
                "examples": {
                  "empty": {
                    "summary": "Empty list",
                    "value": {
                      "items": [],
                      "nextPageLink": null,
                      "count": 0
                    }
                  },
                  "populated": {
                    "summary": "Populated list",
                    "x-provenance": {
                      "note": "Constructed from official docs; item shape not yet observed live."
                    },
                    "value": {
                      "items": [
                        {
                          "surveyQuestionId": 1204,
                          "type": "GOTV",
                          "cycle": 2026,
                          "name": "Will Vote 2026",
                          "mediumName": "WillVote26",
                          "shortName": "WV26",
                          "scriptQuestion": "Can we count on you to vote in the 2026 general election?",
                          "status": "Active",
                          "responses": [
                            {
                              "surveyResponseId": 1,
                              "name": "Yes",
                              "mediumName": "Yes",
                              "shortName": "Y"
                            },
                            {
                              "surveyResponseId": 2,
                              "name": "No",
                              "mediumName": "No",
                              "shortName": "N"
                            }
                          ]
                        }
                      ],
                      "nextPageLink": null,
                      "count": 1
                    }
                  },
                  "survey-questions-list-is-an-empty-page-here": {
                    "summary": "The list arrives in the pagination envelope — empty in this committee",
                    "description": "Survey questions come back in the standard `{items, count, nextPageLink}` envelope. The sandbox committee has no survey questions (and none can be created — every `type` is rejected), so the empty page is the only response this database can produce.",
                    "x-transcript": "survey-questions-list-is-an-empty-page-here",
                    "value": {
                      "items": [],
                      "nextPageLink": null,
                      "count": 0
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/QueryStringTooLong"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "The list arrives in the pagination envelope — empty in this committee",
            "source": "# Survey questions come back in the standard `{items, count, nextPageLink}`\n# envelope. The sandbox committee has no survey questions (and none can be\n# created — every `type` is rejected), so the empty page is the only\n# response this database can produce.\n\n# No filters: the default is Active questions, of which this committee has\n# none.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/surveyQuestions' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 200\n# {\n#   \"items\": [],\n#   \"nextPageLink\": null,\n#   \"count\": 0\n# }",
            "x-transcript": "survey-questions-list-is-an-empty-page-here"
          },
          {
            "lang": "Shell",
            "label": "$top is bounded 1–200, and the API's own hint says so",
            "source": "# A `$top` outside 1–200 is refused with INVALID_PARAMETER, and the refusal\n# states the real bounds — maximum 200 in the text, default 50 in the hint —\n# contradicting the official docs' claimed default of 40.\n\n# One over the maximum. The refusal itself is where the true bounds come\n# from.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/surveyQuestions?%24top=201' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 400\n# {\n#   \"errors\": [\n#     {\n#       \"code\": \"INVALID_PARAMETER\",\n#       \"text\": \"'$top' must be less than or equal to the maximum result size for this end point: 200\",\n#       \"properties\": [\n#         \"$top\"\n#       ],\n#       \"hint\": \"If no '$top' parameter is specified, a default top size of 50 will be used.\"\n#     }\n#   ]\n# }\n\n# Zero is out of range on the other side.\n\ncurl -sS -X GET 'https://api.securevan.com/v4/surveyQuestions?%24top=0' \\\n  -u \"app-name:$NGP_API_KEY|1\"\n# → 400\n# {\n#   \"errors\": [\n#     {\n#       \"code\": \"INVALID_PARAMETER\",\n#       \"text\": \"'$top' must be greater than '0'.\",\n#       \"properties\": [\n#         \"$top\"\n#       ]\n#     }\n#   ]\n# }",
            "x-transcript": "survey-questions-top-bounds-come-from-the-api"
          }
        ]
      }
    },
    "/echoes": {
      "post": {
        "operationId": "createEcho",
        "summary": "Echo a message back",
        "description": "Test endpoint: echoes the posted message back with a server timestamp. Safe to call freely; useful for verifying auth and connectivity. Accepts an empty body (all fields nullable).",
        "tags": [
          "Echoes"
        ],
        "x-keywords": [
          "echo",
          "ping",
          "health check",
          "connectivity",
          "test credentials",
          "verify api key",
          "smoke test"
        ],
        "x-task": "Check that credentials work",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EchoRequest"
              },
              "examples": {
                "hello": {
                  "summary": "Simple echo",
                  "value": {
                    "message": "hello"
                  }
                },
                "empty": {
                  "summary": "Empty body (accepted; everything is nullable)",
                  "value": {}
                },
                "delayed": {
                  "summary": "Ask the server to wait before responding",
                  "value": {
                    "message": "slow reply",
                    "delayInMilliseconds": 500
                  }
                },
                "echo-round-trips-the-message/1": {
                  "summary": "The cheapest possible proof that the base URL, auth header and mode are right.",
                  "description": "The posted message is echoed back exactly, alongside `dateSent`, the server's own clock. Every request field is optional — an empty body is a valid connectivity check and comes back with `message: null`.",
                  "x-transcript": "echo-round-trips-the-message",
                  "value": {
                    "message": "Anybody out there?"
                  }
                },
                "echo-round-trips-the-message/2": {
                  "summary": "No field is required. An empty body echoes back a null message.",
                  "description": "The posted message is echoed back exactly, alongside `dateSent`, the server's own clock. Every request field is optional — an empty body is a valid connectivity check and comes back with `message: null`.",
                  "x-transcript": "echo-round-trips-the-message",
                  "value": {}
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The echoed message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Echo"
                },
                "examples": {
                  "hello": {
                    "summary": "Echoed message (sandbox)",
                    "value": {
                      "message": "hello",
                      "dateSent": "2026-08-03T16:47:29.8973257Z",
                      "delayInMilliseconds": null
                    }
                  },
                  "echo-round-trips-the-message/1": {
                    "summary": "The cheapest possible proof that the base URL, auth header and mode are right.",
                    "description": "The posted message is echoed back exactly, alongside `dateSent`, the server's own clock. Every request field is optional — an empty body is a valid connectivity check and comes back with `message: null`.",
                    "x-transcript": "echo-round-trips-the-message",
                    "value": {
                      "message": "Anybody out there?",
                      "dateSent": "2026-01-01T00:00:00Z",
                      "delayInMilliseconds": null
                    }
                  },
                  "echo-round-trips-the-message/2": {
                    "summary": "No field is required. An empty body echoes back a null message.",
                    "description": "The posted message is echoed back exactly, alongside `dateSent`, the server's own clock. Every request field is optional — an empty body is a valid connectivity check and comes back with `message: null`.",
                    "x-transcript": "echo-round-trips-the-message",
                    "value": {
                      "message": null,
                      "dateSent": "2026-01-01T00:00:00Z",
                      "delayInMilliseconds": null
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "The message comes back verbatim, stamped with server time",
            "source": "# The posted message is echoed back exactly, alongside `dateSent`, the\n# server's own clock. Every request field is optional — an empty body is a\n# valid connectivity check and comes back with `message: null`.\n\n# The cheapest possible proof that the base URL, auth header and mode are\n# right.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/echoes' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"message\": \"Anybody out there?\"\n  }'\n# → 200\n# {\n#   \"message\": \"Anybody out there?\",\n#   \"dateSent\": \"2026-01-01T00:00:00Z\",\n#   \"delayInMilliseconds\": null\n# }\n\n# No field is required. An empty body echoes back a null message.\n\ncurl -sS -X POST 'https://api.securevan.com/v4/echoes' \\\n  -u \"app-name:$NGP_API_KEY|1\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{}\n  {}'\n# → 200\n# {\n#   \"message\": null,\n#   \"dateSent\": \"2026-01-01T00:00:00Z\",\n#   \"delayInMilliseconds\": null\n# }",
            "x-transcript": "echo-round-trips-the-message"
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "basicAuth": {
        "type": "http",
        "scheme": "basic",
        "description": "HTTP Basic auth. Username = an arbitrary label, e.g. `my_fancy_app`; password = `{apiKey}|{databaseMode}` where databaseMode is `0` (My Voters) or `1` (My Campaign) and apiKey is a UUID like `07540886-b749-433c-b18d-a3d052f6b759`. Using a mode your key lacks returns 401 UNAUTHORIZED \"Invalid Database Mode\"."
      }
    },
    "headers": {
      "MatchedPersonLocation": {
        "description": "URL of the person the request resolved to.",
        "schema": {
          "type": "string",
          "format": "uri"
        },
        "example": "https://api.securevan.com/v4/people/102714507"
      }
    },
    "responses": {
      "Forbidden": {
        "description": "The request was valid but the key's context does not allow it. Observed on GET /people/{vanId} with `$expand=scores`: scores are a My Voters feature, so a My Campaign key is refused even though `scores` is in the API's own list of valid sections. The sibling refusal for `pollingLocation` uses 400 BAD_REQUEST instead — the two are not consistent.",
        "x-provenance": {
          "lastProbed": "2026-08-04",
          "note": "Surfaced by the fuzzer once $expand was modelled as an enum of the API's 23 valid sections; each section was then requested in turn against vanId 102714507, and scores was the only 403 (pollingLocation the only 400)."
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "forbiddenSection": {
                "summary": "$expand=scores from a My Campaign key",
                "value": {
                  "errors": [
                    {
                      "code": "FORBIDDEN",
                      "text": "May not request 'scores'"
                    }
                  ]
                }
              }
            }
          }
        }
      },
      "ActionRestricted": {
        "description": "The API key's profile does not permit this action at all. The body carries nothing beyond the code, and the check runs before the target is looked up, so a restricted action answers 403 even for an id that does not exist — which also means a 403 here says nothing about whether the target exists.\n\nDistinct from the other 403 in this spec: that one refuses a particular *section* of an otherwise-allowed request (`$expand=scores` from a My Campaign key), while this one refuses the whole operation.",
        "x-provenance": {
          "source": "sandbox probe",
          "lastProbed": "2026-08-04",
          "note": "Observed on GET, PUT and DELETE of /people/{vanId}/notes/{noteId} and on DELETE /people/{vanId} with the research key, while GET and POST of /people/{vanId}/notes work normally. Whether any key in the sandbox committee is granted these actions is unknown, so the success paths behind this response are unverified."
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "restricted": {
                "summary": "PUT /people/102714507/notes/184579",
                "value": {
                  "errors": [
                    {
                      "code": "FORBIDDEN",
                      "text": "Access to this action is restricted"
                    }
                  ]
                }
              }
            }
          }
        }
      },
      "QueryStringTooLong": {
        "description": "The request never reached the API. IIS rejects any request whose query string runs past roughly 2048 characters and answers with its own HTML \"404 - File or directory not found\" page, so this 404 means the URL was too long rather than that anything was missing. Nothing in the body identifies the real cause; check the content type, since the API's own 404s are JSON.",
        "x-provenance": {
          "lastProbed": "2026-08-04",
          "note": "Found by the fuzzer on GET /surveyQuestions with a very long generated filter value, then bisected with `statuses=AAA…`: 2000 characters still reach the API (which answers 500), 2100 return the IIS 404. Reproduced on GET /people with a long lastName, so this is infrastructure-wide rather than endpoint-specific."
        },
        "content": {
          "text/html": {
            "schema": {
              "type": "string"
            }
          }
        }
      },
      "NoteCategoryNotFound": {
        "description": "No note category with that id exists in the current context, as the standard error envelope. A non-integer path segment, or an id above 2147483647, matches no route at all and gets an IIS HTML page instead; an id of zero or below does reach the handler and answers 500 rather than 404.",
        "x-provenance": {
          "source": "sandbox probe",
          "lastProbed": "2026-08-08",
          "note": "GET /notes/categories/{1,10,999999999,2147483647} all returned this envelope; /notes/categories/abc and /notes/categories/2147483648 returned the IIS HTML 404."
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "notFound": {
                "summary": "Unknown noteCategoryId",
                "value": {
                  "errors": [
                    {
                      "code": "NOT_FOUND",
                      "text": "The specified resource cannot be found."
                    }
                  ]
                }
              }
            }
          },
          "text/html": {
            "schema": {
              "type": "string"
            },
            "x-provenance": {
              "lastProbed": "2026-08-08",
              "note": "IIS \"404 - File or directory not found\" page, served when the path segment is not an int32 so no API route matches."
            }
          }
        }
      },
      "PersonNotFound": {
        "description": "No person with that vanId exists. Zero and negative ids return this too, as the standard error envelope. Two non-API cases share this status and answer with an IIS HTML page instead: a non-integer path segment, which matches no route, and a query string longer than ~2048 characters, which IIS rejects outright.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "notFound": {
                "summary": "Unknown vanId",
                "value": {
                  "errors": [
                    {
                      "code": "NOT_FOUND",
                      "text": "The specified resource cannot be found."
                    }
                  ]
                }
              }
            }
          },
          "text/html": {
            "schema": {
              "type": "string"
            },
            "x-provenance": {
              "lastProbed": "2026-08-03",
              "note": "IIS \"404 - File or directory not found\" page, served when the path segment is not an integer so no API route matches."
            }
          }
        }
      },
      "RequestValidationRedirect": {
        "description": "The request never reached the API. ASP.NET request validation rejects a path segment containing `<`, `>`, `*` or `&` and hands the request to the VAN web application, which answers **302** with `Location: /Error.aspx?EID={code}` and a small HTML \"Object moved\" body. Clients that follow the redirect land on the web app's HTML \"Oops...something went wrong\" page with status 200 — HTML, not JSON, from an endpoint that otherwise only speaks JSON.\n\nOther unusual path characters take different routes: `:` and `\"` give the IIS HTML 404, and a backslash gives the standard JSON 404 envelope.",
        "x-provenance": {
          "lastProbed": "2026-08-03",
          "note": "Found by the stateful fuzz phase on GET /people/{vanId} and reproduced character by character. The EID in the Location is a support reference code; no request data is echoed back."
        },
        "headers": {
          "Location": {
            "description": "The web application's error page, e.g. /Error.aspx?EID=26B226-343EF8",
            "schema": {
              "type": "string"
            },
            "example": "/Error.aspx?EID=26B226-343EF8"
          }
        },
        "content": {
          "text/html": {
            "schema": {
              "type": "string"
            },
            "examples": {
              "objectMoved": {
                "summary": "Redirect body",
                "value": "<html><head><title>Object moved</title></head><body>\n<h2>Object moved to <a href=\"/Error.aspx?EID=26B226-343EF8\">here</a>.</h2>\n</body></html>\n"
              }
            }
          }
        }
      },
      "BadRequest": {
        "description": "Validation error, as the standard JSON envelope.\n\nTwo unrelated cases share this status and answer with `text/html` instead, because the request is rejected in front of the API and never reaches it: a percent-encoded control character such as `%7F` in the path gets IIS's \"Bad Request - Invalid URL\" page, and `%00` gets Cloudflare's \"400 Bad Request\" page. Check the content type before parsing.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "invalidParameter": {
                "summary": "$top over the maximum on /surveyQuestions",
                "value": {
                  "errors": [
                    {
                      "code": "INVALID_PARAMETER",
                      "text": "'$top' must be less than or equal to the maximum result size for this end point: 200",
                      "properties": [
                        "$top"
                      ],
                      "hint": "If no '$top' parameter is specified, a default top size of 50 will be used."
                    }
                  ]
                }
              }
            }
          },
          "text/html": {
            "schema": {
              "type": "string"
            },
            "x-provenance": {
              "source": "sandbox probe",
              "lastProbed": "2026-08-04",
              "note": "Found by the fuzzer's coverage phase on POST /people/{vanId}/notes with a generated path segment containing %7F, then reproduced character by character and confirmed to be path-position independent: %7F on GET /people/{vanId} and on /people/{vanId}/notes both give the IIS page (`charset=us-ascii`, 324 bytes), %00 gives Cloudflare's, and %25 takes the separate request-validation 302 route instead. Not notes-specific — it applies to every operation."
            },
            "examples": {
              "invalidUrl": {
                "summary": "IIS: control character in the path (%7F)",
                "value": "<!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.01//EN\"\"http://www.w3.org/TR/html4/strict.dtd\">\n<HTML><HEAD><TITLE>Bad Request</TITLE>\n<META HTTP-EQUIV=\"Content-Type\" Content=\"text/html; charset=us-ascii\"></HEAD>\n<BODY><h2>Bad Request - Invalid URL</h2>\n<hr><p>HTTP Error 400. The request URL is invalid.</p>\n</BODY></HTML>\n"
              },
              "cloudflare": {
                "summary": "Cloudflare: null byte in the path (%00)",
                "value": "<html>\n<head><title>400 Bad Request</title></head>\n<body>\n<center><h1>400 Bad Request</h1></center>\n<hr><center>cloudflare</center>\n</body>\n</html>\n"
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing/invalid API key, or a database mode the key does not have access to.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "wrongMode": {
                "summary": "Database mode the key lacks",
                "value": {
                  "errors": [
                    {
                      "code": "UNAUTHORIZED",
                      "text": "Invalid Database Mode"
                    }
                  ]
                }
              }
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "Rate limit exceeded. Limits are per API key, set by the key's rate-limit profile, and apply across all endpoints, so any operation can return 429. There is no `Retry-After` header; the suggested wait appears only in the error text (\"Try again in N ms.\"). Unlike other errors, `code` is the numeric string \"429\" rather than a symbolic name.",
        "x-docs-discrepancy": "The official docs do not mention rate limiting or the 429 response anywhere in their reference index (checked 2026-08-04). Observed live on GET /surveyQuestions and POST /people/create.",
        "x-provenance": {
          "source": "sandbox probe",
          "lastProbed": "2026-08-04",
          "note": "Triggered with ~300 concurrent GET /surveyQuestions requests; 225 returned 429. None of them carried a Retry-After header — the retry hint is only in the error text, with the millisecond count varying per response."
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "rateLimited": {
                "summary": "Per-key rate limit exceeded",
                "value": {
                  "errors": [
                    {
                      "code": "429",
                      "text": "Rate limit exceeded. Try again in 30 ms."
                    }
                  ]
                }
              }
            }
          }
        }
      },
      "ServerError": {
        "description": "Internal server error. The API returns 500 (not 400) for various malformed inputs, e.g. negative delayInMilliseconds on /echoes, non-ASCII filter values on /surveyQuestions, vanId 0 or null phone entries on /people/find, a null phone entry on the person write endpoints, an `identifiers` entry with the valid type `dwid` on POST /people/create, and a negative vanId — in the path or the body — or a secondary equal to the primary on PUT /people/{vanId}/mergeInto. Two body shapes occur: the standard errors envelope (with a referenceCode for support), or a raw ASP.NET exception payload including a stack trace when the request fails before reaching the API's own error handling (e.g. a query-string key containing '[').",
        "content": {
          "application/json": {
            "schema": {
              "description": "The two shapes are disjoint: the standard envelope requires `errors`, the ASP.NET payload requires `message`, and neither carries the other's fields.",
              "oneOf": [
                {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                {
                  "$ref": "#/components/schemas/AspNetError"
                }
              ]
            },
            "examples": {
              "internal": {
                "summary": "Malformed input",
                "value": {
                  "errors": [
                    {
                      "code": "INTERNAL_SERVER_ERROR",
                      "text": "An unknown error occurred",
                      "referenceCode": "48E6AB-938498"
                    }
                  ]
                }
              },
              "aspNet": {
                "summary": "Raw ASP.NET exception (query-string key containing '[')",
                "description": "Returned when the request fails before reaching the API's own error handling. `stackTrace` is abridged here; the live response leaks the full trace, including build-server paths.",
                "value": {
                  "message": "An error has occurred.",
                  "exceptionMessage": "The key is invalid JQuery syntax because it is missing a closing bracket\r\nParameter name: key",
                  "exceptionType": "System.ArgumentException",
                  "stackTrace": "   at System.Web.Http.ModelBinding.FormDataCollectionExtensions.NormalizeJQueryToMvc(String key)\r\n   at System.Web.Http.ModelBinding.FormDataCollectionExtensions.<GetJQueryNameValuePairs>d__1.MoveNext()\r\n   at System.Linq.Buffer`1..ctor(IEnumerable`1 source)\r\n   at System.Linq.Enumerable.ToArray[TSource](IEnumerable`1 source)\r\n   at System.Net.Http.HttpRequestMessageExtensions.GetQueryNameValuePairs(HttpRequestMessage request)\r\n   at VAN.Web.Api.Infrastructure.TranslatorHandler.GetTranslationResource(HttpRequestMessage request) in D:\\BuildAgent\\work\\72169567f13f28bb\\Source\\Web.Api\\Infrastructure\\TranslatorHandler.cs:line 158\r\n   at VAN.Web.Api.Infrastructure.TranslatorHandler.<SendAsync>d__10.MoveNext() in D:\\BuildAgent\\work\\72169567f13f28bb\\Source\\Web.Api\\Infrastructure\\TranslatorHandler.cs:line 85\r\n   ... (stack trace abridged; the live response returns ~5.7 KB of frames)"
                }
              }
            },
            "x-provenance": {
              "source": "sandbox probe",
              "lastProbed": "2026-08-04",
              "note": "The aspNet example is a verbatim sandbox response to GET /people/102714507?a[=1, with the stack trace truncated after the frames that identify the crash. The internal example is from earlier probing of the malformed inputs listed above."
            }
          }
        }
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "description": "The standard error envelope, returned by every failing endpoint except where noted.",
        "required": [
          "errors"
        ],
        "properties": {
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "description": "One problem with the request.",
        "required": [
          "code",
          "text"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "Machine-readable error code. Known values: UNAUTHORIZED, FORBIDDEN, INVALID_PARAMETER, BAD_REQUEST, NOT_FOUND, METHOD_NOT_ALLOWED, INTERNAL_SERVER_ERROR (list likely incomplete).",
            "examples": [
              "INVALID_PARAMETER"
            ]
          },
          "text": {
            "type": "string",
            "description": "Human-readable description of the problem."
          },
          "properties": {
            "type": [
              "array",
              "null"
            ],
            "description": "JSON paths of the offending request properties, e.g. \"responses[0].shortName\".",
            "items": {
              "type": "string"
            }
          },
          "hint": {
            "type": [
              "string",
              "null"
            ],
            "description": "How to fix it — often the accepted values or a regular expression."
          },
          "referenceCode": {
            "type": [
              "string",
              "null"
            ],
            "description": "Support reference code; present on INTERNAL_SERVER_ERROR responses."
          }
        }
      },
      "AspNetError": {
        "type": "object",
        "description": "Raw ASP.NET Web API exception payload, returned on some 500s instead of the standard errors envelope when the request fails before reaching the API's own error handling — e.g. a query-string key containing '[' crashes jQuery-syntax key parsing. Includes a full stack trace.",
        "x-provenance": {
          "lastProbed": "2026-08-03",
          "note": "Found by the stateful fuzz phase on GET /people/{vanId} with a fuzzed query-string key containing '['. The stack-trace disclosure is itself a VAN bug, logged in STATUS.md."
        },
        "required": [
          "message"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "e.g. \"An error has occurred.\""
          },
          "exceptionMessage": {
            "type": [
              "string",
              "null"
            ]
          },
          "exceptionType": {
            "type": [
              "string",
              "null"
            ],
            "description": "e.g. \"System.ArgumentException\""
          },
          "stackTrace": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "EchoRequest": {
        "type": "object",
        "description": "A message to send to the echo endpoint. Every field is optional.",
        "properties": {
          "message": {
            "type": [
              "string",
              "null"
            ],
            "description": "Text to echo back verbatim."
          },
          "delayInMilliseconds": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1,
            "maximum": 2000,
            "description": "Optional server-side delay before responding, in milliseconds. Warning: -1 hangs the connection indefinitely; other negative values return 500.",
            "x-provenance": {
              "note": "The -1 hang is likely the value being passed straight to .NET as Timeout.Infinite. Spec minimum is 1 so fuzzer boundary probes send 0 (safe) rather than -1."
            }
          }
        }
      },
      "Echo": {
        "type": "object",
        "description": "The posted message, echoed back with a server timestamp.",
        "required": [
          "message",
          "dateSent"
        ],
        "properties": {
          "message": {
            "type": [
              "string",
              "null"
            ],
            "description": "The message exactly as posted."
          },
          "dateSent": {
            "type": "string",
            "format": "date-time",
            "description": "Server time when the response was produced."
          },
          "delayInMilliseconds": {
            "type": [
              "integer",
              "null"
            ],
            "description": "The delay that was applied, echoed back."
          }
        }
      },
      "PersonMatchCriteria": {
        "type": "object",
        "description": "Match criteria. Every field is optional in the sense that the API never rejects a sparse body — but matching only happens once the criteria reach one of these minimum combinations:\n\n- firstName + lastName + emails[].email\n- firstName + lastName + phones[].phoneNumber\n- firstName + lastName + addresses[].zipOrPostalCode (zip5) + dateOfBirth\n- firstName + lastName + addresses[].addressLine1 (street number **and** street name) + addresses[].zipOrPostalCode (zip5)\n- emails[].email on its own (phones[].phoneNumber on its own also works)\n\nBelow that, the request is answered Unmatched without a search rather than rejected. A valid vanId overrides all other criteria and skips the threshold entirely.",
        "x-provenance": {
          "lastProbed": "2026-08-04",
          "note": "Combination list from the docs' Match Candidate common model, each combination confirmed against sandbox vanId 102719047 (see the x-provenance on POST /people/find for the full matched/unmatched probe list). `addresses` is absent from the docs' find request example but is accepted and is the only way to supply zip5 or a street address as criteria — name + dob + zip matched, name + dob alone did not."
        },
        "properties": {
          "vanId": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1,
            "description": "VAN id of the person; a valid vanId overrides all other criteria and is looked up directly, with no minimum-combination threshold. Warning: the API returns 500 for vanId 0."
          },
          "firstName": {
            "type": [
              "string",
              "null"
            ],
            "description": "Required by every combination except the email-only (or phone-only) one. Compared case- and accent-insensitively, and may match nicknames and variants unless the context has \"Disable Partial Matching\" enabled. A first name that disagrees with the person record turns an otherwise-matching request into Unmatched."
          },
          "middleName": {
            "type": [
              "string",
              "null"
            ],
            "description": "Never part of a minimum combination; only narrows a match that the other criteria already reached."
          },
          "lastName": {
            "type": [
              "string",
              "null"
            ],
            "description": "Required by every combination except the email-only (or phone-only) one. Same comparison rules as firstName."
          },
          "dateOfBirth": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Only reaches the threshold in combination with firstName, lastName and a zip5 in addresses[]. Name + dateOfBirth alone returns Unmatched."
          },
          "emails": {
            "type": [
              "array",
              "null"
            ],
            "description": "Email addresses to match on. The strongest single criterion: an address on its own reaches the threshold, no name required. Compared case-insensitively.",
            "items": {
              "$ref": "#/components/schemas/PersonMatchEmail"
            }
          },
          "phones": {
            "type": [
              "array",
              "null"
            ],
            "description": "Phone numbers to match on. Reaches the threshold with firstName + lastName, and — undocumented but observed — on its own as well. Punctuation is ignored: \"907-555-4242\" matches a stored \"9075554242\". A null array entry returns 500.",
            "x-docs-discrepancy": "The docs list only an email address as a criterion sufficient on its own; a phone number alone also matched (observed 2026-08-04, sandbox vanId 102719047).",
            "items": {
              "$ref": "#/components/schemas/PersonMatchPhone"
            }
          },
          "addresses": {
            "type": [
              "array",
              "null"
            ],
            "description": "Addresses to match on — the only way to supply the zip5 that two of the minimum combinations require. Never sufficient on its own, and never with a name alone: firstName + lastName + zipOrPostalCode returns Unmatched unless a dateOfBirth or a street address comes with it. A null entry in this array is tolerated (404 Unmatched, not 500).",
            "items": {
              "$ref": "#/components/schemas/PersonMatchAddress"
            }
          }
        }
      },
      "PersonMatchAddress": {
        "type": "object",
        "description": "An address used as match criteria — the fields the matcher reads, unlike the fuller PersonAddressInput used when writing. Only two shapes reach the matching threshold, both alongside firstName and lastName: zipOrPostalCode + dateOfBirth, or addressLine1 + zipOrPostalCode.",
        "x-provenance": {
          "lastProbed": "2026-08-04",
          "note": "Accepted by POST /people/find and confirmed to drive matching against sandbox vanId 102719047 (742 Evergreen Terrace, Springfield AK 99501): name+dob+zip and name+addressLine1+zip both matched; name+zip alone, name+\"Evergreen Terrace\" (no street number)+zip, and name+addressLine1+wrong zip all returned Unmatched. Only these fields were probed as criteria; the write model's other fields (addressLine2/3, type, …) are accepted but were not observed to affect the outcome."
        },
        "properties": {
          "addressLine1": {
            "type": [
              "string",
              "null"
            ],
            "description": "Street address. Must carry both the street **number** and the street name to count toward a match: \"742 Evergreen Terrace\" matched, \"Evergreen Terrace\" did not."
          },
          "city": {
            "type": [
              "string",
              "null"
            ],
            "description": "City or town. Not part of any minimum combination."
          },
          "stateOrProvince": {
            "type": [
              "string",
              "null"
            ],
            "description": "Two or three character state or province code, e.g. \"MN\", \"ON\", \"NSW\". Not part of any minimum combination."
          },
          "zipOrPostalCode": {
            "type": [
              "string",
              "null"
            ],
            "description": "The zip5 that the date-of-birth and street-address combinations both require. Must agree with the person record — a right street with a wrong zip does not match."
          },
          "countryCode": {
            "type": [
              "string",
              "null"
            ],
            "description": "Two character ISO country code supported by the VAN context. Defaults to the context's country."
          }
        }
      },
      "PersonMatchEmail": {
        "type": "object",
        "description": "An email address used as match criteria — the address only, unlike the fuller PersonEmailInput used when writing.",
        "properties": {
          "email": {
            "type": "string",
            "format": "email"
          }
        }
      },
      "PersonMatchPhone": {
        "type": "object",
        "description": "A phone number used as match criteria — no type or opt-in fields, unlike the PersonPhoneInput used when writing.",
        "properties": {
          "phoneNumber": {
            "type": "string",
            "description": "Number without country code."
          },
          "dialingPrefix": {
            "type": [
              "string",
              "null"
            ],
            "description": "Numeric country code."
          },
          "countryCode": {
            "type": [
              "string",
              "null"
            ],
            "description": "Alpha-2 country code.",
            "x-docs-discrepancy": "Official docs spell this field 'countyCode' — likely a typo in the docs; not yet verified live."
          }
        }
      },
      "PersonMatched": {
        "type": "object",
        "description": "An existing person was found and nothing was written. The only match-stub shape that accompanies a 302: from find, findOrCreate, create when the body's vanId exists, and update.",
        "required": [
          "vanId",
          "status"
        ],
        "properties": {
          "vanId": {
            "type": "integer"
          },
          "status": {
            "const": "Matched"
          }
        }
      },
      "PersonUnmatched": {
        "type": "object",
        "description": "No person matched and nothing was written — the 404 body from find.",
        "required": [
          "vanId",
          "status"
        ],
        "properties": {
          "vanId": {
            "type": "null"
          },
          "status": {
            "const": "Unmatched"
          }
        }
      },
      "PersonUnmatchedStored": {
        "type": "object",
        "description": "Nothing matched, so a new person record was created — the 201 body from findOrCreate.",
        "required": [
          "vanId",
          "status"
        ],
        "properties": {
          "vanId": {
            "type": "integer"
          },
          "status": {
            "const": "UnmatchedStored"
          }
        }
      },
      "PersonStored": {
        "type": "object",
        "description": "A new person record was created with no attempt to match — the 201 body from create.",
        "required": [
          "vanId",
          "status"
        ],
        "properties": {
          "vanId": {
            "type": "integer"
          },
          "status": {
            "const": "Stored"
          }
        }
      },
      "Page": {
        "type": "object",
        "description": "The envelope every paginated endpoint returns around its `items` array.",
        "required": [
          "count"
        ],
        "properties": {
          "nextPageLink": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Absolute URL of the next page — including an explicit `:443` port — or null on the last page.",
            "examples": [
              "https://api.securevan.com:443/v4/people?lastName=Testperson&$top=1&$skip=1"
            ]
          },
          "count": {
            "type": "integer",
            "description": "Total number of matches across all pages, not the size of this page."
          }
        }
      },
      "NoteList": {
        "description": "A page of notes on a person.",
        "allOf": [
          {
            "$ref": "#/components/schemas/Page"
          },
          {
            "type": "object",
            "required": [
              "items"
            ],
            "properties": {
              "items": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Note"
                }
              }
            }
          }
        ]
      },
      "Note": {
        "type": "object",
        "description": "A free-text note on a person.",
        "required": [
          "noteId"
        ],
        "properties": {
          "noteId": {
            "type": "integer",
            "description": "Unique identifier of the note.",
            "example": 184579
          },
          "text": {
            "type": [
              "string",
              "null"
            ],
            "description": "The body of the note.",
            "example": "Great chat! This person will be able to volunteer next year."
          },
          "isViewRestricted": {
            "type": "boolean",
            "description": "Whether the note is restricted to certain users in the context. Always false in practice: a restricted note is withheld from API keys entirely rather than returned with the flag set."
          },
          "category": {
            "description": "The note's category. An uncategorized note reads as the stub `{\"noteCategoryId\": 0, \"name\": null}` from GET /people/{vanId}/notes, but as null when the same note arrives through `$expand=notes` on the person.",
            "anyOf": [
              {
                "$ref": "#/components/schemas/NoteCategoryRef"
              },
              {
                "type": "null"
              }
            ]
          },
          "createdDate": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the note was created, UTC. Truncated to the minute — the seconds are always 00.",
            "example": "2026-08-04T17:11:00Z"
          },
          "isPinned": {
            "type": "boolean",
            "description": "Whether the note is pinned. Always false: POST accepts an `isPinned` field and ignores it, and nothing else in the API sets it."
          },
          "contactHistory": {
            "type": [
              "object",
              "null"
            ],
            "description": "Always null, including for notes created with a `contactHistory` payload and when the list is requested with `$expand=noteDetails`.",
            "x-provenance": {
              "lastProbed": "2026-08-04",
              "note": "Never observed non-null, so the populated shape is unknown and deliberately left unmodelled."
            }
          }
        }
      },
      "NoteCategoryRef": {
        "type": "object",
        "description": "The category stub returned on a note.",
        "properties": {
          "noteCategoryId": {
            "type": "integer",
            "description": "Category id, or 0 when the note has no category."
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Category name, or null when the note has no category."
          }
        }
      },
      "NoteCategory": {
        "type": "object",
        "description": "A note category available in the current context.",
        "x-provenance": {
          "source": "docs",
          "lastProbed": "2026-08-04",
          "note": "The sandbox committee has no note categories opted in, so only the empty array has been observed; the item shape is from the official docs."
        },
        "properties": {
          "noteCategoryId": {
            "type": "integer",
            "description": "Unique identifier of the category — the value to send as `category.noteCategoryId` when writing a note.",
            "example": 24
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Display name of the category.",
            "example": "Event Details"
          },
          "assignableTypes": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/NoteCategoryType"
            },
            "description": "The note category types this category can be applied to — the entities a note in it can hang off. Values are drawn from `GET /notes/categoryTypes`, which in almost all contexts is `Event`, `Location`, `Person` and `Organization`.\n\nA category can only be used on a person note if this array contains `Person`; sending the id of any other category to `POST /people/{vanId}/notes` returns 400.",
            "example": [
              "Event",
              "Organization"
            ]
          }
        }
      },
      "NoteCategoryType": {
        "type": "string",
        "description": "An entity type a note category can be assigned to. The official docs say that \"in almost all cases\" the available types are `Event`, `Location`, `Person` and `Organization` — singular and PascalCase — but a context can expose a different set, so this is deliberately not an `enum`. `GET /notes/categoryTypes` is the authoritative list for a given context.",
        "x-provenance": {
          "source": "docs",
          "lastProbed": "2026-08-08",
          "note": "From https://docs.ngpvan.com/reference/notescategorytypes, whose example response is [\"Person\", \"Organization\", \"Event\", \"Location\"]. Corroborated by the Notes overview page, which says notes can be applied to People, Events, Locations and Organizations. Not observable live: the sandbox key gets 403 on /notes/categoryTypes and the committee has no categories to read the names off."
        },
        "examples": [
          "Person",
          "Organization",
          "Event",
          "Location"
        ],
        "example": "Person"
      },
      "NoteInput": {
        "type": "object",
        "description": "A note to create on a person.",
        "required": [
          "text"
        ],
        "properties": {
          "text": {
            "type": "string",
            "minLength": 1,
            "maxLength": 7000,
            "description": "The body of the note. Required and non-empty — absent, null and empty all return 400.\n\nThe API's own stated limit is 8000 characters, and 8001 is rejected with 400, but anything from 7001 to 8000 characters returns 500 without saving. 7000 is the longest text that actually works, which is what this schema allows.",
            "x-provenance": {
              "source": "sandbox probe",
              "lastProbed": "2026-08-04",
              "note": "Bisected on POST /people/102714507/notes: 7000 characters → 204, 7001 → 500, 8001 → 400 \"'text' must be between 0 and 8000 characters\". maxLength is set to 7000 rather than the API's 8000 to keep generated requests out of the 500 band."
            },
            "example": "Great chat! This person will be able to volunteer next year."
          },
          "isViewRestricted": {
            "type": "boolean",
            "default": false,
            "description": "Restricts the note to certain users in the context. A note saved with true is accepted (204) but then invisible to API keys — it never comes back from GET /people/{vanId}/notes, so it cannot be read, updated or verified through the API afterwards."
          },
          "category": {
            "$ref": "#/components/schemas/NoteCategoryInput"
          },
          "contactHistory": {
            "$ref": "#/components/schemas/NoteContactHistoryInput"
          },
          "isPinned": {
            "type": "boolean",
            "description": "Accepted and ignored — the created note always reads back `isPinned: false`. Included here only because the API tolerates it.",
            "x-provenance": {
              "source": "sandbox probe",
              "lastProbed": "2026-08-04",
              "note": "POST with isPinned true returned 204 and the note came back isPinned false. Not part of the documented request model."
            }
          }
        }
      },
      "NoteUpdateInput": {
        "type": "object",
        "description": "Changes to apply to an existing note. Only these three fields can be updated.",
        "x-provenance": {
          "source": "docs, van-cli",
          "note": "Not verified live — the research key is refused this action with 403. The official docs mark `text` and `isViewRestricted` as required while van-cli sends whichever of the three the caller supplied; nothing is marked required here because neither claim could be checked."
        },
        "properties": {
          "text": {
            "type": "string",
            "minLength": 1,
            "maxLength": 7000,
            "description": "The new body of the note. The length limits are those of the create endpoint; they have not been checked on update."
          },
          "isViewRestricted": {
            "type": "boolean",
            "description": "Restricts the note to certain users in the context. Setting this to true makes the note invisible to API keys from then on."
          },
          "category": {
            "$ref": "#/components/schemas/NoteCategoryInput"
          }
        }
      },
      "NoteCategoryInput": {
        "type": "object",
        "description": "The category to file a note under.",
        "required": [
          "noteCategoryId"
        ],
        "properties": {
          "noteCategoryId": {
            "type": "integer",
            "format": "int32",
            "minimum": 1,
            "description": "Id of a category from GET /notes/categories whose `assignableTypes` contain `Person`. An id outside that set returns 400 INVALID_PARAMETER. `noteCategoryId: 0` — the value the API itself reports for an uncategorized note — returns 500, so omit `category` entirely instead of sending zero.",
            "example": 24,
            "x-provenance": {
              "source": "sandbox probe",
              "lastProbed": "2026-08-04",
              "note": "0 → 500 INTERNAL_SERVER_ERROR, 99999 → 400 \"'category' (99999) is an invalid Note Category ID for this type of note\". The sandbox committee has no categories opted in, so no accepted value has been observed; `minimum: 1` keeps generated requests out of the 500."
            }
          }
        }
      },
      "NoteContactHistoryInput": {
        "type": "object",
        "description": "A Contact History record to create alongside the note. It does not come back on the note afterwards — the note's own `contactHistory` stays null in every response.",
        "x-docs-discrepancy": "Official docs type all four fields as strings; that is what has been probed and what this schema keeps, but whether integers are also accepted has not been tested (2026-08-04).",
        "properties": {
          "contactTypeId": {
            "type": "string",
            "description": "A Contact Type id from GET /canvassResponses/contactTypes. An id outside that list returns 400. If an `inputTypeId` is also given, the contact type must be available to it.",
            "example": "1"
          },
          "inputTypeId": {
            "type": "string",
            "description": "An Input Type id from GET /canvassResponses/inputTypes. Defaults to 11 (API).",
            "example": "11"
          },
          "dateCanvassed": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp of the contact attempt. Defaults to today.",
            "example": "2026-08-01T00:00:00Z"
          },
          "resultCodeId": {
            "type": "string",
            "description": "A Result Code id from GET /canvassResponses/resultCodes. Defaults to Canvassed. An id outside that list returns 500 rather than the 400 an invalid contactTypeId gets.",
            "x-provenance": {
              "source": "sandbox probe",
              "lastProbed": "2026-08-04",
              "note": "resultCodeId \"99999\" → 500 INTERNAL_SERVER_ERROR; \"14\" (Canvassed) → 204."
            },
            "example": "14"
          }
        }
      },
      "SurveyQuestionList": {
        "description": "A page of survey questions.",
        "allOf": [
          {
            "$ref": "#/components/schemas/Page"
          },
          {
            "type": "object",
            "required": [
              "items"
            ],
            "properties": {
              "items": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/SurveyQuestion"
                }
              }
            }
          }
        ]
      },
      "SurveyQuestion": {
        "type": "object",
        "description": "A survey question.",
        "x-provenance": {
          "source": "docs",
          "note": "Item shape derived from official docs; not yet observed live — the sandbox committee has no survey questions and POST /surveyQuestions rejects every type value tried so far."
        },
        "properties": {
          "surveyQuestionId": {
            "type": "integer",
            "description": "Unique identifier of the question."
          },
          "type": {
            "type": [
              "string",
              "null"
            ],
            "description": "Category of question, e.g. \"GOTV\". The full set of values is not known — POST /surveyQuestions rejected every type tried in the sandbox."
          },
          "cycle": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Election year the question belongs to, as YYYY."
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Full name of the question."
          },
          "mediumName": {
            "type": [
              "string",
              "null"
            ],
            "description": "Abbreviated name, for displays with limited room."
          },
          "shortName": {
            "type": [
              "string",
              "null"
            ],
            "description": "Shortest form of the name, for the tightest displays."
          },
          "scriptQuestion": {
            "type": [
              "string",
              "null"
            ],
            "description": "The question as read aloud to the person."
          },
          "status": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/SurveyQuestionStatus"
              },
              {
                "type": "null"
              }
            ],
            "description": "Whether the question is in use.",
            "x-provenance": {
              "note": "Enum inferred from the values the `statuses` filter accepts; never observed on a live item."
            }
          },
          "responses": {
            "type": [
              "array",
              "null"
            ],
            "description": "The canned answers a canvasser can record against this question.",
            "items": {
              "$ref": "#/components/schemas/SurveyQuestionResponse"
            }
          }
        }
      },
      "SurveyQuestionStatus": {
        "type": "string",
        "description": "`Active` — in use. `Archived` — retired but kept for reporting. `Inactive` — not currently in use.",
        "enum": [
          "Active",
          "Archived",
          "Inactive"
        ]
      },
      "SurveyQuestionResponse": {
        "type": "object",
        "description": "A canned answer to a survey question.",
        "properties": {
          "surveyResponseId": {
            "type": "integer",
            "description": "Unique identifier of the response."
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Full text of the answer, e.g. \"Yes\"."
          },
          "mediumName": {
            "type": [
              "string",
              "null"
            ],
            "description": "Abbreviated form of the answer."
          },
          "shortName": {
            "type": [
              "string",
              "null"
            ],
            "description": "Shortest form of the answer, e.g. \"Y\"."
          }
        }
      },
      "PersonEmail": {
        "type": "object",
        "description": "An email address on a person record, returned when $expand=emails is requested. Every email a person holds is returned; there is no best-email flag, and `isPreferred` is the only ranking among them.",
        "x-provenance": {
          "lastProbed": "2026-08-04",
          "note": "Enums taken from the API's own INVALID_PARAMETER responses to POST /people/findOrCreate and confirmed by round-tripping every value through GET /people/{vanId}?$expand=emails. Email codes come back as the same single letters that were written. Nullability probed 2026-08-04: an email written with only the address, and another written with every optional field explicitly null, both read back fully populated with defaults (type P, isPreferred, subscriptionStatus S) — isSubscribed is the only field observed null."
        },
        "properties": {
          "email": {
            "type": "string",
            "description": "The email address."
          },
          "type": {
            "type": "string",
            "enum": [
              "P",
              "W",
              "O"
            ],
            "description": "What kind of address this is. `P` = personal, `W` = work, `O` = other. Defaults to `P` when not set at write time, so it is never null.",
            "x-provenance": {
              "note": "Writing any other value returns 400 INVALID_PARAMETER: \"'type' must be one of P , W , O\". Writing an explicit null reads back as \"P\" (observed 2026-08-04)."
            }
          },
          "dateCreated": {
            "type": "string",
            "format": "date-time",
            "description": "When the address was added to the person record. Set by the server."
          },
          "isPreferred": {
            "type": "boolean",
            "description": "Whether this is the person's preferred email address. Exactly one address per person carries it — normally the most recently added one, unless an address was pinned by an explicit write; see `PersonEmailInput.isPreferred`.\n\nThe array comes back **preferred first, then the remaining addresses by `dateCreated` descending**. Addresses that share a `dateCreated` — it has only minute resolution — have no defined order among themselves."
          },
          "isSubscribed": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "The pre-Targeted-Email view of `subscriptionStatus`: whether the address may be used in a broadcast email. Derived from `subscriptionStatus` — `S` maps to true, `U` to false, and `N` to null, since neutral has no boolean equivalent.",
            "x-provenance": {
              "note": "The S/U/N -> true/false/null mapping was observed by writing each subscriptionStatus and reading the person back (2026-08-03). The docs describe isSubscribed only as a write field and mark it deprecated where Targeted Email is available; they do not say what it reads back as."
            }
          },
          "subscriptionStatus": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "U",
              "N",
              "S",
              null
            ],
            "description": "Targeted Email subscription state. `S` = subscribed — the default at write time, and the only status that receives Targeted Email messages. `N` = neutral — no message, but not an opt-out. `U` = unsubscribed. Null on some addresses (`isSubscribed` is null there too). This property exists only where the Targeted Email feature is enabled.",
            "x-provenance": {
              "note": "Writing any other value returns 400 INVALID_PARAMETER with hint \"'U', 'S', 'N'\". An email written without it (or with an explicit null) reads back \"S\" (2026-08-04), but the fuzzer's mutation target carries four older non-preferred addresses whose status reads null — the rule that nulls it was not pinned down, so null stays in the schema."
            }
          }
        }
      },
      "PersonPhone": {
        "type": "object",
        "description": "A phone number on a person record, returned when $expand=phones is requested.",
        "x-provenance": {
          "lastProbed": "2026-08-04",
          "note": "Shape and every enum observed live: each documented write code was posted through POST /people/findOrCreate and read back via GET /people/{vanId}?$expand=phones. Fields not in the documented model (dateCreated, isBest, isDisclosure, smsOptInStatus, isCellPhoneExchange, tags) are read-only additions seen on every phone returned. Nullability probed 2026-08-04: a phone written with only phoneNumber, and another written with every optional field explicitly null, both read back fully populated — the server substitutes defaults (phoneType Personal, deviceType Unknown, opt-in statuses Unknown, dialingPrefix/countryCode from the context) — so only ext, isCellStatus and tags are ever null."
        },
        "properties": {
          "phoneId": {
            "type": "integer",
            "description": "Read-only; unique identifier of the phone."
          },
          "phoneNumber": {
            "type": "string",
            "description": "The number, normalized to digits only. Required and validated at write time, so never null."
          },
          "dialingPrefix": {
            "type": "string",
            "description": "1 to 3 digit country dialing prefix, e.g. \"1\" for North America. Derived from the number's country (defaulting to the context's country) when not written."
          },
          "countryCode": {
            "type": "string",
            "description": "ISO alpha-2 code of the country the number belongs to, e.g. \"US\". Derived from the number's country (defaulting to the context's country) when not written."
          },
          "ext": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 6,
            "description": "Extension; no more than six numeric characters."
          },
          "dateCreated": {
            "type": "string",
            "format": "date-time",
            "description": "When the number was added to the person record. Set by the server."
          },
          "phoneType": {
            "type": "string",
            "enum": [
              "Personal",
              "Work",
              "Other"
            ],
            "description": "Which sphere of the person's life the number belongs to. Defaults to `Personal` when no type is written, so it is never null. The cell/fax/landline/etc distinction is stored in `deviceType`, not here.",
            "x-provenance": {
              "note": "Mapping established by writing all seven accepted codes to one person and reading them back (2026-08-03). Enum lists the read values observed for those codes; phones created outside the API were not sampled. Phones written with no phoneType, or with an explicit null, read back \"Personal\" (observed 2026-08-04)."
            },
            "x-docs-discrepancy": "Official docs document only the write codes and imply they are echoed back. GET returns an expanded category name instead, and seven write codes collapse onto three of them (observed 2026-08-03)."
          },
          "deviceType": {
            "type": "string",
            "enum": [
              "Cell",
              "Landline",
              "Unknown",
              "Fax",
              "VoIP"
            ],
            "description": "What physical kind of device answers the number (decides if the number is textable). \"Unknown\" when the device kind has never been established.",
            "x-provenance": {
              "note": "Read values confirmed by writing each of C, L, U, F, V and reading back (2026-08-03)."
            },
            "x-docs-discrepancy": "Official docs document only the write codes C, L, U, F, V and imply they are echoed back; GET returns the spelled-out names Cell/Landline/Unknown/Fax/VoIP (observed 2026-08-03)."
          },
          "isPreferred": {
            "type": "boolean",
            "description": "Whether this is the person's preferred phone number. At most one number per person carries it, and it is only ever set by an explicit write — there is no positional default, so a person with phones usually has none. Setting it also makes the number `isBest`, overriding the type ranking that flag otherwise follows, and writing a new preferred number clears the flag from the old one.",
            "x-provenance": {
              "lastProbed": "2026-08-06",
              "note": "People with several phones never showed more than one preferred. The isBest interaction was probed on two people: a work-only phone written with isPreferred:true came back best (a work-only phone without it does not), and appending a second preferred number moved both isPreferred and isBest off the first."
            }
          },
          "isBest": {
            "type": "boolean",
            "description": "Read-only; whether this is the number VAN treats as the person's best. **At most one number per person carries it, across all types — it is not per `phoneType`**, and a person can have several phones and no best one at all. It is also what `GET /people?phoneNumber=` searches, so a person with no best number cannot be found by phone there.\n\nWhich number gets it, in order:\n\n1. The number written with `isPreferred: true`, whatever its type or device — including a Work or Fax number that could not otherwise qualify. Writing a new preferred number moves both flags to it.\n2. Otherwise the most recently added number among those that qualify — `phoneType` `Personal` with a `deviceType` other than `Fax`. A `Cell` outranks every other device: once a person has one, a later `Landline`, `VoIP` or `Unknown` number does not take the flag, while a newer `Cell` does.\n3. If nothing qualifies — every number is `Work`, `Other` or a Personal fax, and none is preferred — **no number is best** and every entry reads `false`.\n\nThe returned `phones` array is ordered best-first when a best number exists; the rest of the order is not meaningful.",
            "x-provenance": {
              "lastProbed": "2026-08-06",
              "note": "Not in the documented model — the official common models table does not list isBest for phones at all. Corrects an earlier reading of \"best known number of its type — the most recently updated one\"; neither half holds.\n\nProbed on 14 purpose-built people. Not per type: a person with one Personal, one Work and one Other number had a single best (the Personal one), and a person with four Personal and one Work had one best in total. Not simply most recent: appending Work, Other or Personal/Fax numbers never moved the flag, an existing Cell held it against later Landline, VoIP and Unknown additions, and a Personal/Other written with deviceType Cell lost to a plain Personal — phoneType outranks deviceType. Recency does decide between equals: a second plain Personal took it from the first, and a second Cell from the first — including two Cells written in the same request, where the later array entry won despite an identical dateCreated, so the tiebreak is insertion order rather than the minute-resolution timestamp. The zero-best case was confirmed on work-only, other-only and Personal/fax-only people, each of whom GET /people?phoneNumber= then failed to find, while a work-only person whose number was written with isPreferred:true was best and was found."
            },
            "x-docs-discrepancy": "The official common models do not document isBest for phones; it is returned on every phone, and is awarded to at most one number per person — not one per phoneType — by a phoneType/deviceType ranking rather than by recency alone (observed 2026-08-06)."
          },
          "isDisclosure": {
            "type": "boolean",
            "description": "Read-only; whether the number is usable for campaign-finance disclosure reporting.",
            "x-provenance": {
              "note": "Not in the documented model. Observed true on the first number written to a person and on numbers written with deviceType Cell, false otherwise; the exact rule was not pinned down."
            }
          },
          "smsOptInStatus": {
            "type": "string",
            "enum": [
              "Opt-In",
              "Unknown",
              "Opt-Out"
            ],
            "description": "Read-only; text-message consent for this number. \"Unknown\" — never null — when no consent has been recorded.",
            "x-provenance": {
              "note": "Not in the documented model. Observed to mirror phoneOptInStatus on every phone probed (2026-08-03); there is no separate write field for it."
            }
          },
          "phoneOptInStatus": {
            "type": "string",
            "enum": [
              "Opt-In",
              "Unknown",
              "Opt-Out"
            ],
            "description": "Whether the person has consented to being contacted at this number. \"Unknown\" — never null — when no consent has been recorded.",
            "x-provenance": {
              "note": "Writing any other value returns 400 INVALID_PARAMETER: \"'phoneOptInStatus' must be one of I , U , O\"."
            },
            "x-docs-discrepancy": "Official docs describe the field only as the write codes I/U/O; GET returns the expanded names Opt-In/Unknown/Opt-Out (observed 2026-08-03)."
          },
          "isCellPhoneExchange": {
            "type": "boolean",
            "description": "Read-only; whether the number's exchange (area code + prefix) is one allocated to wireless carriers. An inference from the number itself, independent of `deviceType` and `isCellStatus`.",
            "x-provenance": {
              "note": "Not in the documented model. Only observed as false — the sandbox's fictional 555 numbers belong to no real exchange."
            }
          },
          "isCellStatus": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/PhoneIsCellStatus"
              },
              {
                "type": "null"
              }
            ],
            "description": "How confident VAN is that this number reaches a cell phone. Null when no explicit status has been applied.",
            "x-docs-discrepancy": "The value written is validated but never read back: phones written with a valid isCellStatus still return null from GET /people/{vanId}?$expand=phones (observed 2026-08-03)."
          },
          "tags": {
            "type": [
              "array",
              "null"
            ],
            "items": {},
            "description": "Read-only; tags applied to the number.",
            "x-provenance": {
              "note": "Not in the documented model. Only observed as null; item shape unverified."
            }
          }
        }
      },
      "PhoneIsCellStatus": {
        "description": "A confidence level for whether a phone number reaches a cell phone. The four levels are fixed; `GET /phones/isCellStatuses` returns them as a bare array (empty in the sandbox). On write, supplying either `statusId` or `statusName` alone is enough; omitting the object entirely leaves any existing status unchanged.",
        "x-provenance": {
          "lastProbed": "2026-08-03",
          "note": "Values come from the API's own INVALID_PARAMETER response: \"'statusId' must be one of 1 , 2 , 3 , 4\" and \"'statusName' must be one of Verified Cell , Likely Cell , Likely Not a Cell , Not a Cell\". The id-to-name pairing below follows that ordering and the docs' example ({\"statusId\": 2, \"statusName\": \"Likely Cell\"}); the API accepts a mismatched pair without complaint, so the pairing could not be confirmed by round-trip."
        },
        "oneOf": [
          {
            "title": "Verified Cell",
            "type": "object",
            "properties": {
              "statusId": {
                "const": 1
              },
              "statusName": {
                "const": "Verified Cell"
              }
            }
          },
          {
            "title": "Likely Cell",
            "type": "object",
            "properties": {
              "statusId": {
                "const": 2
              },
              "statusName": {
                "const": "Likely Cell"
              }
            }
          },
          {
            "title": "Likely Not a Cell",
            "type": "object",
            "properties": {
              "statusId": {
                "const": 3
              },
              "statusName": {
                "const": "Likely Not a Cell"
              }
            }
          },
          {
            "title": "Not a Cell",
            "type": "object",
            "properties": {
              "statusId": {
                "const": 4
              },
              "statusName": {
                "const": "Not a Cell"
              }
            }
          }
        ]
      },
      "PersonAddress": {
        "type": "object",
        "description": "An address on a person record, returned when $expand=addresses is requested. The expansion returns only the best known type=Home address and the best known type=Mailing address — at most two entries, and the same address appears twice (once per type, sharing an addressId) when it serves as both. type=Work and type=Custom addresses are stored but not surfaced here.",
        "x-provenance": {
          "lastProbed": "2026-08-04",
          "note": "Shape observed live by writing addresses of each documented type through POST /people/findOrCreate and reading them back. Fields not in the documented model (unitNo, geoLocation, preview, streetAddress, displayMode) are read-only additions seen on every address returned. Nullability probed 2026-08-04: a zip-only address reads back with city/state inferred from the zip and addressLine1 null; a city+state-only address reads back zipOrPostalCode \"\" (empty string, not null); addresses too sparse or unresolvable to standardize (street line only, or an unknown zip) are not surfaced by the expansion at all — so city, stateOrProvince, zipOrPostalCode and countryCode were never observed null."
        },
        "properties": {
          "addressId": {
            "type": "integer",
            "format": "int64",
            "description": "Read-only; unique identifier of the address on this person. Shared by the Home and Mailing entries when one address fills both roles."
          },
          "type": {
            "type": "string",
            "enum": [
              "Voting",
              "Mailing"
            ],
            "description": "Which role the address plays for the person. This expansion only ever returns \"Voting\" or \"Mailing\", even though the database can also store \"Work\" and \"Custom\"; a person with no mailing address of their own has their home address returned under \"Mailing\" as well.",
            "x-provenance": {
              "note": "Read values observed by writing Home, Work, Mailing and Custom addresses (2026-08-03). An address written as Work or Custom did not appear in the expansion at all."
            },
            "x-docs-discrepancy": "Official docs list five address types with no indication that reads are restricted; $expand=addresses only ever returns Voting and Mailing, and Work and Custom addresses are omitted from the response entirely (observed 2026-08-03)."
          },
          "addressLine1": {
            "type": [
              "string",
              "null"
            ],
            "description": "First line of the standardized street address."
          },
          "addressLine2": {
            "type": [
              "string",
              "null"
            ],
            "description": "Second line of the street address."
          },
          "addressLine3": {
            "type": [
              "string",
              "null"
            ],
            "description": "Third line of the street address."
          },
          "unitNo": {
            "type": [
              "string",
              "null"
            ],
            "description": "Read-only; the unit or apartment number parsed out of the street address by standardization.",
            "x-provenance": {
              "note": "Not in the documented model. Only observed as null, including for an address written with \"Apt 4\" on line 2 — the sandbox does not appear to run full standardization."
            }
          },
          "city": {
            "type": "string",
            "description": "City or town. Inferred from the postal code when not written."
          },
          "stateOrProvince": {
            "type": "string",
            "description": "Two or three character state or province code, e.g. \"MN\", \"ON\", \"NSW\". Inferred from the postal code when not written."
          },
          "zipOrPostalCode": {
            "type": "string",
            "description": "ZIP, ZIP+4, postal code, post code, etc. An empty string — not null — when the stored address has none."
          },
          "geoLocation": {
            "description": "Read-only; the geocoded position of the address.",
            "x-provenance": {
              "note": "Not in the documented model. Only observed as null — the sandbox does not geocode API-created addresses; type unverified."
            }
          },
          "countryCode": {
            "type": "string",
            "description": "Two character ISO country code supported by the VAN context, e.g. \"US\". Defaults to the context's country."
          },
          "preview": {
            "type": "string",
            "description": "Read-only; a one-line display form of the street address. A single space when there are no street lines.",
            "x-provenance": {
              "note": "Not in the documented model. Observed as address lines 1 and 2 joined by a space, with a trailing space when line 2 is empty."
            }
          },
          "isPreferred": {
            "type": "boolean",
            "description": "Read-only; whether this is the person's preferred address. It marks the entry filling the `Voting` slot: `true` on that entry, and on the `Mailing` entry only when the same address fills both slots. A mailing address of the person's own always reads `false`.",
            "x-provenance": {
              "lastProbed": "2026-08-06",
              "note": "Observed on nine people covering home-only, mailing-only, home+mailing and repeated writes of each type. No person was seen with a preferred address that was not the Voting one, and none lacked a preferred address entirely."
            }
          },
          "isBest": {
            "type": "boolean",
            "description": "Read-only; whether this is the best known address of its type — the most recently added address of that type. **The flag is per type**, so a person can have two best addresses at once, one `Voting` and one `Mailing` (and when a single address fills both slots, that one address is returned twice, best in each).\n\nIn practice the field carries no information on read: this expansion returns nothing but the best `Voting` and the best `Mailing` address, so every entry it returns reads `true`. To learn that an older address exists at all, match it with `POST /people/find`.",
            "x-provenance": {
              "lastProbed": "2026-08-06",
              "note": "Per-type behavior and the always-true reading observed on nine people; isBest false was never seen on an address. Recency confirmed by appending addresses in separate update calls to one person: each new Home address took the Voting slot (501 → 502 → 504) and each new Mailing address took the Mailing slot, while POST /people/find still matched the displaced ones, so they are hidden rather than replaced. Within a single request the rule does not apply to home addresses — three Home addresses written in one call stored only the first, the other two matching nothing afterwards — whereas three Mailing addresses in one call were all stored, with the last best."
            }
          },
          "streetAddress": {
            "type": [
              "string",
              "null"
            ],
            "description": "Read-only; the street portion of the standardized address.",
            "x-provenance": {
              "note": "Not in the documented model. Only observed as null; type assumed to be string."
            }
          },
          "displayMode": {
            "type": "string",
            "description": "Read-only; which form of the address the other fields show — \"Standardized\" for the normalized version rather than the raw text as entered.",
            "x-provenance": {
              "note": "Not in the documented model. Only \"Standardized\" observed; other values not enumerated, so this is left unconstrained."
            }
          }
        }
      },
      "PersonEmailInput": {
        "type": "object",
        "description": "An email address as written to a person record. Reads come back as PersonEmail; the two differ only in required-ness and the server-set dateCreated, since email codes round-trip unchanged.",
        "x-provenance": {
          "lastProbed": "2026-08-03",
          "note": "Every value round-tripped through POST /people/findOrCreate and GET /people/{vanId}?$expand=emails."
        },
        "required": [
          "email"
        ],
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "description": "The address. Validated: a malformed value returns 400 INVALID_PARAMETER \"'email' is not a valid email address\"."
          },
          "type": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "P",
              "W",
              "O",
              null
            ],
            "description": "`P` = personal, `W` = work, `O` = other. Defaults to `P`."
          },
          "isPreferred": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Whether this becomes the person's preferred address. Documented as defaulting to false; in practice **a newly written address takes the flag**, off whichever address held it before.\n\nWriting `true` explicitly **pins** the address: the flag then stops following new additions and survives a merge that brings in a more recently added address. Pinning works on an address the person already holds too — re-writing it with the flag set makes it preferred again.\n\n`dateCreated` has only minute resolution, and addresses written within the same minute are not ordered against each other; which of them ends up preferred is not predictable. Space writes at least a minute apart if you need the outcome to be deterministic.",
            "x-provenance": {
              "note": "Probed 2026-08-06 by appending addresses at 65-second intervals so that dateCreated actually distinguishes them: each new address took the flag in turn, while an address written with isPreferred:true held it against two later additions and against a merge that brought in a newer address.\n\nA caution for anyone re-probing this: same-minute writes give a badly misleading picture. When every address shares a dateCreated the flag settles on one of them and stops following later writes, which reads as a positional rule — that artifact produced a wrong 'the second address is always preferred' reading here on 2026-08-06 before the spacing was added, and it is why the original 2026-08-03 reading (a new address takes the flag) was briefly and wrongly overturned."
            }
          },
          "isSubscribed": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Deprecated where Targeted Email is available. `false` is a permanent opt-out — it stores `subscriptionStatus: \"U\"`, which cannot be reversed. Cannot be sent together with `subscriptionStatus`."
          },
          "subscriptionStatus": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "U",
              "N",
              "S",
              null
            ],
            "description": "`S` = subscribed (the default, and the only status that receives Targeted Email), `N` = neutral, `U` = unsubscribed. `U` is terminal. Only available where Targeted Email is enabled, and not valid alongside `isSubscribed`."
          }
        }
      },
      "PersonPhoneInput": {
        "type": "object",
        "description": "A phone number as written to a person record. The code fields take single letters here, but they are input codes mapped to the stored model at write time (see PersonPhone): several codes collapse onto one stored value, and reads return the stored words, not the codes.",
        "x-provenance": {
          "lastProbed": "2026-08-03",
          "note": "Every code round-tripped through POST /people/findOrCreate and GET /people/{vanId}?$expand=phones."
        },
        "required": [
          "phoneNumber"
        ],
        "properties": {
          "phoneNumber": {
            "type": "string",
            "description": "Non-numeric characters are stripped, then the remaining digits are validated for the country implied by `countryCode`/`dialingPrefix`, defaulting to the context's country. A number that fails validation returns 400 INVALID_PARAMETER \"Phone number is not valid. If entering UK number, please include leading 0.\".",
            "examples": [
              "907-111-2222",
              "(907) 111-2222",
              "9071112222"
            ]
          },
          "phoneType": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "H",
              "W",
              "O",
              "C",
              "M",
              "F",
              "P",
              null
            ],
            "description": "`H` = home, `W` = work, `O` = other, `C` = cell, `M` = main, `F` = fax, `P` = personal. A write-only input code, not what is stored: at write time it is collapsed and stored as `phoneType` `Personal` (H, C, M, P), `Work` (W, F) or `Other` (O), and `C` additionally stores `deviceType: \"Cell\"` while `F` stores `deviceType: \"Fax\"`. Reads return the stored values (see PersonPhone).",
            "x-docs-discrepancy": "Official docs list five codes (H, W, C, M, F); the API's own INVALID_PARAMETER response accepts seven — \"'phoneType' must be one of: H, W, O, C, M, F, P\" (observed 2026-08-03)."
          },
          "deviceType": {
            "description": "What kind of device answers the number; decides whether it is textable. Accepts either a letter — `C` = cell, `L` = landline, `U` = unknown, `F` = fax, `V` = VoIP — or the equivalent numeric id: 1 (Cell), 2 (Landline), 4 (Unknown), 5 (Fax), 6 (VoIP). Defaults to Unknown. Available since May 9, 2024.",
            "oneOf": [
              {
                "type": "string",
                "enum": [
                  "C",
                  "L",
                  "U",
                  "F",
                  "V"
                ]
              },
              {
                "type": "integer",
                "enum": [
                  1,
                  2,
                  4,
                  5,
                  6
                ]
              },
              {
                "type": "null"
              }
            ],
            "x-docs-discrepancy": "Official docs list only the letter codes. The API's INVALID_PARAMETER response also accepts numeric ids 1, 2, 4, 5, 6; writing 2 and 6 was confirmed to store Landline and VoIP (observed 2026-08-03). There is no id 3."
          },
          "ext": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 6,
            "description": "Extension. Over six characters returns 400 INVALID_PARAMETER \"'ext' must be between 0 and 6 characters\"."
          },
          "isPreferred": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Whether this becomes the person's preferred number. Defaults to false and stays there — a newly added phone never takes the preferred flag implicitly, however many are written. An explicit `true` is honoured.",
            "x-provenance": {
              "note": "Seven phones written to one person with no isPreferred flag all read back isPreferred false (2026-08-03); a phone written with an explicit isPreferred:true was confirmed to read back preferred (2026-08-06)."
            }
          },
          "phoneOptInStatus": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "I",
              "U",
              "O",
              null
            ],
            "description": "`I` = opt in, `U` = unknown (the default), `O` = opt out. Reads back as `Opt-In`, `Unknown`, `Opt-Out`, and also sets the read-only `smsOptInStatus` to the same value."
          },
          "isCellStatus": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/PhoneIsCellStatus"
              },
              {
                "type": "null"
              }
            ],
            "description": "Confidence that the number reaches a cell phone. Omitting it leaves any existing explicit status unchanged."
          },
          "dialingPrefix": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 3,
            "description": "1 to 3 numeric characters identifying the country, e.g. \"1\". If sent alongside `countryCode`, the two must name the same country."
          },
          "countryCode": {
            "type": [
              "string",
              "null"
            ],
            "description": "ISO alpha-2 country code, e.g. \"US\". If sent alongside `dialingPrefix`, the two must name the same country."
          }
        }
      },
      "PersonAddressInput": {
        "type": "object",
        "description": "An address as written to a person record. Reads come back as PersonAddress, which surfaces only the best known Home and Mailing addresses and adds several standardization fields.",
        "x-provenance": {
          "lastProbed": "2026-08-03",
          "note": "Each documented type written through POST /people/findOrCreate and read back with $expand=addresses."
        },
        "properties": {
          "addressLine1": {
            "type": [
              "string",
              "null"
            ],
            "description": "First line of the street address."
          },
          "addressLine2": {
            "type": [
              "string",
              "null"
            ],
            "description": "Second line of the street address."
          },
          "addressLine3": {
            "type": [
              "string",
              "null"
            ],
            "description": "Third line of the street address."
          },
          "city": {
            "type": [
              "string",
              "null"
            ],
            "description": "City or town."
          },
          "stateOrProvince": {
            "type": [
              "string",
              "null"
            ],
            "description": "Two or three character state or province code, e.g. \"MN\", \"ON\", \"NSW\"."
          },
          "zipOrPostalCode": {
            "type": [
              "string",
              "null"
            ],
            "description": "ZIP, ZIP+4, postal code, post code, etc."
          },
          "countryCode": {
            "type": [
              "string",
              "null"
            ],
            "description": "Two character ISO country code supported by the VAN context. Defaults to the context's country."
          },
          "type": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "Mailing",
              "Home",
              "Voting",
              "Work",
              "Custom",
              null
            ],
            "description": "`Home` and `Voting` mean the same thing and read back as `Voting`. Some types are unavailable in some contexts. An address written as `Work` or `Custom` is stored but never appears under $expand=addresses. When a person has no mailing address, their home address serves as the mailing address too.",
            "x-docs-discrepancy": "The value is not validated: an address written with type \"Q\" is accepted with 201 and filed as the person's home address (observed 2026-08-03)."
          }
        }
      },
      "PersonIdentifierInput": {
        "type": "object",
        "description": "A known external identifier for the person, e.g. a DWID or voter file VANID. External IDs are case-insensitive in VAN — \"Abcd1234\" always matches \"ABCD1234\".",
        "x-provenance": {
          "lastProbed": "2026-08-03",
          "note": "Only the rejection path was observed: an unrecognized type returns 400 \"'type' (bogus) is not a valid ExternalID in this context\". The sandbox 500s on the valid type 'dwid' (see the operation description), so a successful write was never observed."
        },
        "required": [
          "type",
          "externalId"
        ],
        "properties": {
          "type": {
            "type": "string",
            "description": "An external identifier type available in the current context. Use `votervanid` for a VoterFile VANID from a My Campaign call, and `dwid` for Catalist DWIDs in either mode."
          },
          "externalId": {
            "type": "string",
            "description": "The identifier value; case-insensitive."
          }
        }
      },
      "PersonCustomFieldValueInput": {
        "type": "object",
        "description": "A value for one of the context's custom fields.",
        "x-provenance": {
          "lastProbed": "2026-08-03",
          "note": "Only the rejection path was observed — the demo committee defines no custom fields, so writing customFieldId 1 returns 400 \"Custom field 1 does not exist.\". Property names taken from the error's `properties` path and the official docs."
        },
        "properties": {
          "customFieldId": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Id of a custom field defined in the current context. Unknown ids return 400 INVALID_PARAMETER."
          },
          "customFieldGroupId": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Id of the custom field's group."
          },
          "assignedValue": {
            "type": [
              "string",
              "null"
            ],
            "description": "The value to store."
          }
        }
      },
      "PersonInput": {
        "type": "object",
        "description": "The person payload shared by POST /people/create, POST /people/findOrCreate and POST /people/{vanId} — called the \"Match Candidate\" common model in the official docs. Every field is optional — an entirely empty body is accepted and creates a blank person record. On update the payload is merged, not replaced: fields left out keep their existing values, and emails, phones and addresses are appended rather than swapped.\n\nEvery scalar field here is writeable through POST /people/{vanId}, in one payload, with four exceptions to know about. `collectedLocationId`, `electionType` and `cycle` are accepted and then discarded — nothing the API returns ever carries them back. `organizationContactCommonName` and `organizationContactOfficialName` are stored only while `contactMode` is \"Organization\". `suffix` is matched against a lookup rather than stored verbatim. And `nickname`, `website`, `jobTitle` and `contactMethodPreferenceCode` do write, but read back only under `$expand=preferences`, so a plain round-trip makes them look dropped.",
        "x-provenance": {
          "lastProbed": "2026-08-10",
          "note": "Field list from the official docs' Match Candidate model; max lengths and the enforced/unenforced split established by probing POST /people/create with out-of-range values. Not modelled here, because the sandbox has no lookup values to write against and only the 400 path could be seen: pronouns, selfReportedRaces, selfReportedEthnicities, selfReportedGenders, selfReportedSexualOrientations and selfReportedLanguagePreference. Each takes an id that must exist in the context, e.g. 'reportedRaceId' is not a valid ReportedRace in this context. The writeable set was swept on 2026-08-10 by updating a blank person with every scalar field at once and reading the record back with and without $expand=preferences."
        },
        "properties": {
          "vanId": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Id of an existing person record. When present (and not 0), everything else in the payload stops mattering to the match. The two endpoints treat an id that matches nothing differently: POST /people/create answers 302 Matched for any plausible id without ever checking it exists, and for an implausible id quietly creates from the other fields while still answering 302 Matched; POST /people/findOrCreate ignores an unknown id and runs its ordinary match on the rest of the payload. A vanId of 0 is ignored by both. See each operation's outcomes for the full picture.",
            "x-provenance": {
              "note": "Unlike POST /people/find, which returns 500 for vanId 0, the write endpoints tolerate it (observed 2026-08-03; on 2026-08-08 create answered 201 Stored for vanId 0 and 302-with-a-hidden-create for negative ids), so no minimum is imposed here."
            }
          },
          "firstName": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 75
          },
          "middleName": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 75
          },
          "lastName": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 150
          },
          "suffix": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 50,
            "description": "Part of the name following the last name, e.g. \"Jr.\". Matched against a lookup rather than stored verbatim: case and punctuation are ignored, so \"jr\" and \"Jr.\" both read back as \"Jr\". A value the lookup does not recognize, eg \"Esq.\", is neither stored nor refused — the write succeeds and the existing suffix is left standing."
          },
          "title": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 10,
            "description": "An honorific."
          },
          "salutation": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 100,
            "description": "Preferred greeting for correspondence. Derived from the name when not supplied."
          },
          "envelopeName": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 350,
            "description": "Preferred name for mailings. Derived from the name when not supplied."
          },
          "nickname": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 50,
            "description": "Written normally, but returned only under $expand=preferences."
          },
          "website": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 50,
            "description": "Written normally, but returned only under $expand=preferences."
          },
          "party": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "maxLength": 1,
            "description": "One-character party affiliation, e.g. \"D\". Only the length is checked — any single character is stored as given.",
            "x-provenance": {
              "note": "Writing \"Q\" is accepted and reads back as \"Q\"; writing \"Democrat\" returns 400 for length, not for value (observed 2026-08-03)."
            }
          },
          "contactMethodPreferenceCode": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "P",
              "E",
              "M",
              "F",
              "S",
              null
            ],
            "description": "Preferred method of contact: `P` = phone, `E` = email, `M` = mail, `F` = fax, `S` = SMS. Any other value returns 400 \"The specified condition was not met for 'contactMethodPreferenceCode'\". Written normally, but returned only under $expand=preferences."
          },
          "employer": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 50,
            "description": "May not be available in every context."
          },
          "occupation": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 50,
            "description": "May not be available in every context."
          },
          "jobTitle": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 150,
            "description": "May not be available in every context. Written normally, but returned only under $expand=preferences — unlike employer and occupation."
          },
          "sex": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "M",
              "F",
              null
            ],
            "description": "Matched case-insensitively — \"m\" is accepted and stored as \"M\". Any other value returns 400 \"The specified condition was not met for 'sex'\"."
          },
          "dateOfBirth": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "examples": [
              "2001-11-23"
            ],
            "description": "ISO 8601 date, which must fall in the 20th or 21st century — otherwise 400 \"'dateOfBirth' must be in the 20th or 21st century.\". A value that is not a parseable date is not an error: it is silently dropped and the person record stores null.",
            "x-provenance": {
              "note": "\"not-a-date\" returned 201 with dateOfBirth null (observed 2026-08-03)."
            }
          },
          "collectedLocationId": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Location where the person's voter registration application was collected. Accepted and then discarded in a My Campaign context: no response this spec documents carries it back."
          },
          "electionType": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "G",
              "P",
              "R",
              "PP",
              "SP",
              "SG",
              "MP",
              "MG",
              "C",
              "O",
              null
            ],
            "description": "Type of election registered for: `G` = General, `P` = Primary, `R` = Run-off, `PP` = Presidential Primary, `SP` = Special Primary, `SG` = Special General, `MP` = Municipal Primary, `MG` = Municipal General, `C` = Caucus, `O` = Other. Any other value returns 400 \"Invalid Election Type\". Accepted and then discarded in a My Campaign context: the value reaches no election record, and $expand=electionRecords stays empty."
          },
          "cycle": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 4,
            "maxLength": 4,
            "examples": [
              "2024"
            ],
            "description": "Election year the person registered to vote, as a four-character numeric string. Any other length returns 400 \"'cycle' must be 4 characters in length\". Accepted and then discarded in a My Campaign context, like electionType."
          },
          "emails": {
            "type": [
              "array",
              "null"
            ],
            "description": "Appended to the person's existing addresses, not substituted for them. A bare object instead of an array is silently ignored.",
            "items": {
              "$ref": "#/components/schemas/PersonEmailInput"
            }
          },
          "phones": {
            "type": [
              "array",
              "null"
            ],
            "description": "Appended to the person's existing numbers, not substituted for them. A bare object instead of an array is silently ignored. A null array entry returns 500.",
            "items": {
              "$ref": "#/components/schemas/PersonPhoneInput"
            }
          },
          "addresses": {
            "type": [
              "array",
              "null"
            ],
            "description": "Appended to the person's existing addresses, not substituted for them. A bare object instead of an array is silently ignored.",
            "items": {
              "$ref": "#/components/schemas/PersonAddressInput"
            }
          },
          "identifiers": {
            "type": [
              "array",
              "null"
            ],
            "description": "Known external identifiers. Writing a type the context does not recognize returns a clean 400; writing the valid type `dwid` returns 500 in a My Campaign context, so no successful write was ever observed.",
            "items": {
              "$ref": "#/components/schemas/PersonIdentifierInput"
            }
          },
          "customFieldValues": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/PersonCustomFieldValueInput"
            }
          },
          "organizationContactCommonName": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 150,
            "description": "An organization's common name. Stored only while contactMode is \"Organization\" — sent on a person-mode record it is silently discarded. Only applies to My Campaign databases with organizations-as-contacts enabled."
          },
          "organizationContactOfficialName": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 150,
            "description": "An organization's official name. Stored only while contactMode is \"Organization\" — sent on a person-mode record it is silently discarded. Only applies to My Campaign databases with organizations-as-contacts enabled."
          },
          "contactMode": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "Person",
              "Organization",
              null
            ],
            "description": "Only applies to My Campaign databases with organizations-as-contacts enabled.",
            "x-docs-discrepancy": "Official docs say the value must be Person or Organization; it is not validated. Writing \"Q\" returns 201 and the person reads back with contactMode \"Person\" (observed 2026-08-03)."
          }
        }
      },
      "PersonMergeInput": {
        "type": "object",
        "description": "Names the **primary** of a merge — the person that survives. The secondary is the vanId in the path.",
        "required": [
          "vanId"
        ],
        "properties": {
          "vanId": {
            "type": "integer",
            "format": "int32",
            "minimum": 1,
            "description": "VAN id of the primary person, which survives the merge and keeps this id.\n\nAbsent, null, `0` and values too large for `int32` are all rejected with 400 `Must specify VanIDs for merging`. A negative id returns 500, so this schema requires a positive one. A numeric string is accepted and coerced, and a non-integer number is truncated — neither is worth relying on.",
            "example": 102720504
          }
        },
        "x-provenance": {
          "source": "docs + sandbox probe",
          "lastProbed": "2026-08-05",
          "note": "Unknown fields alongside vanId are ignored (a body with a bogus extra key merged normally). minimum is 1 rather than 0 because a negative vanId 500s; 0 is a clean 400."
        }
      },
      "PersonMergeResult": {
        "type": "object",
        "description": "The outcome of a merge: the vanId of the person that survived, which is always the primary from the request body. The secondary's vanId is not echoed back, and is no longer resolvable.",
        "required": [
          "vanId"
        ],
        "properties": {
          "vanId": {
            "type": "integer",
            "description": "VAN id of the surviving primary person.",
            "example": 102720708
          }
        }
      },
      "PersonList": {
        "description": "A page of person records.",
        "allOf": [
          {
            "$ref": "#/components/schemas/Page"
          },
          {
            "type": "object",
            "required": [
              "items"
            ],
            "properties": {
              "items": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Person"
                }
              }
            }
          }
        ]
      },
      "Person": {
        "type": "object",
        "description": "A person record: returned by GET /people/{vanId}, as the items of GET /people, and as what a redirect-following client lands on after the write endpoints. A few fields read differently between get-by-id and search — see `formalSalutation` and `formalEnvelopeName`.\n\nThe properties listed below with no type were only ever observed as null, either because the section needs `$expand` or because the sandbox committee holds no such data. They are listed to document that the API returns them, but their shape is unverified.\n\nSix scalar fields are returned only under `$expand=preferences` — `nickname`, `website`, `jobTitle`, `contactMethodPreferenceCode`, `contactMethodPreferenceId`, `contactMethodPreferenceName` — so a write of any of them looks discarded on a plain read. `organizationContactCommonName` and `organizationContactOfficialName` are always returned, but hold a value only while `contactMode` is \"Organization\".",
        "x-provenance": {
          "lastProbed": "2026-08-10",
          "note": "Field inventory observed live on a minimal API-created person; the untyped fields need a more fully populated person record to pin down. Nullability checked against a fully blank person record (created from {}, 2026-08-04): even there contactSource, contactMode, formalSalutation (\"Friend\"), formalEnvelopeName (\"Our Friend At\"), isDeceased, dateCreated and dateAcquired come back populated, while salutation and envelopeName are null. On 2026-08-10 the $expand=preferences group and the organization-name fields were pinned down by writing every scalar PersonInput field in one update and reading the record back with and without the expand."
        },
        "properties": {
          "vanId": {
            "type": "integer"
          },
          "firstName": {
            "type": [
              "string",
              "null"
            ]
          },
          "lastName": {
            "type": [
              "string",
              "null"
            ]
          },
          "middleName": {
            "type": [
              "string",
              "null"
            ]
          },
          "suffix": {
            "type": [
              "string",
              "null"
            ]
          },
          "title": {
            "type": [
              "string",
              "null"
            ]
          },
          "contactSource": {
            "type": "string",
            "description": "How the person record entered the database, e.g. \"API\".",
            "x-provenance": {
              "note": "Only \"API\" observed (the sandbox has no UI-created people); other values not enumerated. Present even on a blank person record, so typed non-null."
            }
          },
          "contactMode": {
            "type": "string",
            "enum": [
              "Person",
              "Organization"
            ],
            "description": "Defaults to \"Person\" even on a blank person record; an unrecognized written value is stored as \"Person\"."
          },
          "salutation": {
            "type": [
              "string",
              "null"
            ]
          },
          "formalSalutation": {
            "type": [
              "string",
              "null"
            ],
            "description": "On GET /people/{vanId}, derived from the name — \"Friend\" when there is no name to derive from, unlike `salutation`, which is null in that case. Always null in GET /people search results, even for people where get-by-id derives a value.",
            "x-provenance": {
              "lastProbed": "2026-08-04",
              "note": "Null-in-search-results found by the fuzzer on GET /people; confirmed against vanId 102704536, which reads back \"Scgapi Matchrules\" here via get-by-id but null via search."
            }
          },
          "envelopeName": {
            "type": [
              "string",
              "null"
            ]
          },
          "formalEnvelopeName": {
            "type": [
              "string",
              "null"
            ],
            "description": "On GET /people/{vanId}, derived from the name — \"Our Friend At\" when there is no name to derive from, unlike `envelopeName`, which is null in that case. Always null in GET /people search results, even for people where get-by-id derives a value.",
            "x-provenance": {
              "lastProbed": "2026-08-04",
              "note": "Null-in-search-results found by the fuzzer on GET /people; same evidence as formalSalutation."
            }
          },
          "party": {
            "type": [
              "string",
              "null"
            ]
          },
          "employer": {
            "type": [
              "string",
              "null"
            ]
          },
          "occupation": {
            "type": [
              "string",
              "null"
            ]
          },
          "jobTitle": {
            "type": [
              "string",
              "null"
            ],
            "description": "Null unless the request included $expand=preferences — unlike `employer` and `occupation`, which are always returned."
          },
          "sex": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "M",
              "F",
              null
            ],
            "description": "Always the uppercase one-letter code, even when the value was written in lowercase.",
            "x-provenance": {
              "source": "sandbox probe + official docs (common-models.md: \"must be M or F\")",
              "lastProbed": "2026-08-04",
              "note": "Wrote sex \"m\"/\"f\" via /people/findOrCreate; GET returned \"M\"/\"F\" respectively (vanIds 102716311, 102716312)."
            }
          },
          "dateOfBirth": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "partialDateOfBirth": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "month": {
                "type": "integer"
              },
              "day": {
                "type": "integer"
              },
              "year": {
                "type": "integer"
              }
            },
            "examples": [
              {
                "year": 2001,
                "month": 11,
                "day": 23
              }
            ],
            "description": "The birth date broken into components; null when dateOfBirth is null. Returned by both GET /people and GET /people/{vanId}.",
            "x-provenance": {
              "lastProbed": "2026-08-04",
              "note": "Surfaced by fuzzing GET /people — earlier field inventories missed it because every probed person had a null dateOfBirth, which nulls this field too. Only full dates observed (month, day and year all set); whether a genuinely partial date omits components is unverified."
            }
          },
          "isDeceased": {
            "type": "boolean"
          },
          "dateCreated": {
            "type": "string",
            "format": "date-time"
          },
          "dateAcquired": {
            "type": "string",
            "format": "date-time",
            "description": "For API-created people this is \"0001-01-01T00:00:00Z\" (the .NET default date)."
          },
          "emails": {
            "type": [
              "array",
              "null"
            ],
            "description": "Null unless the request included $expand=emails; an empty array when expanded and none exist.",
            "items": {
              "$ref": "#/components/schemas/PersonEmail"
            }
          },
          "phones": {
            "type": [
              "array",
              "null"
            ],
            "description": "Null unless the request included $expand=phones; an empty array when expanded and none exist. Every phone on the person is returned, not just the best known one.",
            "items": {
              "$ref": "#/components/schemas/PersonPhone"
            }
          },
          "addresses": {
            "type": [
              "array",
              "null"
            ],
            "description": "Null unless the request included $expand=addresses; an empty array when expanded and none exist. Provides the best known Home address and the best known Mailing address only — the same address appears under both types when it fills both roles, and Work/Custom addresses are omitted.",
            "items": {
              "$ref": "#/components/schemas/PersonAddress"
            }
          },
          "sourceFileTitle": {},
          "sourceFileFirstName": {},
          "sourceFileMiddleName": {},
          "sourceFileLastName": {},
          "sourceFileSuffix": {},
          "organizationContactCommonName": {
            "type": [
              "string",
              "null"
            ],
            "description": "An organization's common name. Only stored while `contactMode` is \"Organization\" — written on a person-mode record it is silently discarded."
          },
          "organizationContactOfficialName": {
            "type": [
              "string",
              "null"
            ],
            "description": "An organization's official name. Only stored while `contactMode` is \"Organization\" — written on a person-mode record it is silently discarded."
          },
          "additionalSalutation": {},
          "preferredPronoun": {},
          "pronouns": {},
          "namePronunciation": {},
          "additionalEnvelopeName": {},
          "contactMethodPreferenceCode": {
            "type": [
              "string",
              "null"
            ],
            "description": "Null unless the request included $expand=preferences. The one-letter code that was written — see `contactMethodPreferenceCode` on PersonInput."
          },
          "contactMethodPreferenceId": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Null unless the request included $expand=preferences. The internal id of the preferred contact method, e.g. 2 for Email."
          },
          "contactMethodPreferenceName": {
            "type": [
              "string",
              "null"
            ],
            "description": "Null unless the request included $expand=preferences. The code spelled out, e.g. \"Email\"."
          },
          "assistantName": {},
          "nickname": {
            "type": [
              "string",
              "null"
            ],
            "description": "Null unless the request included $expand=preferences."
          },
          "website": {
            "type": [
              "string",
              "null"
            ],
            "description": "Null unless the request included $expand=preferences."
          },
          "professionalSuffix": {},
          "selfReportedRace": {},
          "selfReportedEthnicity": {},
          "selfReportedRaces": {},
          "selfReportedEthnicities": {},
          "selfReportedGenders": {},
          "selfReportedSexualOrientations": {},
          "selfReportedLanguagePreference": {},
          "selfReportedLanguagePreferences": {},
          "recordedAddresses": {},
          "pollingLocation": {},
          "earlyVoteLocation": {},
          "identifiers": {},
          "codes": {},
          "customFields": {},
          "primaryCustomField": {},
          "contributionSummary": {},
          "suppressions": {},
          "caseworkCases": {},
          "caseworkIssues": {},
          "caseworkStories": {},
          "notes": {
            "type": [
              "array",
              "null"
            ],
            "description": "Notes on the person, when requested with `$expand=notes`. Same objects GET /people/{vanId}/notes returns, with two differences: an uncategorized note's `category` is null here rather than the `{\"noteCategoryId\": 0, \"name\": null}` stub, and the array is not paginated. View-restricted notes are withheld here too.",
            "x-provenance": {
              "source": "sandbox probe",
              "lastProbed": "2026-08-04",
              "note": "Compared side by side against GET /people/102714507/notes on a person with six notes: same ids and fields, different `category` rendering and a different item order."
            },
            "items": {
              "$ref": "#/components/schemas/Note"
            }
          },
          "scores": {},
          "customProperties": {},
          "electionRecords": {},
          "membershipStatus": {},
          "organizationRoles": {},
          "districts": {},
          "surveyQuestionResponses": {},
          "finderNumber": {},
          "biographyImageUrl": {},
          "biographyText": {},
          "biographyHtml": {},
          "primaryContact": {}
        }
      }
    }
  }
}