GovDash
Menu

Contracts

Create a contract

Creates a contract on the authenticated team and returns it. A contract number already used on the team answers conflict without creating anything.

posthttps://api.govdash.us/v1/contracts

Authorization

Authorizationstringheaderrequired

Your API key as a bearer token, for example Bearer gd_live_....

See Authentication for how to create a key.

Headers

govdash-versionenumheaderrequired

The dated API version this request is written against. Responses keep that version's shape after newer versions ship.

One of:2026-11-17

Body

application/json
titlestringrequired

Contract title.

classificationenumrequired

Data classification of the contract. Values above the token's classification ceiling are forbidden.

One of:UNCLASSIFIEDCUI

team_idstring

Team that will own the contract. Defaults to, and must be, the authenticated team.

contract_numberstring

Contract number.

awarding_agency_idstring

Identifier of an agency, from GET /v1/agencies.

funding_agency_idstring

Identifier of an agency, from GET /v1/agencies.

vendor_idstring

Identifier of the company that holds the contract.

start_datestring (date-time)

Start of the period of performance.

current_end_datestring (date-time)

End of the currently exercised period of performance.

ultimate_end_datestring (date-time)

End of the full period of performance, including all options.

award_valuenumber

Base award amount in US dollars.

obligated_amountnumber

Amount obligated by the agency in US dollars.

current_valuenumber

Current contract value in US dollars.

ceiling_valuenumber

Ceiling contract value in US dollars.

Response

201 · application/json

A contract award the team tracks. Amounts are null when the token's user cannot read sensitive contract details.

idstring

Contract identifier.

objectstring

Object type, always contract.

team_idstring

Team that owns the contract.

updated_atstring (date-time)

When the contract was last updated.

titlestring

Contract title.

contract_numberstring | null

Canonical contract identifier, derived from the contract, task order and subcontract numbers the contract has.

statusenum

Processing status of the contract.

One of:UNPROCESSEDPROCESSING_DOCUMENTSPROCESSING_AWARDFAILEDFINALIZEDDELETING

classificationenum

Data classification of the contract.

One of:UNCLASSIFIEDCUI

awarding_agency_idstring | null

Identifier of the awarding agency.

funding_agency_idstring | null

Identifier of the funding agency.

vendor_idstring | null

Identifier of the company that holds the contract.

start_datestring (date-time) | null

Start of the period of performance.

current_end_datestring (date-time) | null

End of the currently exercised period of performance.

ultimate_end_datestring (date-time) | null

End of the full period of performance, including all options.

past_performanceobject | null

Primary past performance, included in detail and write responses. Null when none is recorded. Use expand[]=past_performance.writeups on retrieval for write-up summaries.

Show child attributes
idstring
descriptionstring | null
business_partner_idsstring[]
writeupsobject[]
Show child attributes
idstring
namestring
is_primaryboolean
updated_atstring (date-time)

When the write-up was last updated.

award_valuenumber | null

Base award amount in US dollars.

obligated_amountnumber | null

Amount obligated by the agency in US dollars.

current_valuenumber | null

Current contract value in US dollars: the base and all exercised options.

ceiling_valuenumber | null

Ceiling contract value in US dollars: the value including all options.

Errors

Every error returns a stable error.code to branch on and an error.message that says what went wrong, like the examples below. See Errors for how to handle each one.

400bad_request

The body is missing a required field, has one this endpoint doesn't accept, or a field has the wrong type. The message names the field.

Invalid request body: Missing key at ["title"]

401unauthorized

The API key is missing, mistyped, revoked, or expired.

The bearer token is missing or invalid.

403forbiddenclassification_out_of_scope

The key's service account doesn't have the permission this needs, or your team's access has ended.

You do not have permission to perform this action.

404not_found

The record doesn't exist, belongs to another team, or is above the key's classification.

The requested resource was not found.

409conflict

A record like this already exists. Use it instead of creating another.

The request conflicts with an existing resource.

413payload_too_large

The request body is over 1 MB.

The request body must not exceed 1 MB.

422validation_failed

The request is well formed, but GovDash won't make this change. The message says why, when it can.

The request failed validation.

429rate_limited

You sent too many requests. Wait the seconds in the retry-after header, then retry.

This access token exceeded its write rate limit.

500internal_error

Something went wrong on GovDash's side, usually a bug. Retry with backoff, and check before retrying a create.

An unexpected error occurred.

503service_unavailable

GovDash is briefly unavailable and didn't run the request. Retry after retry-after.

The service is temporarily unavailable. Try again later.

post/v1/contracts

Create a contract

Sends a real POST request that changes your team's data.

Body

Starts with the required fields. The Body section of this page lists every field.

Bearer

Kept in this tab only. Use a key you can revoke.

Request
Response
Send the request to see the response.