> ## Documentation Index
> Fetch the complete documentation index at: https://docs.signalhire.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Candidate Object: Data Structure & Fields

> Full structure of the candidate object returned by the Person API.

The `candidate` object contains the full profile data returned by the Person API for a successfully matched individual. It appears in two contexts:

* In the **callback payload** (async mode) — inside each array item where `status` is `success`
* In the **response body** (sync mode, `withoutWaterfall: true`) — same structure, returned directly without a callback

The object includes personal details, professional experience, education, contact information, social profiles, and additional data such as certifications, publications, and patents. Not all fields are guaranteed to be populated — availability depends on the data present in SignalHire's database for a given profile. Fields with no data are returned as `null` or an empty array `[]`.

Below is a full description of all fields.

## Full Example

```json theme={null}
{
  "uid": "abc123def456gh789ijk012lmn345op6",
  "fullName": "John Doe",
  "gender": null,
  "headLine": "Founder / Owner Doe Law Offices",
  "summary": "Experienced lawyer with expertise in family law and criminal defense.",
  "photo": {
    "url": "https://media.cdn.com/image/C4A03AQH-wVPhNTP7cw/0/1577297087305"
  },
  "locations": [
    { "name": "New York, New York, United States" }
  ],
  "skills": ["Civil Litigation", "Corporate Law", "Litigation"],
  "contacts": [
    { "type": "email", "value": "john.doe@doelaw.com", "rating": 100, "subType": "work" },
    { "type": "email", "value": "john.doe@gmail.com", "rating": 100, "subType": "personal" },
    { "type": "phone", "value": "+1 555-123-4567", "rating": 100, "subType": "work_phone", "info": "..." }
  ],
  "social": [
    { "type": "li", "link": "https://www.linkedin.com/in/john-doe-12345678", "rating": 100 },
    { "type": "fb", "link": "https://www.facebook.com/johndoe", "rating": 100 }
  ],
  "experience": [
    {
      "position": "Owner / Managing Attorney",
      "company": "Doe Law Offices LLC",
      "location": null,
      "current": true,
      "started": "2015-01-01T00:00:00+00:00",
      "ended": null,
      "summary": "Helping clients navigate family law and criminal defense cases.",
      "companyUrl": "https://www.linkedin.com/company/doe-law-offices",
      "companySize": "1-10",
      "staffCount": 5,
      "industry": "Law Practice",
      "website": "http://www.doe-law.com"
    }
  ],
  "education": [
    {
      "faculty": "Law",
      "university": "New York University School of Law",
      "url": "https://www.linkedin.com/school/nyu-law/",
      "startedYear": 2005,
      "endedYear": 2008,
      "degree": ["JD"]
    }
  ],
  "language": [
    { "name": "English", "proficiency": "Native or bilingual" },
    { "name": "Portuguese", "proficiency": "Professional working" }
  ],
  "organization": [
    { "name": "New York Bar Association", "position": null, "startDate": "January 2015", "endDate": null }
  ],
  "certification": [
    { "name": "Responsible AI", "license": "10748511", "authority": "Google" }
  ],
  "course": [
    { "name": "Strategic Management [FGV]" }
  ],
  "project": [
    { "name": "Project Name", "description": null, "url": "url", "startDate": "July 2017", "endDate": null }
  ],
  "publication": [
    { "name": "TRIAL Magazine", "description": "...", "issue": "American Association for Justice", "url": null, "date": "July 2006" }
  ],
  "patent": [
    { "name": "Secure geolocation-based data access control", "issue": "US12147159", "patentNumber": null, "date": "November 2024" }
  ],
  "honorAward": [
    { "name": "Award name", "description": "...", "issue": "Great British Entrepreneur Awards", "date": "June 2024" }
  ]
}
```

## Top-Level Fields

<ParamField body="uid" type="string">
  Unique 32-character SignalHire profile identifier.
</ParamField>

<ParamField body="fullName" type="string">
  Full name of the person.
</ParamField>

<ParamField body="gender" type="string | null">
  Gender of the person. Possible values: `male`, `female`, or `null` if not available.
</ParamField>

<ParamField body="headLine" type="string | null">
  Professional headline.
</ParamField>

<ParamField body="summary" type="string | null">
  Profile bio or summary text.
</ParamField>

<ParamField body="photo" type="object | null">
  Profile photo. Contains a single `url` string field, or `null` if no photo is available.
</ParamField>

<ParamField body="locations" type="array">
  List of location objects. Each object contains a single `name` string field (e.g. `"New York, New York, United States"`).
</ParamField>

<ParamField body="skills" type="array of strings">
  List of professional skills.
</ParamField>

<ParamField body="experienceYears" type="integer | null">
  Total years of experience across all roles.
</ParamField>

## contacts

Array of contact items. When `withoutContacts: true` is used, this field is always returned as an empty array `[]`. Each item has the following fields:

<ParamField body="type" type="string">
  Contact type. Possible values: `email`, `phone`, `link`, `skype`, `telegram`, `whatsapp`, `viber`, `hangouts`, `wechat`, `qq`, `icq`, `gtalk`, `aim`, `windows_live_messenger`, `yahoo_messenger`.
</ParamField>

<ParamField body="value" type="string">
  The contact value (email address, phone number, username, or URL depending on type).
</ParamField>

<ParamField body="rating" type="integer">
  Confidence score indicating contact validity. Possible values: `70` (likely valid) or `100` (high confidence).
</ParamField>

<ParamField body="subType" type="string | null">
  For emails: `work`, `personal`, or `null`. For phones: `work_phone`, `mobile`, or `null`. For other types: `null`.
</ParamField>

## social

Array of social profile links. When `withoutContacts: true` is used, only the LinkedIn profile link is returned (if available). Each item has the following fields:

<ParamField body="type" type="string">
  Platform identifier. Possible values:

  | Value | Platform       |
  | ----- | -------------- |
  | `li`  | LinkedIn       |
  | `fb`  | Facebook       |
  | `tw`  | Twitter        |
  | `x`   | X              |
  | `ig`  | Instagram      |
  | `gh`  | GitHub         |
  | `yt`  | YouTube        |
  | `pt`  | Pinterest      |
  | `so`  | Stack Overflow |
  | `be`  | Behance        |
  | `dr`  | Dribbble       |
  | `sc`  | SoundCloud     |
  | `vm`  | Vimeo          |
  | `rd`  | Reddit         |
  | `qu`  | Quora          |
  | `xi`  | XING           |
  | `vi`  | Viadeo         |
  | `vk`  | ВКонтакте      |
  | `ok`  | Odnoklassniki  |
  | `am`  | About.me       |
  | `gr`  | Gravatar       |
  | `wp`  | WordPress      |
  | `wc`  | WordPress.com  |
  | `wo`  | WordPress.org  |
  | `tm`  | Tumblr         |
  | `fs`  | Foursquare     |
  | `ss`  | SlideShare     |
  | `mu`  | Meetup         |
  | `fc`  | Flickr         |
  | `bl`  | Blogger        |
  | `lj`  | Live Journal   |
  | `ms`  | MySpace        |
  | `lf`  | Last.fm        |
  | `gp`  | Google+        |
  | `kl`  | Klout          |
  | `ba`  | Badoo          |
  | `bb`  | Bebo           |
  | `dg`  | Digg           |
  | `tg`  | Tagged         |
  | `dl`  | Delicious      |
  | `su`  | StumbleUpon    |
  | `ni`  | Ning           |
  | `re`  | Renren         |
  | `ye`  | Yelp           |
  | `fl`  | Freelancer     |
  | `ta`  | TripAdvisor    |
  | `di`  | Disqus         |
  | `pl`  | Plaxo          |
  | `eb`  | eBay           |
  | `mh`  | MyHeritage     |
  | `pb`  | Photobucket    |
  | `ps`  | PeopleSmart    |
</ParamField>

<ParamField body="link" type="string">
  Full URL to the social profile.
</ParamField>

<ParamField body="rating" type="integer">
  Confidence score indicating link validity. Possible values: `70` (likely valid) or `100` (high confidence).
</ParamField>

## experience

Array of work experience entries. Each item contains:

<ParamField body="position" type="string | null">
  Job title.
</ParamField>

<ParamField body="company" type="string | null">
  Company name.
</ParamField>

<ParamField body="location" type="string | null">
  Location of the role, or `null` if not specified.
</ParamField>

<ParamField body="current" type="boolean">
  Whether this is the person's current role.
</ParamField>

<ParamField body="started" type="string | null">
  Start date in ISO 8601 format (e.g. `"2015-01-01T00:00:00+00:00"`), or `null` if unknown.
</ParamField>

<ParamField body="ended" type="string | null">
  End date in ISO 8601 format, or `null` if the role is current or end date is unknown.
</ParamField>

<ParamField body="summary" type="string | null">
  Description of responsibilities or achievements in the role.
</ParamField>

<ParamField body="companyUrl" type="string">
  LinkedIn URL of the company. Returns `"n/a"` if not available.
</ParamField>

<ParamField body="companySize" type="string">
  Employee count range (e.g. `"1-10"`, `"50-100"`). Returns `"n/a"` if not available.
</ParamField>

<ParamField body="staffCount" type="integer | string">
  Approximate number of employees. Returns `"n/a"` if not available.
</ParamField>

<ParamField body="industry" type="string">
  Industry category of the company. Returns `"n/a"` if not available.
</ParamField>

<ParamField body="website" type="string">
  Company website URL. Returns `"n/a"` if not available.
</ParamField>

## education

Array of education entries. Each item contains:

<ParamField body="university" type="string">
  Name of the institution.
</ParamField>

<ParamField body="faculty" type="string | null">
  Department or field of study.
</ParamField>

<ParamField body="degree" type="array of strings">
  List of degrees obtained (e.g. `["JD"]`, `["Bachelor of Arts"]`).
</ParamField>

<ParamField body="url" type="string | null">
  LinkedIn URL of the institution.
</ParamField>

<ParamField body="startedYear" type="integer | null">
  Year of enrollment.
</ParamField>

<ParamField body="endedYear" type="integer | null">
  Year of graduation.
</ParamField>

## Other Fields

The following fields follow the same pattern — each is an array of objects that may be empty (`[]`). All fields within each object are `string | null`.

<ParamField body="language" type="array">
  Languages spoken. Each item contains `name` and `proficiency`.
</ParamField>

<ParamField body="organization" type="array">
  Professional organizations. Each item contains `name`, `position`, `startDate`, `endDate`.
</ParamField>

<ParamField body="certification" type="array">
  Certifications. Each item contains `name`, `license`, `authority`.
</ParamField>

<ParamField body="course" type="array">
  Courses completed. Each item contains `name`.
</ParamField>

<ParamField body="project" type="array">
  Projects. Each item contains `name`, `description`, `url`, `startDate`, `endDate`.
</ParamField>

<ParamField body="publication" type="array">
  Publications. Each item contains `name`, `description`, `issue`, `url`, `date`.
</ParamField>

<ParamField body="patent" type="array">
  Patents. Each item contains `name`, `issue`, `patentNumber`, `date`.
</ParamField>

<ParamField body="honorAward" type="array">
  Awards and honors. Each item contains `name`, `description`, `issue`, `date`.
</ParamField>

## Additional Fields

For a small subset of profiles, additional data may be present. These fields should not be relied upon as they are available only occasionally. They are **omitted entirely** when not available — never returned as `null` or `[]`.

<ParamField body="addresses" type="array">
  Physical addresses associated with the person.
</ParamField>

<ParamField body="dob" type="string">
  Date of birth.
</ParamField>

<ParamField body="names" type="array of strings">
  Alternative names or name variations.
</ParamField>