Response keys (v3)
The Profile JSON response fromPOST /v3/profiles/fetch is built around four keys:
| Key | Description |
|---|---|
| id | ID of the person assigned by The Swarm that was previously returned by the /search endpoint. |
profile_info | Detailed profile data, e.g. work experience, education, etc. |
lists | A list of Lists that the person is assigned to along with the status in the list. |
tags | All tags assigned to the profile by any of the team members. |
v2 also returned
connections and notes. Both are removed in v3.- For connections, use the Relationships endpoint — it’s free and exposes the same data.
- The notes feature is being retired and has no v3 replacement.
New fields in v3
The following fields are added to profile responses in v3:| Field | Type | Description |
|---|---|---|
profile_info.hiring | boolean (true / false) | Signals that the profile is actively hiring. |
profile_info.open_to_work | boolean (true / false) | Signals that the profile is open to new opportunities. |
profile_info.current_company_logo_url | string (CDN URL) | Logo URL for the profile’s current company. |
profile_info.experience[].company.logo_url | string (CDN URL) | Logo URL on each experience entry’s company. |
profile_info.experience[].start_date_confidence | string ("validated" or "low") | Confidence indicator on each experience entry’s start date. |
Fill rate
Data completeness for selected fields:| Field | Total | US |
|---|---|---|
| profile_info.full_name | 100% | 100% |
| profile_info.linkedin_usernames | 100% | 100% |
| profile_info.current_title | 94% | 94% |
| profile_info.current_company_name | 95% | 95% |
| profile_info.location_name | 96% | 99% |
| profile_info.current_seniority | 83% | 88% |
| profile_info.industry | 65% | 76% |
Timestamp fields
| Field | Description |
|---|---|
| latest_role_change_at | Timestamp representing the start date of the most recent job detected for the profile. |
| current_job_updated_at | Timestamp of the most recent change detected in the current primary job, which includes changes in company, title, or both. |
| updated_at | Timestamp of the last update to any field in the profile document. Reflects any modification to the profile data. |
| created_at | Timestamp indicating when the profile was created in our database. |
| last_refresh_at | Timestamp of the latest attempt to refresh the profile data - either via rescraping the internet or receiving updated information from a data partner. |
JSON schema
Here you can find the full Profile JSON Schema (v3):{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"lists": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"status": {
"type": "string"
}
}
}
},
"tags": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
}
}
},
"profile_info": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"full_name": {
"type": "string"
},
"first_name": {
"type": "string"
},
"last_name": {
"type": "string"
},
"headline": {
"type": "string"
},
"about": {
"type": "string"
},
"linkedin_url": {
"type": "string"
},
"work_email": {
"type": "string"
},
"personal_emails": {
"type": "array",
"items": {
"type": "string"
}
},
"current_title": {
"type": "string"
},
"current_function": {
"type": "string"
},
"current_seniorities": {
"type": "array",
"items": {
"type": "string"
}
},
"current_company_id": {
"type": "string"
},
"current_company_name": {
"type": "string"
},
"current_company_logo_url": {
"type": "string"
},
"current_company_size": {
"type": "object",
"properties": {
"min": {
"type": "integer"
},
"max": {
"type": "integer"
}
}
},
"current_company_location": {
"type": "string"
},
"current_company_linkedin_url": {
"type": "string"
},
"current_company_websites": {
"type": "array",
"items": {
"type": "string"
}
},
"current_company_industries": {
"type": "array",
"items": {
"type": "string"
}
},
"experience": {
"type": "array",
"items": {
"type": "object",
"properties": {
"is_current": {
"type": "boolean"
},
"company_id": {
"type": "string"
},
"company": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"canonical_name": {
"type": "string"
},
"name": {
"type": "string"
},
"founded": {
"type": "string"
},
"size": {
"type": "object",
"properties": {
"min": {
"type": "integer"
},
"max": {
"type": "integer"
}
}
},
"social_media": {
"type": "array",
"items": {
"type": "object",
"properties": {
"network": {
"type": "string"
},
"id": {
"type": "string"
},
"slug": {
"type": "string"
},
"url": {
"type": "string"
},
"url_status": {
"type": "string"
}
}
}
},
"locations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"city": {
"type": "string"
},
"state": {
"type": "string"
},
"country": {
"type": "string"
},
"is_primary": {
"type": "boolean"
}
}
}
},
"industries": {
"type": "array",
"items": {
"type": "string"
}
},
"websites": {
"type": "array",
"items": {
"type": "string"
}
},
"logo_url": {
"type": "string"
}
}
},
"title": {
"type": "string"
},
"seniorities": {
"type": "array",
"items": {
"type": "string"
}
},
"function": {
"type": "string"
},
"location": {
"type": "array",
"items": {
"type": "string"
}
},
"description": {
"type": "string"
},
"start_date": {
"type": "string"
},
"end_date": {
"type": "string"
},
"status": {
"type": "string"
},
"start_date_confidence": {
"type": "string"
}
}
}
},
"current_location": {
"type": "string"
},
"skills": {
"type": "array",
"items": {
"type": "string"
}
},
"education": {
"type": "array",
"items": {
"type": "object",
"properties": {
"school": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"location": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"city": {
"type": "string"
},
"state": {
"type": "string"
},
"country": {
"type": "string"
}
}
},
"website": {
"type": "string"
},
"linkedin_url": {
"type": "string"
},
"linkedin_id": {
"type": "integer"
}
}
},
"start_date": {
"type": "string"
},
"end_date": {
"type": "string"
},
"degrees": {
"type": "array",
"items": {
"type": "string"
}
},
"majors": {
"type": "array",
"items": {
"type": "string"
}
},
"activities": {
"type": "string"
},
"grade": {
"type": "string"
},
"description": {
"type": "string"
}
}
}
},
"social_media": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"entity_id": {
"type": "string"
},
"network": {
"type": "string"
},
"url": {
"type": "string"
},
"url_status": {
"type": "string"
},
"connections": {
"type": "integer"
},
"followers": {
"type": "integer"
},
"join_date": {
"type": "string"
}
}
}
},
"certifications": {
"type": "array",
"items": {
"type": "object",
"properties": {
"end_date": {
"type": "string"
},
"name": {
"type": "string"
},
"organization": {
"type": "string"
},
"start_date": {
"type": "string"
}
}
}
},
"smart_tags": {
"type": "array",
"items": {
"type": "string"
}
},
"hiring": {
"type": "boolean"
},
"open_to_work": {
"type": "boolean"
},
"latest_role_change_at": {
"type": "string"
},
"latest_company_change_at": {
"type": "string"
},
"current_job_updated_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"created_at": {
"type": "string"
},
"last_refresh_at": {
"type": "string"
},
"image_url": {
"type": "string"
}
}
},
"found_by": {
"type": "object",
"properties": {
"ids": {
"type": "array",
"items": {
"type": "string"
}
},
"linkedin_names": {
"type": "array",
"items": {
"type": "string"
}
},
"linkedin_ids": {
"type": "array",
"items": {
"type": "integer"
}
},
"linkedin_entity_ids": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}