Gigya Job Openings


Skip to end of metadata
Go to start of metadata


A migration to the Gigya platform is performed by exporting data from your current system to a JSON file and sending it to Gigya to import. This guide will help you develop an export schema that will seamlessly import into our platform.

The native Gigya User import file format is a JSON file containing information for each user and associated social identities. If you are importing into Gigya's Registration-as-a-Service, please reference the RaaS Import Guide

Required Schema Fields

All fields that are required in your schema should be included in the import file. If a user is missing any of the required fields, their account registration will stay in a pending state and they will be asked to complete the required fields the next time they log in through the Registration Completion flow. Note that all required fields must be included in your registration completion screen set or users missing required fields will not be able to complete their registrations.

Site Data vs. Social Data

It is important to note that Site Data overrides Social Data when Gigya is merging field values into the profile. Therefore, you should only include fields in the Site Identity that have been previously entered as site fields by the user. Otherwise, if a value was originally collected from a Social Identity and the user later changes it in their social profile, the updated value will not be reflected in their Gigya profile.

Accessing Social Data

In most cases, you should continue using any previously configured Social Network Apps. If you create new social network apps, users who have previously given permission to your old app will have to give permission to your new app. In addition, if you have stored auth tokens for your users and can provide them in the import file, at time of import Gigya will automatically download the social data available for users whose auth tokens are still valid. Since authTokens expire after finite amounts of time, we will only be able to download social data for users who have logged in recently (exact timeframe depends on the social network). If you do not include authTokens in your import file, social data will be downloaded for users the next time they log in socially.

In order to retain the links between social accounts and site accounts, you should provide us with the providerUIDs from each provider mapping to a siteUID. When the user logs in socially, we will then be able to automatically link them to their site profile. Pre-mapping the providerUIDs to siteUIDs is a better user experience because it avoids asking the user to re-link their accounts when they log in socially.

Object Fields

Note that ALL parameters are CASE SENSITIVE, as they are in the Gigya API.



RequiredField NameTypeDescription
UIDstringA unique identifier used by your site to identify the user. You may use the user's account ID that you have designated for this user in your database. The parameter accepts only ASCII characters (not Unicode) and can contain up to 252 characters. The UID is case-sensitive. See User.UID for more information.
userInfoJSON object

This parameter allows you to provide Gigya with a site users profile data. This will ensure a consistent user experience. Gigya will use this information, for example, in Add-ons that show user info, such as the Comments Add-ons.

Note: When using Gigya Add-ons, notifyLogin must be called with userInfo for site users who don't have a social identity in order for them to interact with the Add-ons.

The object may include the following fields: nickname, photoURL, thumbnailURL, firstName, lastName, gender, age, email.
For example:

"userInfo": {
	"firstName": "John",
    "lastName": "Smith",
    "nickname": "john.smith",
    "email": "",
    "photoURL": "",
    "gender": "m",
    "age": 32


Site Identity (Profile)

The site identity accepts a wide array of fields, many of which your site may not currently use. However, if your current site profiles do include any of the following fields, you should include them. Keep in mind that data pulled from social networks should not be imported to the users site identity.

Gigya validates that the profile fields meet the requirements that are defined in the Schema.


Field NameTypeDescription
addressstringThe person's address.
biostringA description of the person's professional profile.
birthDaynumberThe day in month in which the person was born.
birthMonthnumberThe month in which the person was born.
birthYearnumberThe year in which the person was born.
certificationsarray of objectsThe person's certifications' details.
citystringThe person's city.
countrystringThe person's country.
educationarray of objectsThe person's education details.
emailstringThe person's email.
favoritesJSON objectThe person's favorite things, including favorite books, movies, etc.
firstNamestringThe person's first name.
genderstringThe person's gender. The value may be 'm', 'f', or 'u', for male, female, or unspecified.
hometownstringThe person's hometown.
honorsstringA comma-separated list of the person's honors.
industrystringThe industry in which the person's company operates.
interestedInstringThe gender in which the person is interested.
languagesstringA comma-separated list of languages that the person speaks.
lastNamestringThe person's last name.
localestringThe person's locale.
nicknamestringThe person's nickname, this may be either the nickname provided by the connected provider or a concatenation of first and last name.
patentsarray of objectsThe person's patents' details.
phonesarray of objectsThe person's phone numbers.
photoURLstringThe URL of person's full size photo.
politicalViewstringThe person's political views.
professionalHeadlinestringThe person's professional headline, often the job title at the company.
profileURLstringThe URL of the person's profile.
publicationsarray of objectsThe person's publications' details.
relationshipStatusstringThe relationship status of the person.
skillsarray of objectsA collection of the person's skills.
specialitiesstringThe person's specialties.
statestringThe person's state.
timezonestringThe person's timezone.
workarray of objectsA collection of the person's work experience.
zipstringThe person's zip code.


Social Identities

If your current system stores the authTokens for your social users, you should include them in the identities array. If not, the provider and providerUID fields will allow us to pre-link social accounts to site accounts so that they will not have to re-link their accounts when they log in socially or create duplicate accounts.


RequiredField NameTypeDescription
providerstringThe name of the connected provider for this identity, in lowercase letters (facebook, yahoo, etc.).
providerUIDstringThe person's ID on the connected provider.

authTokenstringThe session authentication token.
tokenSecretstringThe session token secret.
tokenExpirationintegerThe absolute time when the session token expires in UNIX time format.
sessionHandlestringThe session handle encoded in BASE64.
sessionHandleExpirationintegerThe absolute time when the session expires in UNIX time format.



Data Schema

In addition to the generic fields stored in the site identity, you can pass fields and data structures in a JSON object to be stored in the data object schema. The purpose of this object is to store any custom data associated with the user, which is not part of the Site Identity. Gigya validates that the data fields meet the requirements that are defined in the Schema. Please note that storing data in the data schema requires Identity Storage.


JSON Samples

The samples provided on the subsequent pages do not represent all of the possible fields. Please see above to identify which fields are required and which are optional. Please note that the inclusion of email and username on the account level should match your Login Identifier policy.

User and Social Identities


    "settings": {
        "importFormat": "gigya-users-­import",
        "apiKey": "<APIKEY-­TO-­IMPORT-­DATA>",
        "finalizeRegistration": true,
        "skipVerification": true,
        "totalRecords": 8274 },
    "accounts": [ {
        "UID": "<YOUR-­SITE-­UID>",
        "userInfo": {
	        "firstName": "John",
            "lastName": "Smith",
            "nickname": "john.smith",
            "email": "",
            "photoURL": "",
            "gender": "m",
            "age": 32 },
		"identities": [ {
            "provider": "facebook",
            "providerUID": "81827657",
            "authToken": "08kjasdfo81hasdf8h",
            "tokenExpiration": 81857623 },
            "provider": "yahoo",
            "providerUID": "81047123",
            "authToken": "08kjasdfo81hasdf8h",
            "tokenSecret": "asdflkgas82345",
            "tokenExpiration": 81857623 } ],
		"data": {
            "customfield1": "customvalue1",
            "customfield2": "customvalue2",
            "customobject3": {
	            "subfield4": "subvalue4",
                "subfield5": "subvalue5" }