Candidate Object: Data Structure & Fields

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

{
  "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

string

Unique 32-character SignalHire profile identifier.

string

Full name of the person.

string | null

Gender of the person. Possible values: male, female, or null if not available.

string | null

Professional headline.

string | null

Profile bio or summary text.

object | null

Profile photo. Contains a single url string field, or null if no photo is available.

array

List of location objects. Each object contains a single name string field (e.g. "New York, New York, United States").

array of strings

List of professional skills.

integer | null

Total years of experience across all roles.

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:

string

Contact type. Possible values: email, phone, link, skype, telegram, whatsapp, viber, hangouts, wechat, qq, icq, gtalk, aim, windows_live_messenger, yahoo_messenger.

string

The contact value (email address, phone number, username, or URL depending on type).

integer

Confidence score indicating contact validity. Possible values: 70 (likely valid) or 100 (high confidence).

string | null

For emails: work, personal, or null. For phones: work_phone, mobile, or null. For other types: null.

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:

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

string

Full URL to the social profile.

integer

Confidence score indicating link validity. Possible values: 70 (likely valid) or 100 (high confidence).

experience

Array of work experience entries. Each item contains:

string | null

Job title.

string | null

Company name.

string | null

Location of the role, or null if not specified.

boolean

Whether this is the person’s current role.

string | null

Start date in ISO 8601 format (e.g. "2015-01-01T00:00:00+00:00"), or null if unknown.

string | null

End date in ISO 8601 format, or null if the role is current or end date is unknown.

string | null

Description of responsibilities or achievements in the role.

string

LinkedIn URL of the company. Returns "n/a" if not available.

string

Employee count range (e.g. "1-10", "50-100"). Returns "n/a" if not available.

integer | string

Approximate number of employees. Returns "n/a" if not available.

string

Industry category of the company. Returns "n/a" if not available.

string

Company website URL. Returns "n/a" if not available.

education

Array of education entries. Each item contains:

string

Name of the institution.

string | null

Department or field of study.

array of strings

List of degrees obtained (e.g. ["JD"], ["Bachelor of Arts"]).

string | null

LinkedIn URL of the institution.

integer | null

Year of enrollment.

integer | null

Year of graduation.

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.

array

Languages spoken. Each item contains name and proficiency.

array

Professional organizations. Each item contains name, position, startDate, endDate.

array

Certifications. Each item contains name, license, authority.

array

Courses completed. Each item contains name.

array

Projects. Each item contains name, description, url, startDate, endDate.

array

Publications. Each item contains name, description, issue, url, date.

array

Patents. Each item contains name, issue, patentNumber, date.

array

Awards and honors. Each item contains name, description, issue, date.

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 [].

array

Physical addresses associated with the person.

string

Date of birth.

array of strings

Alternative names or name variations.

Getting Started

Person API

Search API

Company API

Candidate Object: Data Structure & Fields

Full Example

Top-Level Fields

contacts

experience

education

Other Fields

Additional Fields

​Full Example

​Top-Level Fields

​contacts

​social

​experience

​education

​Other Fields

​Additional Fields

Full Example

Top-Level Fields

contacts

social

experience

education

Other Fields

Additional Fields