---
title: "Cost this hire - one cited dossier"
method: POST
path: "/v1/jobs/cost-hire"
tags: ["Jobs"]
---

# Cost this hire - one cited dossier

`POST /v1/jobs/cost-hire`

## Request

- Base URL: `https://afriref.dev`
- URL: `https://afriref.dev/v1/jobs/cost-hire`
- Auth: one of:
  - API key in header `PAYMENT-SIGNATURE`
  - API key in header `X-PAYMENT`
  - API key in header `X-API-Key`

Cost this hire: one dossier for a salary in KE, NG - wage-floor verdict, employer and employee contributions (or PAYE net pay), employer cost, optional income tax and start date, every figure cited. Others refused free.

## Headers

- `X-Free-Trial` '1'

## Request body

- object
  - `country` 'ke' | 'ng', required: Covered here: KE, NG. Others refused free (coverage_gap).
  - `gross` number, required: Gross pay, local currency
  - `period` 'month' | 'year': Default month
  - `hours_per_week` number: Lets an hourly wage floor be checked: hourly = annual / (52 x hours)
  - `taxable_income` number: Annual taxable income: applies the statutory income-tax schedule (not derived from gross)
  - `start_date` string, date: Returns the first working day on or after it (national calendar)
  - `subdivision` string: Contribution region where held (e.g. CA-QC, DE-SN)
  - `receipt` boolean: Optional. Default false. When true, a paid HTTP 200 embeds an Ed25519-signed receipt (kind answer_receipt) the caller can file and later verify at /certified/public-key. Included in this answer's existing price — no extra charge. The field is omitted on unpaid 402 and on free 4xx refusals. This is not a series certified extract: GET /v1/certified/{country}/{series} is a different artifact, with its own price.

## Response `200`

Dossier: summary (employer_cost, contributions or net pay, wage verdict), wage_check, employment_cost or payroll, income_tax, start_date, not_included, evidence with official sources. Optional property receipt (schema AnswerReceipt, kind answer_receipt) is present only when the request set receipt:true and this response is a paid HTTP 200. Unpaid 402 and free 4xx refusals do not include receipt. Not a series certified extract (GET /v1/certified/{country}/{series}).

- object: Route-specific answer fields (verdict, workings, citations). receipt is optional and does not replace them. confidence_label, coverage_label and label_basis are on every answer an engine produced (rules: /label-rules).
  - `receipt` AnswerReceipt: Signed record of one paid answer computation. Present only on HTTP 200 when the request body set receipt:true. kind is answer_receipt. This object is not a series certified extract: GET /v1/certified/{country}/{series} returns a different artifact (value, citation, archived-source fingerprint, verification chain) at its own price. An answer receipt is included in the answer's existing price — no extra charge. It is not legal advice. It only covers the computation over the cited series as of each series' last_confirmed. Signing: build the object without signature, set receipt_id from the sha256 of that canonical JSON (first 24 hex chars, same pattern as extract_id), re-canonicalize including receipt_id, then sign. Verify with the free key at /certified/public-key — the same key and the same canonicalization rule as series certified extracts, not a second key.
    - `kind` 'answer_receipt', required
    - `receipt_id` string, required: First 24 hex characters of sha256 over the canonical JSON of this object before signature is attached. Same pattern as certified extract_id. The signature covers the object including receipt_id.
    - `answer` string, required: Route or tool name of the paid answer, e.g. vat, wage-check, working-days, settlement-date, income-tax, statutory-interest, payroll, employment-cost.
    - `request` object, required: Sanitized inputs echoed from the request. Properties are route-specific.
    - `result` object, required: Compact summary of the answer status and workings already returned on this 200. Properties are route-specific.
    - `cited_series` object[], required: Series the computation cited. Empty only when the answer cited none.
      - `country` string, required
      - `series_id` string, required
      - `value` union, required: Cited series value as held. Number, string, or null.
        - number
        - string
      - `last_confirmed` string, date, nullable, required: ISO date the cited series was last confirmed, or null.
      - `source_url` string, nullable, required
      - `source_sha256` string, nullable, required: Hex fingerprint from provenance when available, otherwise null.
    - `issued_at` string, date-time, required: ISO8601 timestamp when the receipt was issued.
    - `limitations` string[], required: Always populated. States that this receipt is not a series certified extract and is not legal advice, and that it only covers the computation over the cited series as of each series' last_confirmed.
    - `signature` object, required: Ed25519 signature over the canonical JSON of this receipt with the signature field omitted. Same key_id and same canonicalization rule as series certified extracts, published at /certified/public-key. Not a second production key.
      - `alg` 'Ed25519', required
      - `key_id` string, required: Same key_id as GET /certified/public-key and as series certified extracts.
      - `public_key` string, required: Absolute URL of GET /certified/public-key.
      - `signed_payload` string, required: canonical JSON of answer_receipt: keys sorted recursively, no whitespace (see /certified/public-key)
      - `value` string, required: Base64 Ed25519 signature.
  - `confidence_label` 'high' | 'medium' | 'low': Derived from source type, verification age, stale. Rules: /label-rules
  - `coverage_label` 'ready' | 'partial' | 'gap': ready=complete, partial=limited, gap=no number. Rules: /label-rules
  - `label_basis` object: Inputs and rule ids behind both labels

## Other responses

- `400`: Invalid body (free, before payment)
- `402`: Payment Required
- `404`: Country not served by this brand (free)
- `422`: coverage_gap: not answerable in full - refused free, never charged

---

[API](https://skmtc.dev/afriref/apis/afriref-pan-african-government-reference-data.md) · [All operations](https://skmtc.dev/afriref/apis/afriref-pan-african-government-reference-data/llms.txt) · [OpenAPI document](https://skmtc.dev/afriref/apis/afriref-pan-african-government-reference-data/revisions/d78528e9f644?raw)