Import people into GovDash
This is an inbound sync: your external contact system is the source, and GovDash is the destination. For the reverse direction, see Export opportunities from GovDash. In this example you'll keep GovDash people in step with contacts from another system. You'll read your GovDash people once, match each contact to a person by email, create the person if they're missing, and update them if their details changed.
Steps
- Page through
GET /v1/peopleand index the people by email, ignoring case. - For each contact, look up the email. If nobody matches, create the person with
POST /v1/people. - If someone matches and a field differs, send only the changed fields with
PATCH /v1/people/{id}. - If a create or update returns
409 conflict, another person already has that full name. Log it and review it by hand.
Fields
| Field | Create | Update |
|---|---|---|
first_name | Required. 1 to 250 characters. | Can be replaced, not cleared. |
last_name | Required. 1 to 250 characters. | Can be replaced, not cleared. |
email | Optional | null clears it. |
phone | Optional | null clears it. |
title, middle_name, suffix, linkedin_url | Not accepted | null clears them. |
The full name must be unique within your team. New people are UNCLASSIFIED unless you send classification. This example only adds and changes people. To remove someone who left your source system, call DELETE /v1/people/{id}.
Code
The curl commands list people, create one, and update one. Set PERSON_ID from the list or create response. Run the TypeScript sample with npx tsx sync-people.ts on Node.js 20 or later. The Python sample needs requests, which you install with pip install requests.
curl "$GOVDASH_API_URL/v1/people" \
-H "Authorization: Bearer $GOVDASH_API_KEY" \
-H "govdash-version: $GOVDASH_API_VERSION"
curl "$GOVDASH_API_URL/v1/people" \
-X POST \
-H "Authorization: Bearer $GOVDASH_API_KEY" \
-H "govdash-version: $GOVDASH_API_VERSION" \
-H "Content-Type: application/json" \
-d '{"first_name": "Ada", "last_name": "Lovelace", "email": "[email protected]"}'
curl "$GOVDASH_API_URL/v1/people/$PERSON_ID" \
-X PATCH \
-H "Authorization: Bearer $GOVDASH_API_KEY" \
-H "govdash-version: $GOVDASH_API_VERSION" \
-H "Content-Type: application/json" \
-d '{"phone": "+1 555 0100"}'const apiVersion = process.env.GOVDASH_API_VERSION
if (!apiVersion) throw new Error("Set GOVDASH_API_VERSION")
const baseUrl = process.env.GOVDASH_API_URL
const apiKey = process.env.GOVDASH_API_KEY
if (!baseUrl || !apiKey)
throw new Error("Set GOVDASH_API_URL and GOVDASH_API_KEY")
const headers = {
Authorization: `Bearer ${apiKey}`,
"govdash-version": apiVersion,
}
type Contact = {
firstName: string
lastName: string
email: string
phone?: string
}
type Person = {
id: string
first_name: string | null
last_name: string | null
email: string | null
phone: string | null
}
async function call(method: string, path: string, body?: unknown) {
const response = await fetch(`${baseUrl}${path}`, {
method,
headers: {
...headers,
...(body === undefined ? {} : { "Content-Type": "application/json" }),
},
body: body === undefined ? undefined : JSON.stringify(body),
})
return { status: response.status, body: await response.json() }
}
async function peopleByEmail(): Promise<Map<string, Person>> {
const people = new Map<string, Person>()
let cursor: string | null = null
do {
const query = new URLSearchParams()
if (cursor !== null) query.set("cursor", cursor)
const { status, body } = await call("GET", `/v1/people?${query}`)
if (status !== 200) throw new Error(`${status} ${body.error.code}`)
for (const { node } of body.edges as { node: Person }[]) {
if (node.email !== null) people.set(node.email.toLowerCase(), node)
}
cursor = body.pageInfo.hasNextPage ? body.pageInfo.endCursor : null
} while (cursor !== null)
return people
}
async function syncContact(people: Map<string, Person>, contact: Contact) {
const existing = people.get(contact.email.toLowerCase())
if (existing === undefined) {
const payload: Record<string, string> = {
first_name: contact.firstName,
last_name: contact.lastName,
email: contact.email,
}
if (contact.phone !== undefined) payload.phone = contact.phone
const { status, body } = await call("POST", "/v1/people", payload)
if (status === 201) return console.log("created", body.id)
if (status === 409) return console.warn("name already taken", contact)
throw new Error(`${status} ${body.error.code}: ${body.error.message}`)
}
const changes: Record<string, string> = {}
if (existing.first_name !== contact.firstName)
changes.first_name = contact.firstName
if (existing.last_name !== contact.lastName)
changes.last_name = contact.lastName
if (contact.phone !== undefined && existing.phone !== contact.phone)
changes.phone = contact.phone
if (Object.keys(changes).length === 0)
return console.log("unchanged", existing.id)
const { status, body } = await call(
"PATCH",
`/v1/people/${existing.id}`,
changes,
)
if (status === 200) return console.log("updated", existing.id)
if (status === 409) return console.warn("name already taken", contact)
throw new Error(`${status} ${body.error.code}: ${body.error.message}`)
}
const contacts: Contact[] = [
{
firstName: "Ada",
lastName: "Lovelace",
email: "[email protected]",
phone: "+1 555 0100",
},
]
const people = await peopleByEmail()
for (const contact of contacts) {
await syncContact(people, contact)
}import os
import requests
BASE_URL = os.environ["GOVDASH_API_URL"]
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["GOVDASH_API_KEY"]
session.headers["govdash-version"] = os.environ["GOVDASH_API_VERSION"]
def fail(response):
error = response.json()["error"]
raise RuntimeError(f"{response.status_code} {error['code']}: {error['message']}")
def people_by_email():
people = {}
params = {}
while True:
response = session.get(f"{BASE_URL}/v1/people", params=params)
if not response.ok:
fail(response)
page = response.json()
for edge in page["edges"]:
person = edge["node"]
if person["email"] is not None:
people[person["email"].lower()] = person
if not page["pageInfo"]["hasNextPage"]:
return people
params["cursor"] = page["pageInfo"]["endCursor"]
def sync_contact(people, contact):
existing = people.get(contact["email"].lower())
if existing is None:
payload = {
"first_name": contact["first_name"],
"last_name": contact["last_name"],
"email": contact["email"],
}
if contact.get("phone"):
payload["phone"] = contact["phone"]
response = session.post(f"{BASE_URL}/v1/people", json=payload)
if response.status_code == 201:
print("created", response.json()["id"])
elif response.status_code == 409:
print("name already taken", contact)
else:
fail(response)
return
changes = {
key: contact[key]
for key in ("first_name", "last_name", "phone")
if contact.get(key) is not None and existing[key] != contact[key]
}
if not changes:
print("unchanged", existing["id"])
return
response = session.patch(f"{BASE_URL}/v1/people/{existing['id']}", json=changes)
if response.status_code == 200:
print("updated", existing["id"])
elif response.status_code == 409:
print("name already taken", contact)
else:
fail(response)
contacts = [
{"first_name": "Ada", "last_name": "Lovelace", "email": "[email protected]", "phone": "+1 555 0100"},
]
people = people_by_email()
for contact in contacts:
sync_contact(people, contact)Notes
- People are matched by email, ignoring case. If two people share an email, the samples use the last one listed.
- Sync calls count against your rate limits. Reading your people costs one read per page, and each contact costs at most one write.