GET /v1/contacts/{id}

Get a contact

Access

Authenticated

contact:read

Cost

Free

Rate limit

120 / minute per account

Quota

None

One hydrated contact plus derived stats (lists, sequences).

Path parameters

id string required

max 16 chars

Responses

200 The contact
- 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
- candidateOf array of object required
  
  Every project this contact is a candidate of.
  - projectId string required
    
    The project id.
  - projectName string required
    
    The project name.
  - listId string required
    
    The shortlist within that project holding this candidate.
- stats object required
  
  Rollup counters for this contact.
  - lists integer required
    
    How many shortlists they are on.
  - sequences integer
    
    How many outreach sequences they are in. Absent means withheld, on the same rule as the engagement timestamps: a count leaks the same fact a name would.
  - contacted integer
    
    How many times they have been contacted. Absent means withheld.
- sequenceName string | null
  
  The sequence they are currently in, when there is one worth naming. Null when none, absent when withheld.
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 No such contact in this account
- 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.