This method registers a new user at your site, in accordance with the predefined site Policies and the Schema of the Accounts Storage. The accounts.register call is followed by accounts.finalizeRegistration, unless the finalizeRegistration parameter of accounts.register is set to 'true' (in which case there is no need to call accounts.finalizeRegistration).
A regToken (registration token), generated by accounts.initRegistration, is not required when using this method server-side, with a signed request.
For registration through a social network, see accounts.socialLogin.
us1.gigya.com- For the US data center.
eu1- For the European data center.
au1- For the Australian data center.
ru1- For the Russian data center.
cn1- For the Chinese data center.
If you are not sure of your site's data center, see Finding Your Data Center.
This method requires HTTPS.
|||username||string||A string that the user enters to identify his account.*|
|||string||The user's email address.*|
|* You are required to pass either username or email , depending on the specification of the site's Login Identifier policy. If the emailVerification policy is enabled, an email is always required during registration, regardless of the defined login identifier.|
|||password||string||The user's password. Gigya validates that the password meets the complexity requirements defined in the site's Password Strength policy.|
The regToken expires one hour after it is produced.
|||profile||Profile object||The user's profile information. The object may include site's custom fields in addition to reserved field names (as defined in the Profile object). Fields that are defined as required in the Schema , are required by this method. If not passed, the method will return a "pending registration" error and a new regToken.|
|||captchaToken||string||The CAPTCHA challenge. This parameter is required if specified so in the site's CAPTCHA policy.|
|||cid||string||A string of maximum 100 characters length. The CID sets categories for transactions that can be used later for filtering reports generated by Gigya in the "Context ID" combo box. The CID allows you to associate the report information with your own internal data. For example, to identify a specific widget or page on your site/application. You should not define more than 100 different context IDs.|
|||data||JSON object||Custom data. The purpose of this object is storing any custom data associated to the user, but which is not part of the Profile object. Gigya validates that the data fields meet the requirements that are defined in the Schema.|
|||finalizeRegistration||Boolean||If set to 'true', this API call will also finalize the registration process for the user, and the user will appear as a 'New registered user' in the user reports.|
If there are missing fields, the registration will remain pending. The default value is 'false'.
|||preferences||JSON object||A Preferences Object containing consent data for this user.|
|||secretQuestion||string||The secret question that can be used for verification. This parameter is required if specified so in the site's requireSecurityQuestion Policy.|
|||secretAnswer||string||The answer to the secret question. This parameter is required if specified so in the site's requireSecurityQuestion Policy .|
|||subscriptions||JSON object||A Subscriptions Object containing subscription data for this user.|
The language used in the current registration process, e.g. for communicating error messages and validation emails (see also Email Templates). If an email template is defined for this language, Gigya will send emails in this language (e.g. email verification).
If a profile.locale is not passed, it will be inferred from the lang passed in accounts.register.
This parameter defines your client side environment, which in return determines the server response data fields. The default value of this parameter is "browser", which means that by default you receive cookie-related data in the response.
If your client runs on a mobile:
If you are calling this method using a Mobile SDK since version 2.15.6, this parameter is automatically set to "mobile" (there is no need to set it manually). In any other case, you should set this parameter to be "mobile".
As a result of setting the parameter to "mobile" the server response data fields will include: sessionToken and sessionSecret (instead of cookie related data). In such case, you should send the sessionToken and sessionSecret to your mobile client. On your client side, call GSAPI.setSession (using the Mobile SDK) to save them in the app's storage.
|||include||string||A comma-separated list of fields to include in the response. The possible values are: identities-active, identities-all, loginIDs, emails, profile, data, password, missing-required-fields, lastLoginLocation and irank. The default is profile, so if this parameter is not used the response will return only the Profile object.|
|||sessionExpiration||integer||This parameter defines the time in seconds that Gigya should keep the login session valid for the user. To end the session when the browser closes, please assign the value '0'. If this parameter is not specified, the session is valid forever. See Managing Session Expiration for additional information.|
Note: The value of this parameter overrides the value of the identical parameter in the WebSDK Configuration.
|||siteUID||string||You may specify the UID to use with this account; if not specified, it is auto-generated.|
Note: The parameter accepts up to 252 ASCII characters (unicode is not supported).
Records the source of the registration. The default value is the URL of the current page but it can be any string value. regSource is stored in the account and can be used by verification emails to determine which page should be opened (see accounts.set Policies). Can also be set via the Global Conf object.
Each REST API request must contain identification and authorization parameters.
Some REST APIs may function without these authorization parameters, however, when that occurs, these calls are treated as client-side calls and all client-side rate limits will apply. In order to not reach client-side IP rate limits that may impact your implementation when using server-to-server REST calls, it is Recommended Best Practice to always sign the request or use a secret. A non-exhaustive list of REST APIs that this may apply to are as follows:
Please refer to the Authorization Parameters section for details.
If not passing the include parameter, only the user's profile object is returned by default.
|sessionInfo||JSON object||An object containg session information. The content of this object depends on the targetEnv parameter (see above).|
By default, if the targetEnv parameter is not set (your client environment is web), the sessionInfo object contains the the following string fields: cookieName and cookieValue.
Please create a session cookie with the name and value specified by these fields.
Alternatively, if the targetEnv parameter is set to "mobile" (your client runs on a mobile), the sessionInfo object contains the the following string fields: sessionToken and sessionSecret. Please send these fields to your mobile client. On your client side, call GSAPI.setSession (using the Mobile SDK) to save them on the app's storage.
|regToken||string||A ticket that is used to complete a registration process. A new regToken is returned when there is a pending registration error, which occurs when the user did not complete the registration process, or there are missing fields in the user profile data that were defined as "required" in the Schema. The regToken is valid for one hour from the moment it is returned.|
|unverifiedEmails||array||One or more unverified emails, in case there is a pending verification error.|
In case of a data validation errors (errorCode 400006), you will receive this field as an array of error objects. Each object represents a validation error regarding one of the following required fields: username, password, secretQuestion, secretAnswer, email. For example:
|newUser||Boolean||Indicates whether a new user was created in this call.|
A field that does not contain data will not appear in the response.
Gigya defines specific error codes and messages that are used with the Accounts API. These errors are returned with the APIs, indicating that some information is incorrect or missing.
This section describes the errors that are related to this API, the reasons for each error, and the expected next step.
- Account pending registration (error code 206001) - returned when the registration process has not been finalized, or the schema defines fields as required and one or more of these fields are missing for this user.In the initial call to accounts.register, the response will include missing fields, but in subsequent calls, use the include parameter to include missing-required-fields; These will be returned in the response as an array:The expected next step is: if the schema defines fields that are required and one or more of these fields are missing from the user profile or data, call accounts.setAccountInfo. If the registration process has not been finalized, call accounts.finalizeRegistration.
- CAPTCHA verification failed (error code 400021) - returned when the registration policy states that requireCaptcha is "true", and the CAPTCHA verification fails when a user tries to register.
- Login identifier exists (error code 403043) - returned when email is defined as the loginIdentifier in the accountOptions policy, and the email address received from the provider exists in the system but is associated with a different user. The expected next step: call accounts.linkAccounts to merge between the account identified by the provided UID and the account identified by the provided login credentials (loginID + password).
- Validation errors - the validationErrors object is an array of validation errors; each validation error is made up of an errorCode , a message, and a fieldName . The errorCode and message specify what error occurred and the fieldName specifies which field had a validation error. When an invalid field type is used, i.e. a string instead of an integer, or if a wrong format is used, i.e. an email address that is not in a correct format, an "Invalid parameter value" error is returned (error code 400006). A validation error is returned whenever there is a data validation error regarding one of the following required fields: username, password, securityQuestion, secretAnswer, email. The expected next step is: call the API method again with the missing info.
- Pending code verification (206006) - This response code may be returned when email code verification is used and the user has not yet verified their email.
This is not an exhaustive list of possible errors. These are specifically errors that may be encountered when using a custom implementation which require additional action to complete the registration of the user within the current context (to replace the built in logic of Screen-Sets). Additional information about specific recoverable Accounts errors can be found at Accounts API Error Codes and Messages.