Identities

The Identities data point, in most cases, contain the meat of the data about the user as made available from the provider. Putting together various identity data from different providers can give you a fuller view of the user's information as well as opportunities to verify their data across multiple providers.

After the user connects an Account via Smile, Smile retrieves the user's Identity data from the Provider and makes it available for retrieval. You may listen for the appropiate events and webhooks (outlined below) in order to determine when their Identity data is ready.

Verifying User Identity

Most platforms will contain at least a first name and last name, with middle names and suffixes varying from platform to platform. You can use these information to match your customer's provided information with data from verifiable sources, such as government records and social security agencies.

Fallback Methods

If the sources your user provided are not enough you can also make use of Smile's Archive API to encourage the user to upload their own IDs. This can be a drivers' license, passport, or even banking or payroll documents.

The Identity object

AttributeTypeDescription
idstringUnique ID of the identity information on the Smile Network
fullNamestringFull name of the user, if available from the provider. Null if not available
firstNamestringFirst name of the user, if available from the provider. Null if not available
middleNamestringMiddle name of the user, if available from the provider. Null if not available
lastNamestringLast name of the user, if available from the provider. Null if not available
suffixstringSuffix of the user (i.e. Jr, Ss, MD, etc), if available from the provider. Null if not available
genderstringGender of the user, if available from the provider. Null if not available. Possible values: Male, Female, Non-binary
dobdateBirth date of the user, if available from the provider. Null if not available
maritalStatusstringMarital status of the user, if available from the provider. Null if not available. Possible values: Divorced, Lifetime Partner, Married, Separated, Single, Widowed
countryResidencestringCountry of residence of the user, if available from the provider. Null if not available. Provided in 2-character alpha ISO-3166 codes, i.e. PH, ID, etc.
citizenshipstringCitizenship status of the user in their country of residences, if available from the provider. Null if not available. Possible values: Citizen, Resident Alien, Non-resident Alien, Undocumented, Others
photoUrlstringFully-formed URL to user's photo or avatar, if available from the provider. Null if not available
referenceIdstringReference ID of the user's profile from the provider, if available. Null if not available
profileUrlstringFully-formed URL to user's public profile with the provider, , if available. Null if not available
emailsarrayContains email address(es) of the user as available from the provider. See object below
phonesarrayContains phone numbers of the user as available from the provider. See object below
socialProfilesarrayContains any social profiles connected to the user's account as available from the provider. See object below
addressesarrayContains physical addresses of the user as available from the provider. See object below
metadataobjectContains data about this identity data point. See object below

The Email Address object

AttributeTypeDescription
addressstringEmail address of the user
typestringType of email address provided by the user. Possible values: Primary, Secondary, Work, Personal

The Phone Number object

AttributeTypeDescription
numberstringPhone number of the user in international E.164 format
typestringType of phone number provided by the user. Possible values: Mobile, Fixed, Unspecified

The Social Profiles object

AttributeTypeDescription
socialUrlstringFully-formed URL to the user's public social media page
typestringProvider of social media account to the user. Possible values: Twitter, Facebook, LinkedIn, Others

The Address object

AttributeTypeDescription
fullAddressstringFull physical address of the user
line1stringFirst line of the user's address, i.e. street address
line2stringSecond line of the user's address
citystringCity of the user's address
regionstringGeographic region of the user's address such as state or province
zipstringZip or post code of the user's address
countrystringCountry of the user's address. Provided in 2-character alpha ISO-3166 codes, i.e. PH, ID, etc.
latitudestringLatitude coordinates of the user's address
longitudestringLongitude coordinates of the user's address
typestringType of address provided by the user. Possible values: Primary, Secondary

The Meta Data object

AttributeTypeDescription
createdAtdate-timeDate/time when the account record was created
itemCreatedAtdate-timeDate/time when the identity record was created
accountId DeprecatedstringID of the user's account in the Smile Network
sourceIdstringID of the user's account or archive in the Smile Network
sourceTypestringIndicates whether the source associated with this object is an account or archive. Possible values: ACCOUNT, UPLOAD, ARCHIVE
providerIdstringID of the data provider of the user's account
userIdstringID of the user on the Smile Network

Sample Identity data

{
  "id": "i-123abc456def789abc123def456abc78",
  "fullName": "George Cimafranca Palomero, Jr",
  "firstName": "George",
  "middleName": "Cimafranca",
  "lastName": "Palomero",
  "suffix": "Jr",
  "gender": "Male",
  "dob": "1970-08-24",
  "maritalStatus": "Married",
  "countryResidence": "PH",
  "citizenship": "Citizen",
  "photoUrl": "https://cdn.smileapi.io/image/avatar/v20211115191600/george.jpg",
  "referenceId": null,
  "profileUrl": null,
  "emails": [
    {
      "address": "[email protected]",
      "type": "Primary"
    }
  ],
  "phones": [
    {
      "number": "+639559991234",
      "type": "Mobile"
    }
  ],
  "socialProfiles": [
    {
      "socialUrl": "https://www.facebook.com/gpalomero1234",
      "type": "Facebook"
    }
  ],
  "addresses": [
    {
      "fullAddress": "12 Maybunga St, Barangay Paraiso, Pasig City, NCR, 1600, PH",
      "line1": "12 Maybunga St",
      "line2": "Barangay Paraiso",
      "city": "Pasig City",
      "region": "NCR",
      "zip": "1600",
      "country": "PH",
      "latitude": "14.573454",
      "longitude": "121.085042",
      "type": "Primary"
    }
  ],
  "metadata": {
    "createdAt": "2022-08-19T07:29:08Z",
    "itemCreatedAt": "2022-08-24T05:24:37Z",
    "sourceId": "a-123abc456def789abc123def456abc78",
    "sourceType": "ACCOUNT",
    "userId": "tenantId-123abc456def789abc123def456abc78",
    "providerId": "abccorp"
  }
}

Endpoints

Endpoint
List all identitiesGET /identities
Retrieve one identityGET /identities/{id}

Webhooks

IDENTITY_ADDED

Sent when identity data about a user is added from the provider.

{
  "id": "et-123abc456def789abc123def456abc78",
  "version": 1,
  "type": "IDENTITY_ADDED",
  "createdAt": "2021-04-14T09:30:24Z",
  "data": {
    "userId": "tenantId-123abc456def789abc123def456abc78",
    "accountId": "a-123abc456def789abc123def456abc78",
    "identityId": "i-123abc456def789abc123def456abc78",
    "providers": [
      "abccorp"
    ]
  }
}

TASK_FINISHED

Sent when the full data sync task process for a user's account is finished.

{
  "id": "et-123abc456def789abc123def456abc78",
  "version": 1,
  "type": "TASK_FINISHED",
  "createdAt": "2021-04-14T09:30:24Z",
  "data": {
    "userId": "tenantId-123abc456def789abc123def456abc78",
    "sourceId": "a-123abc456def789abc123def456abc78",
    "sourceType": "ACCOUNT",
    "providers": [
      "abccorp"
    ],
    "datapoints": [
      "IDENTITIES",
      "INCOMES"
    ]
  }
}