Ph.Ats.Ashby

Imported from HappydanceDev/TestClient3_v17 (apps/umbraco/Ph.Ats.Ashby/AGENTS.md). Install upstream with npx skills add HappydanceDev/TestClient3_v17 --skill Ph.Ats.Ashby. Copyright stays with the author.

AGENTS.md

This project integrates Happydance with the Ashby ATS — RPC-style API, Basic auth, JSON envelopes ({success, results, errors}).

Use README.md for setup, API examples, and product-level context. This file should stay short and code-oriented.

What Matters Here

• HttpRest

  • AshbyRestClient (extends RestClientBase) — JSON helper for all read endpoints
  • AshbyTokenService — adds the Basic auth header (API key as username, blank password)

• Models

  • AshbyJob / AshbyJobPosting / AshbyJobBase — typed DTOs for jobPosting.info / jobPosting.list
  • AshbyJobDetail / AshbyCustomField / AshbyHiringTeamMember — the expanded parent job (see Custom Fields)
  • AshbyJobBoard — a board from jobBoard.list (see Internal vs External Jobs)
  • AshbyJobForm — focused subset returned by IAshbyFormService.GetJobForm (basic job + application form definition + survey definitions)
  • AshbyApplicationFormDefinition, AshbyFormField, AshbyFieldDefinition, AshbySelectableValue, AshbySurveyFormDefinition — Easy Apply form-shape DTOs
  • AshbyApplicationSubmission (and friends: AshbyApplicationFormPayload, AshbyFileUploadPart, AshbySurveyPayload) — mapper output
  • AshbySubmitResponse, AshbyApplicationInfo, AshbySurveySubmitResponse — typed responses for the three Easy Apply write endpoints
  • AshbyResponse<T> — the standard envelope; never bypass it

• Services

  • AshbyJobBoardService — fetches job postings + locations, used by the job import pipeline
  • AshbyFormService — owns the Easy Apply HTTP surface: GetJobForm, SubmitApplicationForm (multipart), GetApplicationInfo, SubmitSurvey
  • AshbyDryRunFormService — dev-only IAshbyFormService that suppresses writes (see README)
  • AshbyEnvelope.Unwrap<TInner, TOut> — translates the Ashby {success, results, errors} envelope onto ResponseWrapper<T>. Reuse it; do not hand-roll envelope parsing.
  • AshbyCustomFieldExtensions — generic typed accessors for job custom fields
  • AshbyPayRangeParser — parses pay ranges out of string-valued custom fields. Provided but not wired in; titles are tenant-specific (see README Salary).

• EasyApply

  • Contains the Ashby implementation of the generic Easy Apply application pipeline.
  • AshbyApplicationProviderAdapter is the coordinator (form → submit → survey fan-out). Keep orchestration here; do not push it into the form service.
  • AshbyApplicationFormBuilder owns the generic form/render contract assembly. It deserialises sourceData.RawQuestionnairePayload back into AshbyJobForm — the source serialises the typed model so schema drift surfaces in deserialization.
  • AshbyApplicationSubmissionMapper owns generic-submission → Ashby payload mapping. Both application-form and survey payloads are keyed by Ashby path/name in practice.

Custom Fields

Custom fields live on the parent job (requisition), not on the job posting. jobPosting.info only returns them when the request includes expand: ["job"], which GetJobInternal sends by default (gated by Ashby:ExpandJob, default true). The expanded object lands on AshbyJob.Job (AshbyJobDetail).

Besides customFields, the expand also brings customRequisitionId (e.g. REQ11515), the requisition status (Open/Closed — not the posting's Published status), confidential, brandId, and hiringTeam. Hiring team members carry staff names and emails — treat as private, do not publish.

Read values through the accessors, never by walking JsonElement directly:

job.CustomFields().GetLabel("Business Unit");     // "Sales"
job.CustomFields().GetLabels("Job Family");       // ["Field Sales"] — multi-select
job.CustomFields().GetDecimal("Scheduled Weekly Hours");
job.CustomFields().PublicFields().ToLabelDictionary();

• Ashby's value is polymorphic (string / bool / number / array of select keys), so it's held as JsonElement and every accessor returns null/default rather than throwing on an unexpected kind.
• Fields are matched on title, case-insensitively — Ashby ids are per-tenant UUIDs.
• For select fields prefer GetLabel; the raw value is an opaque key. GetString returns that key when you actually need it.
• isPrivate fields are excluded by PublicFields(). Filter through it before surfacing anything publicly.
• Tenant-specific named accessors belong in Ph.Import.Ats.Ashby/AshbyCustomFieldMappings.cs, not here. That file is a worked example — its titles come from one tenant and only GetRequisitionId is wired into the mapper. Repoint the rest before mapping them onto index fields.
• The mapper already folds every public custom field into AdditionalText, so values are searchable without a dedicated index field each.

Internal vs External Jobs

Ashby separates internal and external jobs by job board. Both jobPosting.list and jobPosting.info accept a jobBoardId, and AshbyConfig.JobBoardId is sent on both:

{ "listedOnly": true, "jobBoardId": "56cf15ce-0e9e-441a-a8af-0f8876f3322c" }
{ "jobPostingId": "ca6cee41-...", "jobBoardId": "56cf15ce-...", "expand": ["job"] }

Board ids come from jobBoard.list (IAshbyJobBoardService.GetJobBoards), which returns id, title and isInternal per board.

• Both calls must use the same board id. jobPosting.info returns posting data for a given board — apply links, descriptions — so listing from the internal board while fetching detail from the default external board would silently pair internal postings with external data. This is why the id is threaded through GetJobInternal as well as GetJobPostingsList.
• Per the OpenAPI spec, omitting jobBoardId does not mean "all boards": jobPosting.list defaults to "the primary external job board" and jobPosting.info "defaults to an external job board". Leaving it null is therefore the right setting for a public site, not a no-op.
• Filtering is applied by Ashby, server-side. Do not filter by board client-side; postings carry no board reference in the response, so there is nothing to filter on after the fact.
• The Job Board integration check lists every board with its id and isInternal flag, and errors if the configured id matches no enabled board (which would otherwise silently import zero jobs). Use it to find the id rather than calling the API by hand.

isListed / listedOnly is a separate gate — Ashby says unlisted postings "should not be displayed publicly", which also covers confidential and draft roles. The two combine: board scoping picks the audience, listedOnly picks what's publishable within it. Verified live: internal postings are still "listed", so { listedOnly: true, jobBoardId: "<internal board>" } does return the internal jobs — there is no need to relax listedOnly for an internal site.

Description Mapping

AshbyContentMapperService merges Ashby's three description parts into AzureJob.Description and leaves AdditionalDescription1-3 null. Ashby's descriptionHtml is exactly its three parts concatenated, so populating both stored the whole description twice. The posting's own suppressDescriptionOpening / suppressDescriptionClosing flags are honoured, and descriptionHtml is the fallback when a posting supplies no parts at all.

Submission Endpoint

We use applicationForm.submit, not application.create. Reasons are documented in the README. Do not switch endpoints without revisiting that decision.

Submission is multipart/form-data (one round trip with files inline). The presigned file.createFileUploadHandle JSON path is intentionally not implemented yet.

Ashby matches file submissions on path — the field's name, not our internal field id. ResolveFilePath prefers a sibling value's question key matched on FieldId, and drops a file whose only candidate path is indistinguishable from its id, rather than submitting a path Ashby would reject with invalid_field_provided_for_form.

Location Fields

Ashby declares Location as a single flat field — { "type": "Location", "path": "_systemfield_location" } — with no child fields. It expects { country, city, region } plain strings; Ashby geocodes them server-side.

• Do not send geo-location ids. The hosted careers page's autocomplete calls an internal ApiAutocompleteGeoLocation endpoint returning providerLocationId values (united_states/california/santa_monica). That is presentation only — applicationForm.submit takes plain strings, and the internal endpoint is not part of the public API.
• Display names and ISO codes both work. Verified live: { country: "GBR", region: "GB-LND", city: "London" } was stored by Ashby as United Kingdom / England / London.
• Any combination is accepted. Partial values geocode, so a CV giving only city + region is still useful.
• BuildLocationObject reads the structured value from the flat field, and falls back to discrete _systemfield_location.city-style siblings grouped by questionMetadata.questionKey — the form the mock submission generator emits. Blank parts never overwrite supplied ones, and a non-object value (a bare "Santa Monica, CA") yields no location rather than being coerced into one.

The per-type value shapes for Location, RichText, Score and EducationHistory are not in Ashby's official reference. They are documented in a third-party spec mirror, corroborated by the shapes EncodeValue already emits. Check there before assuming a field type is undocumented.

Survey Submission

After applicationForm.submit succeeds and there are survey answers to send, the adapter must:

1. Call application.info with the submittedFormInstanceId to resolve the real applicationId and candidateId.
2. For each AshbySurveyPayload, call surveySubmission.create.

Survey failures are best-effort — log a warning and continue. Do not fail the whole submit because EEO data didn't post.

Dependency Injection

• DI lives in Ph.Import.Ats.Ashby/AshbyComposer.cs.
• AshbyFormService is registered as a concrete class so the dry-run wrapper can inject it.
• IAshbyFormService is registered with a factory that swaps in AshbyDryRunFormService when AshbyConfig.DryRunSubmissions is true and the environment is not Production.

Tests

• Tests live in Ph.Ats.Ashby.Tests, not Ph.Tests.
• AshbyTestData builds reusable AshbyJobForm fixtures and a stub ICultureDictionaryFactory.
• Applications/ holds the Easy Apply tests: form-builder, submission-mapper, provider-adapter, form-source (matches the Greenhouse layout).
• Import-side tests sit at the project root: AshbyCustomFieldExtensionsTests, AshbyPayRangeParserTests, AshbySalaryMappingTests, AshbyDescriptionMappingTests, AshbyJobBoardRequestTests (which asserts the request bodies for jobBoardId / expand), and AshbyVacancyServiceSignalsTests.

Agent Guidance

• Prefer small, reversible changes in auth, config, or HTTP registration before touching the Easy Apply orchestration.
• Do not guess Ashby request/response shapes. Always check the Ashby reference first; the existing DTOs and the README JSON snippets are the local source of truth.
• The rendered reference pages truncate the request schema, so "the docs don't list parameter X" is not evidence that X doesn't exist. Append .md to any reference URL for the full OpenAPI JSON (~130–160KB) and search it directly — e.g. curl -s https://developers.ashbyhq.com/reference/jobpostinginfo.md | grep -A20 '"JobPostingInfoRequest"'. Both jobBoardId parameters were found this way after the rendered pages appeared to show no such option.
• Ashby returns HTTP 200 for almost everything, including business-level errors. Always check response.Success (or envelope.Success for the inner shape), never just the status code.
• Survey submissions use the field path/name. Ashby's API reference mentions field ids, but live submissions can reject the job-posting form field UUIDs with survey_form_field_not_found.
• Keep ATS-specific normalization and submission mapping here; keep orchestration and source selection out of this project.
• The form-source (AshbyDirectApplicationFormSource) lives in Ph.Import.Ats.Ashby/EasyApply/ — that's where the import-side wiring belongs, not in this project.
• Do not add Azure dependencies here for generic application forms. Azure-backed form seed resolution belongs in Ph.EasyApply.
• When adding new Ashby endpoints, prefer restClient.Post<AshbyResponse<T>> + AshbyEnvelope.Unwrap — not raw HttpClient calls. applicationForm.submit is the documented exception (multipart).