GovDash
Menu

Companies

Create a company

Creates a company, UNCLASSIFIED unless a classification is given, in the authenticated team's Data Library and returns it. A name, UEI or CAGE code already used on the team answers conflict without creating anything.

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

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
locationobject
Show child attributes
address_line_1string | nullrequired

First line of the street address.

address_line_2string | nullrequired

Second line of the street address.

citystring | nullrequired

City.

statestring | nullrequired

State or region name.

state_codestring | nullrequired

State or region code, such as VA.

postal_codestring | nullrequired

Postal or ZIP code.

countrystring | nullrequired

Country name.

country_codestring | nullrequired

Country code, such as US.

classificationenum

Data classification of the company. Defaults to UNCLASSIFIED. Values above the token's classification ceiling are forbidden.

One of:UNCLASSIFIEDCUI

namestringrequired

Legal name, unique within the team. At most 250 characters and not only whitespace.

relationship_typeenumrequired

How the company relates to the team.

One of:JOINT_VENTURE_MEMBERSUBSIDIARYPARENT_COMPANYVENDORCUSTOMERUNKNOWN

dba_namestring

Doing-business-as or trade name.

website_urlstring

Website URL.

relationship_notesstring

Free-text notes on the relationship with the team.

ueistring

12-character SAM Unique Entity Identifier, unique within the team.

cage_codestring

5-character CAGE code, unique within the team.

Response

201 · application/json

A company in the team's Data Library.

idstring

Company identifier.

objectstring

Object type, always company.

classificationenum

Data classification of the company.

One of:UNCLASSIFIEDCUI

namestring

Legal name, unique within the team.

dba_namestring | null

Doing-business-as or trade name.

relationship_typeenum

How the company relates to the team.

One of:PRIME_CONTRACTORSUB_CONTRACTORTEAM_ARRANGEMENT_MEMBERJOINT_VENTURE_MEMBERSUBSIDIARYPARENT_COMPANYUNKNOWNSUPPLIERCUSTOMERCOMPETITORVENDORINCUMBENTOUR_TEAM

relationship_notesstring | null

Free-text notes on the relationship with the team.

website_urlstring | null

Website URL.

ueistring | null

SAM Unique Entity Identifier.

cage_codestring | null

CAGE code.

duns_numberstring | null

DUNS number.

updated_atstring (date-time)

When the company was last updated.

locationobject | null

Primary address. null when none is recorded.

Show child attributes
address_line_1string | null

First line of the street address.

address_line_2string | null

Second line of the street address.

citystring | null

City.

statestring | null

State or region name.

state_codestring | null

State or region code, such as VA.

postal_codestring | null

Postal or ZIP code.

countrystring | null

Country name.

country_codestring | null

Country code, such as US.

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 ["name"]

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/companies

Create a company

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.