# Social Check

`GET /social_check`

- Live: `GET https://gdapi.globaldata.net.au/api/v2/social_check`
- Sandbox: `GET https://sandbox-gdapi.globaldata.net.au/api/v2/social_check`

The social_check method will perform a social media check using a phone number, email address, or
social media profile URL. The social media check will return a number of data structures (where available)
including:

- Social media profile links
- Associated email addresses and phone numbers
- Employment history
- Education history
- Interests and skills

## Supported social media profile URLs

Social media profile URLs must be supplied as full URLs and must include a path identifying the
specific profile. Bare handles such as `@johnsmith` are not accepted, and a domain on its own
(e.g. `linkedin.com`) is also not accepted.

The following URL formats are all accepted (using `linkedin.com/in/johnsmith` as an example path):

- `https://www.linkedin.com/in/johnsmith`
- `http://www.linkedin.com/in/johnsmith`
- `https://linkedin.com/in/johnsmith`
- `http://linkedin.com/in/johnsmith`
- `www.linkedin.com/in/johnsmith`
- `linkedin.com/in/johnsmith`

In other words, the scheme (`http://` or `https://`) and the `www.` prefix are both optional, but the
domain and a non-empty path are required. A trailing slash is allowed and will be stripped.

Profile URLs from the following networks are supported:

`facebook.com`, `fb.com`, `linkedin.com`, `twitter.com`, `x.com`, `xing.com`, `indeed.com`, `github.com`,
`meetup.com`, `instagram.com`, `quora.com`, `gravatar.com`, `klout.com`, `stackoverflow.com`,
`angellist.com`, `youtube.com`, `foursquare.com`, `pinterest.com`, `vimeo.com`, `aboutme.com`,
`flickr.com`, `ello.com`, `crunchbase.com`, `dribbble.com`, `google.com`, `wordpress.com`, `myspace.com`,
`behance.com`, `soundcloud.com`, `reddit.com`.

## Sandbox environment data

When simulating queries in the sandbox environment, the following inputs will return a match. Any other
input that passes validation will return `No match`. Every input listed against a single person resolves
to the same record and so will share the same `person_id`, which can be used to demonstrate
cross-input deduplication.

| Person          | Phone        | Email                                            | Profile URL                                |
|:----------------|:-------------|:-------------------------------------------------|:-------------------------------------------|
| Mary Bird       | +61449335480 | mary.bird@example.com<br>birdlady@example.com    | linkedin.com/in/mary-bird-9rk5reef<br>facebook.com/mary88-sample-user |
| Robert Jones    |              | robert@example.com                               | facebook.com/robert-jones-sample-user      |
| Michael Raymond |              | michael.raymond@example.com                      | linkedin.com/in/michael-raymond-sample     |

Profile URL inputs may include the `https://` (or `http://`) scheme and a `www.` prefix - they are
normalised before lookup, so for example `https://www.linkedin.com/in/mary-bird-9rk5reef` will also
return the Mary Bird record.

## Request body

The details of the record to enhance

| Field | Type | Description |
|-------|------|-------------|
| `records` | string | Comma separated list of phone numbers, email addresses and/or social media profile URLs. **Note:** Phone numbers should be in E.164 format, or Australian 0NSN format. Social media profile URLs must include a path (e.g. `https://www.linkedin.com/in/johnsmith`) and must be from one of the supported networks listed above. Example: `test@example.com,0412345678,https://www.linkedin.com/in/johnsmith` |

**Sample request**

```json
{
    "records": "test@example.com,0412345678,https://www.linkedin.com/in/johnsmith"
}
```

## Responses

### 200 Result of social media check

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `message` | string | A message indicating the result of the request. This will be `Ok` if the request was successful. Example: `Ok` |
| `api_reference` | string (uuid) | Example: `738d9a89-b6fe-4fc1-96be-1389b2a506a2` |
| `records` | array of objects | A set of matched records |
| `records[].record` | string | The phone number, email address or social media profile URL being checked (as supplied) Example: `test@example.com` |
| `records[].result` | string | Was a match found for this record? * `Match` - A match was found * `No Match` - No match was found * `Error` - An error occurred Enum: `Match`, `No Match`, `Error` Example: `Match` |
| `records[].likelihood` | integer [1..10] | A confidence score indicating the strength of the match, from 1 (lowest) to 10 (highest). This value reflects how closely the input data matched the returned record. Example: `8` |
| `records[].person_id` | string or null | A unique identifier for the matched person. This value is consistent across lookups, so if two different inputs (e.g. two different email addresses) resolve to the same person, they will share the same `person_id`. This can be used to deduplicate results. Example: `a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1` |
| `records[].location` | string | String representing general geographic location. The format will depend on the social media information available but will generally consist of suburb, state and country. Example: `sydney, new south wales, australia` |
| `records[].location_locality` | string | The locality (city/suburb) component of the person's location. Example: `sydney` |
| `records[].location_region` | string | The region (state/province) component of the person's location. Example: `new south wales` |
| `records[].location_country` | string | The country component of the person's location. Example: `australia` |
| `records[].person` | object | Details of the person associated with the record. |
| `records[].person.name_first` | string | The first name of the person Example: `John` |
| `records[].person.name_middle` | string | The middle name of the person Example: `Michael` |
| `records[].person.name_last` | string | The last name of the person Example: `Smith` |
| `records[].person.name_combined` | string | The full name of the person Example: `John Michael Smith` |
| `records[].person.gender` | string | The gender of the person Enum: `male`, `female` Example: `male` |
| `records[].person.dob` | string (date) | The date of birth of the person This can be either a full date in the format YYYY-MM-DD or a year only in the format YYYY Example: `1990-05-23` |
| `records[].person.industry` | string | The industry the person is associated with. Example: `accounting` |
| `records[].emails` | array of strings | A list of email addresses associated with the person |
| `records[].emails_detailed` | array of objects | A list of email addresses associated with the person, including type classification. This provides the same email addresses as the `emails` field but with additional metadata. |
| `records[].emails_detailed[].address` | string | The email address Example: `test@example.com` |
| `records[].emails_detailed[].type` | string or null | The classification of the email address, if known. Common values include: * `current_professional` - A current work email * `personal` - A personal email May be null if the type is unknown. Example: `current_professional` |
| `records[].phones` | array of strings | A list of phone numbers associated with the person (in E.164 format) |
| `records[].employment` | object | Current employment details of the person |
| `records[].employment.company` | string | The name of the company the person works for Example: `Sample Corp` |
| `records[].employment.title` | string | The job title of the person Example: `Software Engineer` |
| `records[].employment.company_website` | string | The website of the company the person works for Example: `samplecorp.com` |
| `records[].employment.company_size` | string | The approximate size of the company the person works for Example: `51-200` |
| `records[].employment.company_industry` | string | The industry of the company the person works for Example: `information technology and services` |
| `records[].employment.start_date` | string | The start date of the person's current employment. This can be a year/month in the format YYYY-MM or a year only in the format YYYY. Example: `2021-04` |
| `records[].employment_history` | array of objects | A list of employment history items for the person, ordered by start date (most recent first). |
| `records[].employment_history[].company` | string | The name of the company the person worked for Example: `Other Corp` |
| `records[].employment_history[].title` | string | The job title of the person Example: `Systems Engineer` |
| `records[].employment_history[].date_start` | string (date) | The start date of the person's employment. This can be either a full date in the format YYYY-MM-DD or a year/month in the format YYYY-MM or a year only in the format YYYY Example: `2015-01-01` |
| `records[].employment_history[].date_end` | string (date) | The end date of the person's employment. This can be either a full date in the format YYYY-MM-DD or a year/month in the format YYYY-MM or a year only in the format YYYY Example: `2020-01-01` |
| `records[].employment_history[].industry` | string | The industry of the company the person worked for Example: `retail` |
| `records[].employment_history[].company_size` | string | The approximate size of the company Example: `201-500` |
| `records[].employment_history[].company_website` | string | The website of the company Example: `othercorp.com.au` |
| `records[].employment_history[].is_primary` | boolean | Whether this is the person's current primary role Example: `false` |
| `records[].education` | array of objects | Education details of the person, ordered by start date (most recent first). |
| `records[].education[].school` | string | The name of the institution Example: `University of Sydney` |
| `records[].education[].type` | string | The type of institution Example: `University` |
| `records[].education[].url` | string | The URL of the institution Example: `https://www.sydney.edu.au/` |
| `records[].education[].studies` | array of strings | Studies undertaken at the institution |
| `records[].education[].date_start` | string (date) | The start date of the person's studies. This can be either a full date in the format YYYY-MM-DD or a year/month in the format YYYY-MM or a year only in the format YYYY Example: `2015-01-01` |
| `records[].education[].date_end` | string (date) | The end date of the person's studies. This can be either a full date in the format YYYY-MM-DD or a year/month in the format YYYY-MM or a year only in the format YYYY Example: `2020-01-01` |
| `records[].education[].location` | string | The geographic location of the institution Example: `sydney, new south wales, australia` |
| `records[].education[].domain` | string | The web domain of the institution Example: `sydney.edu.au` |
| `records[].interests` | array of strings | A list of interests of the person |
| `records[].skills` | array of strings | A list of skills of the person |
| `records[].socials` | array of objects | A list of social media profiles of the person |
| `records[].socials[].network` | string | The type of social media profile Example: `LinkedIn` |
| `records[].socials[].url` | string | The URL of the social media profile Example: `https://www.linkedin.com/in/johnsmith/` |
| `records[].socials[].username` | string | The username of the social media profile Example: `johnsmith` |
| `records[].socials[].id` | string | The ID of the social media profile Example: `1234567890` |
| `records[].record_date` | string (date) | The date this record was last updated, in the format YYYY-MM-DD. Example: `2025-03-19` |

**Sample response**

```json
{
    "message": "Ok",
    "api_reference": "738d9a89-b6fe-4fc1-96be-1389b2a506a2"
}
```

Standard error responses: 400, 401, 402, 403, 429, 5XX (see [Common error responses](/docs/reference/general/common-error-responses.md))