GovDash
Menu

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

  1. Page through GET /v1/people and index the people by email, ignoring case.
  2. For each contact, look up the email. If nobody matches, create the person with POST /v1/people.
  3. If someone matches and a field differs, send only the changed fields with PATCH /v1/people/{id}.
  4. If a create or update returns 409 conflict, another person already has that full name. Log it and review it by hand.

Fields

FieldCreateUpdate
first_nameRequired. 1 to 250 characters.Can be replaced, not cleared.
last_nameRequired. 1 to 250 characters.Can be replaced, not cleared.
emailOptionalnull clears it.
phoneOptionalnull clears it.
title, middle_name, suffix, linkedin_urlNot acceptednull 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.

curlcurl
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"}'
sync-people.tsTypeScript
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)
}
sync_people.pyPython
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.