---
agentTools:
  projectIndex: https://developers.pinpointhq.com/llms.txt
---

# 1.0.28

## US address fields

Address handling on [Applications](https://developers.pinpointhq.com/reference/get-applications), [Candidates](https://developers.pinpointhq.com/reference/get-candidates) and [Job Seekers](https://developers.pinpointhq.com/reference/get-job-seekers) changed in **May 2026** so that the fields you read and write are semantically correct for US records.

Previously, US addresses reused `address2` to hold the city and `town` to hold the state, which meant integrations had to know about the quirk. Now:

* A new `state_province` attribute holds the state for US records, and `null` for non-US records.
* `town` always holds the city, for every country.
* `address2` holds address line 2 for non-US records, and returns `null` for US records.
* Writing `address2` on a US record is rejected. Writing `state_province` on a non-US record is rejected. Both restrictions are temporary and will be lifted once the underlying address model is migrated.
* Changing `country` across the US/non-US boundary requires you to supply the new address fields in the same request, otherwise the request is rejected.
* Validation errors that used to be reported against `town` for US records are now reported against `state_province`.

If you read `address2` or `town` for US candidates, update your mapping to `town` (city) and `state_province` (state).

## New: Background Checks (`api/v1/background_checks`)

* **New resource** — [`index`](https://developers.pinpointhq.com/reference/get-background-checks), [`show`](https://developers.pinpointhq.com/reference/get-background-check), [`create`](https://developers.pinpointhq.com/reference/post-background-checks) and [`update`](https://developers.pinpointhq.com/reference/put-background-check) are available, so a background check provider can push requests and results into Pinpoint against an application *(Apr 2026)*
* Attributes: `name`, `status`, `result`, `result_url`, `external_uid`, `provider_code`, `is_completed`, `result_details` (read-only), `application_id`, `created_at`, `updated_at`
* `provider_code` identifies your service. It must be one of the registered custom providers — use `example_check` while you build
* Set `is_completed: true` when you send the final `status` and `result`. This applies the configured tags to the application and sends the relevant notifications, so only send it once the check is genuinely finished
* `result_url` is the link to your report (PDF or results page in your own UI). `result` is the overall outcome or score, e.g. `clear`, `consider`, `4/5`
* Updates are only permitted on checks created through the API by a custom provider. Checks owned by a native Pinpoint integration or an integration plugin are read-only over the API, and the `application` relationship cannot be reassigned after creation
* Filters: `status`, `provider_code`, `external_uid`, `application_id`, `created_at`, `updated_at`. Sortable on `created_at` and `updated_at`. `?include=application` is supported
* See the [Background Checks guide](https://developers.pinpointhq.com/docs/background-checks) for the end-to-end flow

## New: One-way Video Interviews (`api/v1/one_way_video_interviews`)

* **New read-only resource** — [`index`](https://developers.pinpointhq.com/reference/get-one-way-video-interviews) and [`show`](https://developers.pinpointhq.com/reference/get-one-way-video-interview), for reporting on one-way (asynchronous) video interviews *(May 2026)*
* Attributes: `status` (`Completed` / `Incomplete`), `sent_at`, `responded_at`, `interview_name`, `interview_description`, `num_questions`, `interview_stage`, `application_id`, `created_at`, `updated_at`
* Extra attributes (request with `extra_fields`): `total_time_spent_mins` — how long the candidate spent recording; `time_to_complete_hours` — elapsed hours between the invite being sent and the candidate responding
* Filters: `status`, `application_id`, `job_id`, `job_visibility`. Sortable on `created_at` and `updated_at`. `?include=application` is supported

## Applications (`api/v1/applications`)

* Added `uuid` attribute and filter — a stable identifier for the application that is safe to share with third parties, unlike the sequential `id` *(May 2026)*
* Added `external_system_reference` (read, write, filter) — store the ID or reference the record came from in your own system, and look records back up by it *(Jun 2026)*
* Added `preferred_name` (read/write) *(Jun 2026)*
* Added `state_province` and changed US address field semantics — see the heads-up above *(May 2026)*
* `hired_at` is now **writable** on create and update *(Apr 2026)*
* Added `ai_score` — a read-only object containing Pinpoint's AI Match Score for the application (`status`, `score`, `verdict`, `strengths`, `concerns`, `interview_focus`, `scored_at`). Returns `null` when AI Match Score is not enabled for the company or no score exists yet *(May 2026)*
* Added `documents_base64` write-only array — attach one or more supporting documents on create or update, each as `{ "data": "<base64 data URI>", "filename": "report.pdf" }`. Accepted types: `pdf`, `doc`, `docx`, `png`, `jpeg`, `xls`, `xlsx`, `pptx`, `mp4`, `mov`, `txt`. Maximum 10 MB per file *(Apr 2026)*
* Added `cover_letter_base64_data` and `cover_letter_base64_filename` write-only attributes — upload a cover letter the same way as a CV. Accepted types: `pdf`, `doc`, `docx`, `txt`, `rtf`. Maximum 30 MB *(May 2026)*
* A CV can now be added or replaced on the [Update Application](https://developers.pinpointhq.com/reference/put-application) endpoint, not just on create. Useful for backfilling a resume that was missed during a migration, or replacing the wrong file. Assigning a CV replaces any existing attachment *(Jun 2026)*
* Added `job_posting` relationship, settable on **create** — record which posting the application came through. The posting must belong to the same job as the application, otherwise the request is rejected. The relationship cannot be changed on update *(Jun 2026)*
* Added `furthest_stage` relationship (read-only) — the furthest stage the application has reached, which may be ahead of the current `stage` if the candidate was moved back *(May 2026)*
* Added `candidate_phone` filter — look an application up by the candidate's phone number, alongside the existing `candidate_email` filter *(Apr 2026)*
* Added `concealed` filter — restrict results to applications a viewer is allowed to see under blind screening, or to the concealed ones only *(May 2026)*
* Applications created via the API can now be blocked as **cross-job** duplicates. If the company has opted out of cross-job duplicate candidates and the email address has already applied to a different job at that company, the create request is rejected with a clear error naming the conflicting application, instead of the duplicate being created and then obfuscated *(Jun 2026)*
* Fixed: tag writes that omit `tag` now return a validation error. `add_tag_with_context`, `add_tags_with_context` and `remove_tag_with_context` previously returned `200` while silently persisting nothing. Tag context names are also now sanitised *(May 2026)*
* Fixed: the optional per-stage-group `<stage_group>_stage_at` attributes (enabled by a company setting) no longer leak another company's stage group names into your response, now honour sparse fieldsets (`fields[applications]`), and no longer error when a stage group name begins with a digit *(Apr and Jul 2026)*

## Candidates (`api/v1/candidates`)

* Added `blocked` attribute (read/write) and a `blocked` filter — read or set whether a candidate is blocked. Candidates with no value recorded are treated as not blocked when filtering *(May 2026)*
* Added `preferred_name` (read/write) *(Jun 2026)*
* Added `external_system_reference` (read, write, filter) *(Jun 2026)*
* Added `state_province` and changed US address field semantics — see the heads-up above *(May 2026)*
* Added `phone` filter — look a candidate up by phone number *(Apr 2026)*

## Job Seekers (`api/v1/job_seekers`)

* Added `preferred_name` (read/write) *(Jun 2026)*
* Added `external_system_reference` (read, write, filter) *(Jun 2026)*
* Added `state_province` and changed US address field semantics — see the heads-up above *(May 2026)*
* Fixed: tag writes that omit `tag` now return a validation error rather than a silent `200` *(May 2026)*

## Jobs (`api/v1/jobs`)

* Added `uuid` attribute and filter — a stable identifier for the job that is safe to share with third parties *(Apr 2026)*
* Added `external_system_reference` (read, write, filter) *(Jun 2026)*
* `requisition_id` is now **filterable**, so you can find a job by the requisition reference you already hold *(Jun 2026)*
* `hiring_manager_user` and `recruitment_manager_user` relationships are now **writable** on [create](https://developers.pinpointhq.com/reference/post-jobs) and [update](https://developers.pinpointhq.com/reference/put-job). Previously these were documented as relationships but writes did not take effect *(Apr 2026)*
* Added `assigned_onboarding_candidate_owner_user_id` and `assigned_onboarding_candidate_owner_user_email` extra attributes (request with `extra_fields`) — the user who will be set as candidate owner when someone is moved into onboarding on this job *(Jul 2026)*
* When creating a job without a `diversity_monitoring` value, the company's default diversity monitoring setting is now applied instead of the field being left unset *(Jun 2026)*
* Fixed: `filled_at` is now derived from the job's audit trail rather than from `closed_at`, so it reflects when the job was actually marked as filled. Previously it returned the close date, and returned `null` for jobs that were filled without being closed *(May 2026)*
* Fixed: the `search` filter no longer returns an empty result set for common search terms. Search is now scoped to your own jobs before matching, so results are no longer lost to a global result-size limit *(May 2026)*

## Job Postings (`api/v1/job_postings`)

* `url` and `application_form_url` now use the company's custom careers domain when one is configured, instead of always returning the `*.pinpointhq.com` subdomain. The same fix applies to the `postings.json` job feed *(Jun 2026)*

## Comments (`api/v1/comments`)

* Added **delete** — `DELETE /api/v1/comments/{id}` removes a comment created through the API *(Jul 2026)*
* `category` is now accepted on write with the value `note`. Previously sending it returned a `422`. Comments created via the API are always notes, so the value is advisory *(May 2026)*

## Users (`api/v1/users`)

* Added `last_sign_in_at` (read-only) — when the user last signed in to Pinpoint *(Jun 2026)*
* Added `email` filter — look a user up by email address *(Jun 2026)*
* Fixed: `access_group_id` is now returned on [read](https://developers.pinpointhq.com/reference/get-users) requests, and is resolved for the company the API key belongs to. It was previously writable but absent from responses *(May 2026)*

## Candidate Surveys (`api/v1/candidate_surveys`)

* Added `answers` sideload (read-only) — fetch a survey together with its answers using `?include=answers` *(May 2026)*

## Candidate Assessments (`api/v1/candidate_assessments`)

* [Creating an assessment](https://developers.pinpointhq.com/reference/post-candidate-assessments) without an explicit `status` now defaults to `pending` instead of failing *(Apr 2026)*
* The `status` attribute documentation now lists every allowed value *(Apr 2026)*

## Equality Monitoring Categories (`api/v1/equality_monitoring_categories`)

* Added `equality_monitoring_template_id` attribute and filter, plus an `equality_monitoring_template` relationship — you can now tell which template a category belongs to and filter categories by template *(Jun 2026)*

## `external_system_reference` on structural resources

`external_system_reference` was added across the resources most often used for mapping data from another system *(Jun 2026)*:

* [Departments](https://developers.pinpointhq.com/reference/get-departments) — read, write, filter
* [Locations](https://developers.pinpointhq.com/reference/get-locations) — read, write, filter
* [Structure Custom Group Ones](https://developers.pinpointhq.com/reference/get-structure-custom-group-ones) — read, write, filter
* [Hiring Workflows](https://developers.pinpointhq.com/reference/get-hiring-workflows) — read, filter
* Stages — read, filter (available when sideloaded, e.g. `?include=stage`)

## Performance

* [Custom Attributes](https://developers.pinpointhq.com/reference/get-custom-attributes) reads now eager-load the data behind `value`, `option_value` and `option_label`, removing a large number of per-record queries on big result sets *(May 2026)*
* The `job_visibility` filter on [Interviews](https://developers.pinpointhq.com/reference/get-interviews) uses a faster query path, which materially reduces response times for companies with a lot of interview history *(May 2026)*