RErecruitwithatlas
People

Search people by identity

Changed on

Use this endpoint to look up a specific person in your Atlas account using a contact detail you already know - such as their email address, phone number, or LinkedIn profile URL.

For example, if someone fills out a form on your website and you have their email address, you can use this endpoint to instantly check whether they already exist in Atlas and retrieve their full record.

You must provide at least one of: email, phone, or LinkedIn URL. Atlas will search your agency's data and return any matching people along with their name, current role, current company, and the contact details (identities) that matched your search - each with its active state and inactiveReason, so you can tell an unsubscribed email from a bounced one. To get every identity a person has, use GET /api/v1/people/{personId}/identities.

Phone numbers are expanded server-side into every form they may be stored in (national, international, with and without a leading 0 or +), so 07935929797 and +447935929797 find the same person. A number Atlas cannot parse expands to nothing and is not a searchable value.

If none of the values you supply resolves to something searchable - for example phones on its own containing only an unparseable number - the request is rejected with 422 rather than searched, because a search with no usable filter would otherwise match everything.

If the filters are valid but nothing matches, an empty list is returned - that is not an error.

get/api/v1/people/search

Request

Query parameters

emailsstring

Comma-separated email addresses

Example:alice@example.com,bob@example.com
phonesstring

Comma-separated phone numbers. Each value is expanded server-side into every form it may be stored in (national, international, with and without a leading 0 or +). A number that cannot be parsed expands to nothing and is therefore not a searchable value.

Example:+14155551234,+442071234567
linkedinUrlsstring

Comma-separated LinkedIn URLs

Example:linkedin.com/in/john-doe,linkedin.com/in/jane-smith

Response

Matching people with their identities

status'ok' required

Example response

{
  "data": [
    {
      "firstName": "John",
      "lastName": "Doe",
      "headlineRole": "Software Engineer",
      "headlineCompanyName": "Acme Corp",
      "identities": [
        {
          "identityId": "6f1c2d3e-4b5a-4c6d-8e7f-9a0b1c2d3e4f",
          "inactiveReason": "unsubscribed"
        }
      ]
    }
  ]
}

Changes

  • 158ee454751cRevision changes
    • warning

      added the new undefined enum value to the //// response property for the response status

  • b7e1215476a1Revision changes
    • info

      added the required property //// to the response with the status

    • info

      added the required property //// to the response with the status