GovDash
Menu

People

Create a person

Creates a person, UNCLASSIFIED unless a classification is given, on the authenticated team and returns it. A first and last name already used on the team answers conflict without creating anything.

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

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
first_namestringrequired

First (given) name.

last_namestringrequired

Last (family) name. The full name must be unique within the team.

emailstring

Email address.

phonestring

Phone number.

classificationenum

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

One of:UNCLASSIFIEDCUI

Response

201 · application/json

A person in the team's Data Library.

idstring

Person identifier.

objectstring

Object type, always person.

classificationenum

Data classification of the person.

One of:UNCLASSIFIEDCUI

namestring

Full display name, combined from the name parts.

titlestring | null

Name prefix, title, or rank such as Dr., CPL, or Gen.

first_namestring | null

First (given) name.

middle_namestring | null

Middle name.

last_namestring | null

Last (family) name.

suffixstring | null

Name suffix such as Jr., Sr., or III.

emailstring | null

Email address.

phonestring | null

Phone number.

linkedin_urlstring | null

LinkedIn profile URL.

updated_atstring (date-time)

When the person was last updated.

employmentsobject[]

Companies and agencies the person works for. Employers the token cannot read are left out.

Show child attributes
company_idstring | null

Identifier of the employing company.

agency_idstring | null

Identifier of the employing agency.

is_primaryboolean

Whether this is the person's primary employment.

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 ["first_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/people

Create a person

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.