Greenhouse 422 "phone_number is invalid" when the agent pushes a scraped phone with country-code formatting the API...

TL;DR: Normalize the phone to E.164 (leading plus, country code, digits only, no spaces or punctuation) before sending it to Greenhouse. The 422 means Greenhouse's validator rejected the exact string the agent sent, and scraped phones almost always carry formatting the API does not accept. Log the raw value first so you can see what actually went over the wire.

422 "phone_number is invalid"

1. Log the exact phone_number value the agent sent on the failed request. Expected: you see the raw string, often with a surprise like spaces, dashes, parentheses, or a country-code format the validator choked on.
2. Strip all formatting: remove spaces, dashes, dots, parentheses, and any extension suffix; keep a single leading plus sign followed by digits. Expected: the value looks like +14155550123 with nothing else in it.
3. Make sure the country code is present: if the scraped number has no country code, add the candidate's known country code (from their location or the job's country) rather than guessing. Expected: every number starts with a plus sign and a valid country dialing code.
4. Retry the candidate create or update with the normalized number. Expected: the API returns 200 or 201 instead of 422.
5. If it still 422s, try digits only with no plus sign as a fallback, and check whether Greenhouse wants the number split across its phone type fields instead of one combined string. Expected: one of the two canonical forms is accepted.

Use this when

• Greenhouse returns 422 phone_number is invalid on candidate create or update
• The phone came from a scraper, a PDF parse, or a form field with free-form formatting
• The same request succeeds when the phone field is left blank

Not for this skill when

• The 422 names a different field (first_name, email) - fix that field's format instead
• The API returns 401 or 403 (that is an auth problem, not a phone format problem)
• The number is genuinely missing - this skill is about formatting, not inventing a number for the candidate

Variant phrasings

• Greenhouse Harvest API rejects phone number format
• Greenhouse 422 invalid phone on candidate push
• Greenhouse API phone validation error for scraped numbers

Why it happens

Greenhouse validates the phone_number string server-side against a strict format. Scrapers return whatever formatting the source page used - spaces, dashes, parentheses, leading zeros, double-zero international prefixes - and the validator rejects anything outside its accepted shape instead of normalizing it.

Edge cases

• Double-zero international prefixes (0044 style) fail even though they are dialable; convert to the plus form.
• Extensions always fail validation; drop the extension or store it in a notes field.
• Some regions need the trunk zero dropped when the country code is present; blindly prepending a country code to a local number produces an invalid number.
• Do not guess a country code for a number you cannot place; a wrong code routes calls to the wrong country. Leave it blank and let a human confirm.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_T58Au5MdEuMy7hO6yjI8Ng