How do I automate overseas allowances for contractor proposals?
Automate overseas allowance lookups by mapping each proposal location to the appropriate government rate source, querying that source for a specific date, and saving the returned rates alongside your pricing assumptions. Allowances API provides normalized DSSR and DTMO data so your estimating workflow can retrieve JSON instead of maintaining separate spreadsheets and PDF extracts.
The rate lookup is one part of the estimate. Your proposal team still determines which allowances apply, the calculation basis, and the contract-specific treatment of each cost.
1. Define the proposal inputs before retrieving rates
Create an input record for each assignment or travel scenario:
| Input | Why it matters |
|---|---|
| Country and city or post | Rates are location specific; a country average can hide differences between posts. |
| Rate source and allowance type | DTMO per diem and DSSR allowances are separate datasets. |
| Pricing basis date | A repeatable lookup needs an explicit date. |
| Travel or assignment period | Rates can change within the period being estimated. |
| Headcount and eligible days | These are estimating inputs, separate from the published rate. |
| Calculation and escalation assumptions | Reviewers need to see how the rate became a proposed cost. |
Keep employee names and other personal information out of rate requests. Location, date, and allowance type are sufficient for these lookups.
2. Select the source for each cost component
Use the solicitation, contract instructions, and your approved estimating policy to decide which source applies. Do not select a table solely because it has a rate for the destination.
- DTMO OCONUS per diem: lodging, meal rates, incidentals, and related footnotes for the selected location.
- DSSR foreign per diem: State Department foreign-area per diem, where that is the required basis.
- DSSR allowances: post allowance (COLA), hardship, danger pay, and other supported overseas allowance categories.
A city can appear in both DTMO and DSSR. Preserve the source in your estimate rather than merging their values. The federal allowance source finder explains the source families.
3. Retrieve an allowance for an explicit date
For example, this request retrieves DSSR post allowance data for Nairobi. Set PRICING_DATE to your approved basis date in ISO format, such as 2026-11-01, and make your API key available as ALLOWANCES_API_KEY in your environment:
curl --fail-with-body --get \
'https://api.allowancesapi.com/v1/dssr/allowances/KE/location/Nairobi' \
--header "X-API-Key: ${ALLOWANCES_API_KEY}" \
--data-urlencode "date=${PRICING_DATE}" \
--data-urlencode 'type=cola' \
--data-urlencode 'verification_url=true'
Inspect the returned results, location, and allowance-specific effective date before using the value. The requested date and the published effective date can differ: a lookup asks which published rate applies as of the requested date. When returned, verification_url links to the official source for checking the result.
For hardship or danger pay, make a separate request with type=hardship or type=danger_pay. The API reference documents the response fields and the separate per diem endpoints. Historical access depends on your subscription; check pricing before designing a historical estimating workflow.
4. Apply the calculation for each allowance
Do not multiply every returned percentage by total salary. A DSSR post allowance percentage has its own calculation basis; it is not a generic salary uplift. See the State Department's post allowance information and the COLA calculator for the relevant workflow.
Keep lodging, meals, hardship, danger pay, and post allowance as separate estimate lines. Record units, calculation bases, eligible periods, and any exclusions. A missing result or null field should trigger review rather than silently becoming a zero-dollar allowance.
For a future performance period, distinguish published rates from your own escalation assumptions. An effective-date lookup does not forecast future government publications.
5. Save a pricing snapshot and review changes
Save the request parameters, retrieval timestamp, returned JSON, effective dates, available source links, and the version of your calculation assumptions with the proposal workpapers. Never save the API key in that snapshot.
Deduplicate requests for the same source, location, date, and type. Handle authentication and quota errors explicitly; use bounded retries for temporary failures. Before a proposal revision, retrieve a new snapshot and show reviewers which rate inputs changed. Preserve the original estimate rather than overwriting its basis.
Where Allowances API fits
Allowances API supplies structured rate inputs for proposal tools, ERP systems, and spreadsheet workflows. It is an independent service, not affiliated with a government agency. A successful lookup does not establish employee eligibility, cost allowability, or proposal approval.
Start with one post and one allowance, compare the response with the official source, then connect the lookup to your estimating model. For an assistant-driven workflow, see how to connect an AI assistant to government travel rates.