GET /v1/contacts

List contacts

Access

Authenticated

contact:read

Cost

Free

Rate limit

60 / minute per account

Quota

None

Your account contacts, filtered, sorted, and hydrated with keyset pagination. Sort by any DB-backed field (addedAt, source, doNotContact, lists, lastContacted, nextContacted, touches); name/login/avatar are projected from search and are not server-sortable. Page with limit + the opaque cursor from a prior nextCursor. Segments come from the inList and doNotContact filters plus the returned total. Pass q to search server-side by developer id. Set format=csv for the human export, or format=bundle for the portable JSON bundle POST /v1/contacts/import can re-import (both capped at 5000 rows). Add list=<shortlistId> to make the bundle a shortlist bundle, carrying the list header and its sequence config. Filter by how a contact landed on a list with memberSource, narrowed to one subject with memberSourceRef: memberSource=managed&memberSourceRef=<managedAgentId> returns the candidates that managed agent handed over, and adding list scopes it to the shortlist they were handed to. memberSourceRef without memberSource is a 400. Every returned list chip carries that membership source and sourceRef alongside the contact-level source.

Query parameters

limit integer default: 25

min 1, max 100
cursor string

max 512 chars
sort string

addedAtsourcedoNotContactlistslastContactednextContactedtouches
order string

ascdesc
list string

max 16 chars
inList string

truefalse
doNotContact string

truefalse
hidden string

truefalse
source string

searchfeedimportmanualapilookupown-companycompetitor
memberSource string

searchfeedimportmanualmanagedapi
memberSourceRef string

max 200 chars
developerId array

max 100 items
q string

max 200 chars
format string

jsoncsvbundle

Responses

200 A page of hydrated contacts, a portable bundle, or a CSV export
Option 1 · ContactListResponse
- contacts array of HydratedContact required
  
  This page of contacts.
  
  id string required
  
  The contact id within your account. Different from `developerId`: the developer is the person, the contact is your record of them.
  
  developerId string required
  
  The developer this contact refers to. Portable: it means the same thing in every account, and it is what every developer endpoint takes.
  
  source string required
  
  How this contact entered your account. Provenance, not a grouping — use projects and shortlists to group, and do not encode categories into it.
  
  sourceDetail string | null required
  
  Free-text detail behind `source`, for example the query that produced them. Null when there is none.
  
  addedBy string | null required
  
  The member id or API key id that added them. Null when unknown.
  
  addedByEmail string | null required
  
  That actor’s email address, for display. Null when unknown.
  
  addedByName string | null required
  
  That actor’s display name. Null when unknown.
  
  doNotContactAt string | null required
  
  When they were marked do-not-contact, as an ISO 8601 instant. Non-null suppresses outreach to them.
  
  hiddenAt string | null required
  
  When they were hidden, as an ISO 8601 instant. A hidden contact drops out of the default list AND out of future search results, but keeps its sequences, lists and history.
  
  addedAt string required
  
  When they were first saved, as an ISO 8601 instant.
  
  updatedAt string required
  
  When the contact record last changed, as an ISO 8601 instant.
  
  lists array of object required
  
  Every shortlist this contact is currently on.
  
  id string required
  
  The shortlist id.
  
  name string required
  
  The shortlist name.
  
  source string required
  
  How the contact landed on THIS list. Per-membership: the same contact on three lists carries three answers, which is why it is here and not on the contact.
  
  sourceRef string | null required
  
  The subject behind `source` when there is one, for example the agent that handed the candidate over. Null otherwise.
  
  pinnedRepo string | null required
  
  The `owner/repo` a person on this account pinned as THE relevant piece of work for this developer on THIS list — the repo the card leads with and the {repo_name} anchor outreach from this list uses. Per-membership, because the relevant repo for one role is not the relevant repo for another. Null when nobody has pinned one and none was resolved at add time.
  
  firstContactedAt string | null
  
  When outreach first reached them. Null means never; ABSENT means withheld (see this object’s description).
  
  lastContactedAt string | null
  
  When outreach last reached them. Null means never; absent means withheld.
  
  nextContactedAt string | null
  
  When the next scheduled outreach step is due. Null when nothing is scheduled; absent means withheld.
  
  nextContactAt string | null
  
  Alias of `nextContactedAt`, kept for existing clients. Same value and same absent/null rule.
  
  touchCount integer
  
  How many outreach touches they have received. Absent means withheld.
  
  contactedCount integer
  
  How many distinct outreach conversations they have been part of. Absent means withheld.
  
  rolesCount integer required
  
  How many roles this contact has been put forward for.
  
  developer DeveloperProfile required
  
  The developer’s profile, hydrated at read time. Null when nothing resolves for this developer id.
  
  developerId string required
  
  The stable Vamo identifier for this developer (GitHub's numeric user id, stringified). This is the id every other endpoint takes: facets, reports, contacts, shortlists, steering. Use it, not `login` — a login can be renamed and then belongs to someone else.
  
  max 64 chars
  
  login string required
  
  The GitHub handle as of the last snapshot. Display it, do not key on it: handles are renameable and reusable.
  
  max 200 chars
  
  name string | null required
  
  Display name as the developer set it on GitHub. Null when they set none.
  
  max 200 chars
  
  avatarUrl string | null required
  
  GitHub avatar image URL. Null when absent.
  
  max 2048 chars
  
  currentRole string | null required
  
  A single free-text role line for the developer. Best-effort and unverified; `professional.title` is the LinkedIn-sourced equivalent when we hold a LinkedIn overlay.
  
  max 200 chars
  
  organization object | null required
  
  The developer's current employer, when one is known. Null means we hold no employer, NOT that they are unemployed.
  
  name string required
  
  The organization name as recorded.
  
  max 200 chars
  
  logoUrl string | null required
  
  Organization logo URL, null when absent.
  
  max 2048 chars
  
  university string | null required
  
  Most recent institution, when the LinkedIn overlay carries education. Null when unknown.
  
  max 200 chars
  
  profiles object required
  
  Where this developer can be found, plus the addresses if you have already bought them.
  
  github string required
  
  The developer’s github.com profile URL. Always present — GitHub is the identity anchor for every developer in the index.
  
  max 2048 chars
  
  linkedin string | null required
  
  LinkedIn profile URL when we hold a GitHub↔LinkedIn match for this person. Null for the large majority of developers: only a minority of the indexed GitHub population carries a LinkedIn overlay, so null means "no match held", never "no LinkedIn account".
  
  max 2048 chars
  
  emails array of string
  
  Every email address we hold for this developer. Present ONLY when this account has already paid to reveal them and the purchase is still within its cache window; a base search or profile read never populates it. ABSENT is not the same as "no email": absent means you have not bought it, while `hasEmail: false` means we hold none. These are addresses we have OBSERVED — from public commit metadata and cached GitHub profile data — and we do not check deliverability, so treat the order as meaningless and expect some to bounce. Buy them with the `contact.emails` facet.
  
  max 50 items
  
  hasEmail boolean required
  
  Whether we hold at least one email address for this developer. It says we have an address on file, not that the address works — we do not check deliverability. The addresses themselves are never returned by a search or a base profile read: this boolean is the free signal, and the paid `contact.emails` facet is the only way to get them. Use `hasEmail` on a search request to filter to developers we hold an address for, without paying.
  
  bio string | null required
  
  The developer’s GitHub bio, verbatim. Null when empty.
  
  max 5000 chars
  
  location object | null required
  
  Self-reported location, plus our geocoding of it. Self-reported and never verified against anything: a developer can leave it stale or blank. Null when we hold nothing at all.
  
  raw string | null required
  
  The location string exactly as the developer typed it on GitHub ("SF / remote").
  
  max 200 chars
  
  city string | null required
  
  City resolved from `raw` by geocoding. Null when `raw` was empty or unresolvable.
  
  max 200 chars
  
  country string | null required
  
  Country resolved from `raw`. Null when `raw` was empty or unresolvable.
  
  max 200 chars
  
  joinedAt string | null required
  
  When the GitHub account was created, as an ISO 8601 instant. Null when unknown.
  
  max 40 chars
  
  stats object | null required
  
  Snapshot counts and standing for this developer. These are from our index and go stale between refreshes; `GET /v1/developers/{id}` returns live GitHub equivalents alongside the contribution garden when you need current numbers. Null when we hold no stats at all.
  
  followers integer | null required
  
  GitHub follower count at snapshot time.
  
  min 0, max 100000000
  
  following integer | null required
  
  How many accounts this developer follows, at snapshot time.
  
  min 0, max 100000000
  
  totalStars integer | null required
  
  Sum of stargazers across the repositories ATTRIBUTED to this developer — the same set as `repos`, so the count can never contradict the list. Owned and contributed-to repositories both count; forks do not.
  
  min 0, max 100000000
  
  crackedScore number | null required
  
  Devrank: a 0–100 standing for this developer within the WHOLE indexed GitHub developer population (tens of millions of accounts), not within a language, region, or seniority peer group — so it is not a like-for-like comparison between two candidates for the same role. It is derived from the follower/contribution graph, is recomputed upstream on its own schedule, and carries no version on the wire, so the same developer can read differently across two snapshots. It contributes one term to the page-local `score` and backs the `levers.github.minDevrank` filter. Null when the developer is not in the devrank table.
  
  tier string | null required
  
  The upstream provider’s own coarse label for `crackedScore` (for example "Elite"). The label set is the provider’s and is not a Vamo-stable vocabulary — treat it as display text and branch on `crackedScore` if you need a threshold. Null when the developer is not in the devrank table.
  
  max 200 chars
  
  repos array of object required
  
  The developer’s top ATTRIBUTED public repositories — owned or authored-into, forks excluded — stars descending, capped at 12. This is a sample of their best work, not a complete repository list, and it is not an answer to "why did this person match my query" — read `evidence.matchedRepos` for that.
  
  max 12 items
  
  name string required
  
  The repository name alone, without the owner (`linux`).
  
  max 200 chars
  
  fullName string required
  
  GitHub `owner/name`. This is the join key: an evidence repo and a profile repo describing the same repository carry the same `fullName`.
  
  max 200 chars
  
  description string | null required
  
  The repository's own GitHub description, verbatim. Null when it has none.
  
  max 5000 chars
  
  language string | null required
  
  GitHub's primary language for the repository. Null when GitHub reports none (an empty or docs-only repo); never inferred from the code.
  
  max 200 chars
  
  stars integer required
  
  Stargazer count at the time this profile was snapshotted, not at request time.
  
  min 0, max 100000000
  
  commits integer
  
  How many commits THIS developer authored to this repository over the trailing year. This is the difference between a project they wrote and a project they landed one drive-by fix in — a 385k-star repository with 4 of their commits is not their work. Absent when no commit signal was captured; 0 means none in the trailing year, which for older dormant work is not the same as none ever.
  
  min 0, max 100000000
  
  owned boolean
  
  True when the repository sits under the developer's own account, false when it is someone else's (an organisation's or another person's) and they are a contributor to it. This is the difference between "they built this" and "they committed to this", and it is the ONLY honest basis for crediting a repository's stars to a person. Absent when no ownership signal was captured; treat absent as unknown, never as false.
  
  url string required
  
  The public github.com URL of the repository.
  
  max 2048 chars
  
  languages array of string required
  
  Distinct primary languages across the developer’s repositories, at most 8. Presence means they have shipped public code in it; the list is not ranked by proficiency and carries no line counts.
  
  max 8 items
  
  experience array of object required
  
  Employment history from the LinkedIn overlay, newest first. Empty for any developer we hold no LinkedIn match for, which is most of them.
  
  max 25 items
  
  title string | null
  
  Job title, on an experience entry.
  
  max 200 chars
  
  company string | null
  
  Employer name, on an experience entry.
  
  max 200 chars
  
  school string | null
  
  Institution name, on an education entry.
  
  max 200 chars
  
  degree string | null
  
  Degree awarded, on an education entry.
  
  max 200 chars
  
  fieldOfStudy string | null
  
  Field of study, on an education entry.
  
  max 200 chars
  
  startDate string | null
  
  Start date exactly as the source rendered it. Free text, NOT a normalised date: expect "2019", "Jan 2019" and "2019-01" from different records. Parse defensively.
  
  max 200 chars
  
  endDate string | null
  
  End date in the same unnormalised free-text form as `startDate`. Absent or null on a current role.
  
  max 200 chars
  
  current boolean | null
  
  The source's own "still there" flag. Set on experience entries; null on education entries.
  
  education array of object required
  
  Education history from the LinkedIn overlay. Empty for any developer we hold no LinkedIn match for.
  
  max 25 items
  
  title string | null
  
  Job title, on an experience entry.
  
  max 200 chars
  
  company string | null
  
  Employer name, on an experience entry.
  
  max 200 chars
  
  school string | null
  
  Institution name, on an education entry.
  
  max 200 chars
  
  degree string | null
  
  Degree awarded, on an education entry.
  
  max 200 chars
  
  fieldOfStudy string | null
  
  Field of study, on an education entry.
  
  max 200 chars
  
  startDate string | null
  
  Start date exactly as the source rendered it. Free text, NOT a normalised date: expect "2019", "Jan 2019" and "2019-01" from different records. Parse defensively.
  
  max 200 chars
  
  endDate string | null
  
  End date in the same unnormalised free-text form as `startDate`. Absent or null on a current role.
  
  max 200 chars
  
  current boolean | null
  
  The source's own "still there" flag. Set on experience entries; null on education entries.
  
  professional object | null
  
  LinkedIn-sourced professional scalars, present only when we hold a LinkedIn match for this developer. Absent or null for the majority of developers, which says nothing about their employment — only that we hold no overlay.
  
  headline string | null required
  
  The LinkedIn headline, verbatim.
  
  max 5000 chars
  
  title string | null required
  
  Current job title per LinkedIn, e.g. "Chief Technology Officer".
  
  max 200 chars
  
  company string | null required
  
  Current employer per LinkedIn. Distinct from the GitHub-sourced `organization` field, and the two disagree often — LinkedIn is usually the fresher of the two.
  
  max 200 chars
  
  seniority string | null required
  
  A coarse seniority label from the LinkedIn overlay ("c-level", "senior", …). Free text from the source, not a Vamo enum; do not switch on the exact string.
  
  max 200 chars
  
  expertise array of string required
  
  Self-declared skill tags from the LinkedIn profile. Claimed, not demonstrated — the demonstrated equivalent is the repositories under `repos` and `evidence`.
  
  max 25 items
- nextCursor string | null required
  
  Opaque keyset token for the next page: pass it back as `cursor`. Null on the last page. Do not parse or construct it.
- total integer required
  
  How many contacts match the current filters in total, not just on this page. This is the number to build a segment count from.
Option 2 · ContactBundle
- version number required
  
  Bundle format version. Bumped only on a breaking change; an importer rejects a version it does not know rather than guessing.
  
  1
- kind string required
  
  `shortlist` = one named list and its members, and importing recreates that list. `contacts` = an arbitrary filtered selection with no list of its own.
  
  shortlistcontacts
- source object required
  
  Where this bundle came from.
  
  accountRef string required
  
  The exporting account, as an opaque string. Provenance only: an import always writes to the account holding the credential, never to this one.
  
  max 200 chars
  
  shortlistRef string | null required
  
  The exporting account’s shortlist id, when this is a shortlist bundle. Provenance only; a fresh id is minted on import.
  
  max 200 chars
  
  exportedAt string required
  
  When the bundle was exported, as an ISO 8601 instant.
  
  max 40 chars
- shortlist object | null required
  
  The list header. Present exactly when `kind` is `shortlist`, null otherwise.
  
  name string required
  
  The list name. This IS used on import: it is the name of the list recreated in your account.
  
  max 80 chars
  
  description string | null required
  
  The list description. Null when it had none.
  
  max 280 chars
  
  kind string required
  
  What kind of shortlist this was in the source account.
  
  freestandingprojectpipeline
  
  memberCount integer required
  
  How many members the source list had. Can exceed `members.length`, which is capped per bundle.
  
  sequence object | null required
  
  The outreach sequence attached to the source list, carried as metadata only. Importing recreates the list and its members, never the sequence.
  
  ref string required
  
  The source account’s sequence id. Provenance only.
  
  max 200 chars
  
  name string required
  
  The sequence name.
  
  max 80 chars
  
  jitterMinutes integer required
  
  The random spread applied to send times, in minutes.
  
  pausedAt string | null required
  
  When the sequence was paused, as an ISO 8601 instant. Null when it was running.
  
  max 40 chars
- members array of object required
  
  The contacts in this bundle, up to 5000.
  
  max 5000 items
  
  ref string required
  
  The contact id in the SOURCE account. Provenance and deduplication only; it is never inserted here and means nothing in your account.
  
  max 200 chars
  
  developerId string required
  
  The portable identity: a GitHub developer id, which means the same thing in every account. This is the ONLY field the importer resolves on.
  
  max 200 chars
  
  developer object | null required
  
  The developer’s profile as the source account saw it. Null when nothing resolved. Never carries an email address, even if the source account had bought one: an address stays with the account that paid for it.
  
  developerId string required
  
  The stable Vamo identifier for this developer (GitHub's numeric user id, stringified). This is the id every other endpoint takes: facets, reports, contacts, shortlists, steering. Use it, not `login` — a login can be renamed and then belongs to someone else.
  
  max 64 chars
  
  login string required
  
  The GitHub handle as of the last snapshot. Display it, do not key on it: handles are renameable and reusable.
  
  max 200 chars
  
  name string | null required
  
  Display name as the developer set it on GitHub. Null when they set none.
  
  max 200 chars
  
  avatarUrl string | null required
  
  GitHub avatar image URL. Null when absent.
  
  max 2048 chars
  
  currentRole string | null required
  
  A single free-text role line for the developer. Best-effort and unverified; `professional.title` is the LinkedIn-sourced equivalent when we hold a LinkedIn overlay.
  
  max 200 chars
  
  organization object | null required
  
  The developer's current employer, when one is known. Null means we hold no employer, NOT that they are unemployed.
  
  name string required
  
  The organization name as recorded.
  
  max 200 chars
  
  logoUrl string | null required
  
  Organization logo URL, null when absent.
  
  max 2048 chars
  
  university string | null required
  
  Most recent institution, when the LinkedIn overlay carries education. Null when unknown.
  
  max 200 chars
  
  profiles object required
  
  Where this developer can be found, plus the addresses if you have already bought them.
  
  github string required
  
  The developer’s github.com profile URL. Always present — GitHub is the identity anchor for every developer in the index.
  
  max 2048 chars
  
  linkedin string | null required
  
  LinkedIn profile URL when we hold a GitHub↔LinkedIn match for this person. Null for the large majority of developers: only a minority of the indexed GitHub population carries a LinkedIn overlay, so null means "no match held", never "no LinkedIn account".
  
  max 2048 chars
  
  emails array of string
  
  Every email address we hold for this developer. Present ONLY when this account has already paid to reveal them and the purchase is still within its cache window; a base search or profile read never populates it. ABSENT is not the same as "no email": absent means you have not bought it, while `hasEmail: false` means we hold none. These are addresses we have OBSERVED — from public commit metadata and cached GitHub profile data — and we do not check deliverability, so treat the order as meaningless and expect some to bounce. Buy them with the `contact.emails` facet.
  
  max 50 items
  
  hasEmail boolean required
  
  Whether we hold at least one email address for this developer. It says we have an address on file, not that the address works — we do not check deliverability. The addresses themselves are never returned by a search or a base profile read: this boolean is the free signal, and the paid `contact.emails` facet is the only way to get them. Use `hasEmail` on a search request to filter to developers we hold an address for, without paying.
  
  bio string | null required
  
  The developer’s GitHub bio, verbatim. Null when empty.
  
  max 5000 chars
  
  location object | null required
  
  Self-reported location, plus our geocoding of it. Self-reported and never verified against anything: a developer can leave it stale or blank. Null when we hold nothing at all.
  
  raw string | null required
  
  The location string exactly as the developer typed it on GitHub ("SF / remote").
  
  max 200 chars
  
  city string | null required
  
  City resolved from `raw` by geocoding. Null when `raw` was empty or unresolvable.
  
  max 200 chars
  
  country string | null required
  
  Country resolved from `raw`. Null when `raw` was empty or unresolvable.
  
  max 200 chars
  
  joinedAt string | null required
  
  When the GitHub account was created, as an ISO 8601 instant. Null when unknown.
  
  max 40 chars
  
  stats object | null required
  
  Snapshot counts and standing for this developer. These are from our index and go stale between refreshes; `GET /v1/developers/{id}` returns live GitHub equivalents alongside the contribution garden when you need current numbers. Null when we hold no stats at all.
  
  followers integer | null required
  
  GitHub follower count at snapshot time.
  
  min 0, max 100000000
  
  following integer | null required
  
  How many accounts this developer follows, at snapshot time.
  
  min 0, max 100000000
  
  totalStars integer | null required
  
  Sum of stargazers across the repositories ATTRIBUTED to this developer — the same set as `repos`, so the count can never contradict the list. Owned and contributed-to repositories both count; forks do not.
  
  min 0, max 100000000
  
  crackedScore number | null required
  
  Devrank: a 0–100 standing for this developer within the WHOLE indexed GitHub developer population (tens of millions of accounts), not within a language, region, or seniority peer group — so it is not a like-for-like comparison between two candidates for the same role. It is derived from the follower/contribution graph, is recomputed upstream on its own schedule, and carries no version on the wire, so the same developer can read differently across two snapshots. It contributes one term to the page-local `score` and backs the `levers.github.minDevrank` filter. Null when the developer is not in the devrank table.
  
  tier string | null required
  
  The upstream provider’s own coarse label for `crackedScore` (for example "Elite"). The label set is the provider’s and is not a Vamo-stable vocabulary — treat it as display text and branch on `crackedScore` if you need a threshold. Null when the developer is not in the devrank table.
  
  max 200 chars
  
  repos array of object required
  
  The developer’s top ATTRIBUTED public repositories — owned or authored-into, forks excluded — stars descending, capped at 12. This is a sample of their best work, not a complete repository list, and it is not an answer to "why did this person match my query" — read `evidence.matchedRepos` for that.
  
  max 12 items
  
  name string required
  
  The repository name alone, without the owner (`linux`).
  
  max 200 chars
  
  fullName string required
  
  GitHub `owner/name`. This is the join key: an evidence repo and a profile repo describing the same repository carry the same `fullName`.
  
  max 200 chars
  
  description string | null required
  
  The repository's own GitHub description, verbatim. Null when it has none.
  
  max 5000 chars
  
  language string | null required
  
  GitHub's primary language for the repository. Null when GitHub reports none (an empty or docs-only repo); never inferred from the code.
  
  max 200 chars
  
  stars integer required
  
  Stargazer count at the time this profile was snapshotted, not at request time.
  
  min 0, max 100000000
  
  commits integer
  
  How many commits THIS developer authored to this repository over the trailing year. This is the difference between a project they wrote and a project they landed one drive-by fix in — a 385k-star repository with 4 of their commits is not their work. Absent when no commit signal was captured; 0 means none in the trailing year, which for older dormant work is not the same as none ever.
  
  min 0, max 100000000
  
  owned boolean
  
  True when the repository sits under the developer's own account, false when it is someone else's (an organisation's or another person's) and they are a contributor to it. This is the difference between "they built this" and "they committed to this", and it is the ONLY honest basis for crediting a repository's stars to a person. Absent when no ownership signal was captured; treat absent as unknown, never as false.
  
  url string required
  
  The public github.com URL of the repository.
  
  max 2048 chars
  
  languages array of string required
  
  Distinct primary languages across the developer’s repositories, at most 8. Presence means they have shipped public code in it; the list is not ranked by proficiency and carries no line counts.
  
  max 8 items
  
  experience array of object required
  
  Employment history from the LinkedIn overlay, newest first. Empty for any developer we hold no LinkedIn match for, which is most of them.
  
  max 25 items
  
  title string | null
  
  Job title, on an experience entry.
  
  max 200 chars
  
  company string | null
  
  Employer name, on an experience entry.
  
  max 200 chars
  
  school string | null
  
  Institution name, on an education entry.
  
  max 200 chars
  
  degree string | null
  
  Degree awarded, on an education entry.
  
  max 200 chars
  
  fieldOfStudy string | null
  
  Field of study, on an education entry.
  
  max 200 chars
  
  startDate string | null
  
  Start date exactly as the source rendered it. Free text, NOT a normalised date: expect "2019", "Jan 2019" and "2019-01" from different records. Parse defensively.
  
  max 200 chars
  
  endDate string | null
  
  End date in the same unnormalised free-text form as `startDate`. Absent or null on a current role.
  
  max 200 chars
  
  current boolean | null
  
  The source's own "still there" flag. Set on experience entries; null on education entries.
  
  education array of object required
  
  Education history from the LinkedIn overlay. Empty for any developer we hold no LinkedIn match for.
  
  max 25 items
  
  title string | null
  
  Job title, on an experience entry.
  
  max 200 chars
  
  company string | null
  
  Employer name, on an experience entry.
  
  max 200 chars
  
  school string | null
  
  Institution name, on an education entry.
  
  max 200 chars
  
  degree string | null
  
  Degree awarded, on an education entry.
  
  max 200 chars
  
  fieldOfStudy string | null
  
  Field of study, on an education entry.
  
  max 200 chars
  
  startDate string | null
  
  Start date exactly as the source rendered it. Free text, NOT a normalised date: expect "2019", "Jan 2019" and "2019-01" from different records. Parse defensively.
  
  max 200 chars
  
  endDate string | null
  
  End date in the same unnormalised free-text form as `startDate`. Absent or null on a current role.
  
  max 200 chars
  
  current boolean | null
  
  The source's own "still there" flag. Set on experience entries; null on education entries.
  
  professional object | null
  
  LinkedIn-sourced professional scalars, present only when we hold a LinkedIn match for this developer. Absent or null for the majority of developers, which says nothing about their employment — only that we hold no overlay.
  
  headline string | null required
  
  The LinkedIn headline, verbatim.
  
  max 5000 chars
  
  title string | null required
  
  Current job title per LinkedIn, e.g. "Chief Technology Officer".
  
  max 200 chars
  
  company string | null required
  
  Current employer per LinkedIn. Distinct from the GitHub-sourced `organization` field, and the two disagree often — LinkedIn is usually the fresher of the two.
  
  max 200 chars
  
  seniority string | null required
  
  A coarse seniority label from the LinkedIn overlay ("c-level", "senior", …). Free text from the source, not a Vamo enum; do not switch on the exact string.
  
  max 200 chars
  
  expertise array of string required
  
  Self-declared skill tags from the LinkedIn profile. Claimed, not demonstrated — the demonstrated equivalent is the repositories under `repos` and `evidence`.
  
  max 25 items
  
  provenance object required
  
  How the contact arose in the source account.
  
  source string required
  
  How this contact entered the SOURCE account.
  
  searchfeedimportmanualapilookupown-companycompetitor
  
  sourceDetail string | null required
  
  Free-text detail behind `source`. Null when there was none.
  
  max 1000 chars
  
  addedAt string required
  
  When they were added in the source account, as an ISO 8601 instant.
  
  max 40 chars
  
  addedByName string | null required
  
  The display name of whoever added them in the source account. Deliberately a name and never an id or an email address.
  
  max 200 chars
  
  doNotContact boolean required
  
  Whether they were marked do-not-contact in the source account.
  
  hidden boolean required
  
  Whether they were hidden in the source account.
  
  engagement object required
  
  The source account’s outreach history with them, for context only.
  
  firstContactedAt string | null
  
  When the source account first contacted them. Null means never; ABSENT means withheld.
  
  max 40 chars
  
  lastContactedAt string | null
  
  When the source account last contacted them. Null means never; absent means withheld.
  
  max 40 chars
  
  contactedCount integer
  
  How many times the source account contacted them. Absent means withheld.
  
  rolesCount integer required
  
  How many roles they were put forward for in the source account.
  
  activeSequences integer
  
  How many live sequences they were in. Absent means withheld.
  
  sequenceNames array of string
  
  Names of those sequences. Absent means withheld.
  
  max 100 items
  
  listNames array of string required
  
  The source account’s list names this contact belonged to. Labels for context, not ids and not instructions.
  
  max 100 items
400 Invalid filters or export too large
- code string required
  
  Stable machine-readable error code. Branch on this, never on the numeric status.
  
  bad_requestunauthorizedsignature_requiredpayment_requiredforbiddennot_foundconflictgonepayload_too_largeunprocessable_entitytoo_many_requestsinternal_errornot_implementedbilling_unavailablenot_contactablemailbox_link_unavailablemailbox_requiredmail_engine_unavailablewebhook_publisher_unavailabledatabase_unavailableclient_error
- message string required
  
  Human-readable explanation of the refusal.
- status integer required
  
  The HTTP status code, repeated in the body.
- remedy object
  
  A self-serve path forward, when one exists (a 402 points at the credit top-up).
  - kind string required
    
    What kind of remedy this is, so a client can route it: whether the caller can clear the condition through the API, or a person must act in the web app.
    
    topupconnect_mailbox
  - url string required
    
    Where to go to clear the condition: an API path, or a web app page when only a person can.
401 No or invalid credential
- code string required
  
  Stable machine-readable error code. Branch on this, never on the numeric status.
  
  bad_requestunauthorizedsignature_requiredpayment_requiredforbiddennot_foundconflictgonepayload_too_largeunprocessable_entitytoo_many_requestsinternal_errornot_implementedbilling_unavailablenot_contactablemailbox_link_unavailablemailbox_requiredmail_engine_unavailablewebhook_publisher_unavailabledatabase_unavailableclient_error
- message string required
  
  Human-readable explanation of the refusal.
- status integer required
  
  The HTTP status code, repeated in the body.
- remedy object
  
  A self-serve path forward, when one exists (a 402 points at the credit top-up).
  - kind string required
    
    What kind of remedy this is, so a client can route it: whether the caller can clear the condition through the API, or a person must act in the web app.
    
    topupconnect_mailbox
  - url string required
    
    Where to go to clear the condition: an API path, or a web app page when only a person can.
403 Missing contact:read
- code string required
  
  Stable machine-readable error code. Branch on this, never on the numeric status.
  
  bad_requestunauthorizedsignature_requiredpayment_requiredforbiddennot_foundconflictgonepayload_too_largeunprocessable_entitytoo_many_requestsinternal_errornot_implementedbilling_unavailablenot_contactablemailbox_link_unavailablemailbox_requiredmail_engine_unavailablewebhook_publisher_unavailabledatabase_unavailableclient_error
- message string required
  
  Human-readable explanation of the refusal.
- status integer required
  
  The HTTP status code, repeated in the body.
- remedy object
  
  A self-serve path forward, when one exists (a 402 points at the credit top-up).
  - kind string required
    
    What kind of remedy this is, so a client can route it: whether the caller can clear the condition through the API, or a person must act in the web app.
    
    topupconnect_mailbox
  - url string required
    
    Where to go to clear the condition: an API path, or a web app page when only a person can.
404 The list filter id is unknown
- code string required
  
  Stable machine-readable error code. Branch on this, never on the numeric status.
  
  bad_requestunauthorizedsignature_requiredpayment_requiredforbiddennot_foundconflictgonepayload_too_largeunprocessable_entitytoo_many_requestsinternal_errornot_implementedbilling_unavailablenot_contactablemailbox_link_unavailablemailbox_requiredmail_engine_unavailablewebhook_publisher_unavailabledatabase_unavailableclient_error
- message string required
  
  Human-readable explanation of the refusal.
- status integer required
  
  The HTTP status code, repeated in the body.
- remedy object
  
  A self-serve path forward, when one exists (a 402 points at the credit top-up).
  - kind string required
    
    What kind of remedy this is, so a client can route it: whether the caller can clear the condition through the API, or a person must act in the web app.
    
    topupconnect_mailbox
  - url string required
    
    Where to go to clear the condition: an API path, or a web app page when only a person can.