Skip to main content
Explore the detailed breakdown of each item model component, complete with properties and their descriptions.

​
Response keys (v3)

The Profile JSON response from POST /v3/profiles/fetch is built around four keys:
KeyDescription
idID of the person assigned by The Swarm that was previously returned by the /search endpoint.
profile_infoDetailed profile data, e.g. work experience, education, etc.
listsA list of Lists that the person is assigned to along with the status in the list.
tagsAll 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:
FieldTypeDescription
profile_info.hiringboolean (true / false)Signals that the profile is actively hiring.
profile_info.open_to_workboolean (true / false)Signals that the profile is open to new opportunities.
profile_info.current_company_logo_urlstring (CDN URL)Logo URL for the profile’s current company.
profile_info.experience[].company.logo_urlstring (CDN URL)Logo URL on each experience entry’s company.
profile_info.experience[].start_date_confidencestring ("validated" or "low")Confidence indicator on each experience entry’s start date.

​
Fill rate

Data completeness for selected fields:
FieldTotalUS
profile_info.full_name100%100%
profile_info.linkedin_usernames100%100%
profile_info.current_title94%94%
profile_info.current_company_name95%95%
profile_info.location_name96%99%
profile_info.current_seniority83%88%
profile_info.industry65%76%

​
Timestamp fields

FieldDescription
latest_role_change_atTimestamp representing the start date of the most recent job detected for the profile.
current_job_updated_atTimestamp of the most recent change detected in the current primary job, which includes changes in company, title, or both.
updated_atTimestamp of the last update to any field in the profile document. Reflects any modification to the profile data.
created_atTimestamp indicating when the profile was created in our database.
last_refresh_atTimestamp 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"
          }
        }
      }
    }
  }
}