POST /api/users/signupUser[/{InvitationCode}]

Initiates the signup process by sending the user's signup information to the database; in some cases, sends an email to the user. Once the user has provided the required signup information, the signup is complete.

Before: Either of the following two scenarios can occur before this operation is run:

  1. User initiates signup: on the Community Manager developer portal Sign Up page, the user:
    • Provides first name, last name, and email address
    • Provides phone number (if required based on platform settings)
    • Answers one or more security challenge questions (if required based on platform settings)
    • Accepts the platform terms and conditions/legal agreement (if required based on platform settings)

    An email is then sent to the user, with a confirmation code. The user clicks the email link to confirm ownership of the email address and provides the password. The cookie is set and the user is now logged in.

  2. User is invited: The user is invited by another user; for example, to an API Scope Group or app team: user extending the invitation provides email address. The invited user clicks the link, thus confirming ownership of the email address. The user then provides the same information as in #1 above. The cookie is set and the user is now logged in.

The platform requires confirmation that the email address is valid before completing a signup operation. It accomplishes the confirmation by sending the invitation code to the email address provided. If the user initiates the signup, the user provides the required information, then waits for the email and clicks to complete the registration process. If signup is the result of an invitation, the platform sends the confirmation code to the email address provided. The user clicks the email link, which serves as confirmation that the email address is valid, and then provides the additional required information.

In scenario #1 above, the invitation code is included with the URL when the user clicks the link in the invitation message. Because the invitation code is provided, this operation sets the user's cookie via the set-cookie response parameter.

If the invitation code isn't included with the URL, the platform doesn't set the cookie.

After: Once the notification email is sent as a result of this operation, the user must perform the following steps to complete the signup process:

  • Click the signup code in the notification email, or send it as a parameter to the POST /api/users/signupUser/{InvitationCode} operation as explained below.
  • Provide answers to security challenge questions using the PUT /api/users/{UserID}/challenges operation. Note that if there are constraints set on the answers, the answers must be match the parameters or the operation will fail.
  • Accept the legal agreement using the POST /api/legals/agreements operation (after reviewing the actual agreement).
  • Log in using the POST /api/login operation.

Settings: This operation checks whether the setting that allows users to sign themselves up for the platform is set to allow self-signup. If the setting (SelfSignup) is disabled, the operation will fail. To check this setting, run the GET /api/businesses/{BusinessID}/usersettings operation.

Authorization Roles/Permissions: None required.

This topic includes the following sections:

HTTP Method

POST

URL

https://{hostname}/api/users/signupUser[/{InvitationCode}]

Sample Request

The examples below shows the user's signup information sent in the request body.

Sample Request URL 

https://{hostname}/api/users/signupUser/qEntsGgwk452385-UBl9q5MLRMuDoYE6p7KPAANZrOtL3o_JLXQ_Nw

Sample request headers 

POST /api/users/signupUser/qEntsGgwk452385-UBl9q5MLRMuDoYE6p7KPAANZrOtL3o_JLXQ_Nw HTTP/1.1
Accept: application/json, text/javascript, */*; q=0.01
Content-Type: application/json; charset=UTF-8

Sample request body #1

In the example below, user identification challenges are not in use.

{
  "FirstName":"Jane",
  "LastName":"Saoirse",
  "Email":"jane.saoirse@acmepaymentscorp.com",
  "Password":"Margaret23"
}

Sample request body #2

In the example below, user identification challenges are in use, so the user's answers to these questions must be sent in the request.

{
  "FirstName":"Jane",
  "LastName":"Mead",
  "Email":"jane.mead@example.com",
  "Password":"password1",
  "UserIdentificationChallenges":{
    "UserIdentificationChallenge":[
      {
        "ChallengeCode":"com.soa.challenge.question.city.birth",
        "ChallengeQuestion":"What is the city of your birth?",
        "Answer":"Lexington"
      },
      {
        "ChallengeCode":"com.soa.challenge.question.pet",
        "ChallengeQuestion":"What is the name of your pet?",
        "Answer":"Stella"
      },
      {
        "ChallengeCode":"com.soa.challenge.question.color",
        "ChallengeQuestion":"What is your favorite color?",
        "Answer":"Black"
      }
    ]
  }
}

Sample request body #3

In the example below, user identification challenges are in use and also phone numbers are enabled as part of the user profile.

{
  "FirstName":"Margaret",
  "LastName":"Martinson",
  "Email":"mmartinson@example.com",
  "UserPhones":{
    "UserPhone":[
      {
        "CountryCode":"+1",
        "PhoneNumber":"8181234567"
      }
    ]
  },
  "Password":"Sierra23",
  "UserIdentificationChallenges":{
    "UserIdentificationChallenge":[
      {
        "ChallengeCode":"com.soa.challenge.question.city.birth",
        "Answer":"San Marino"
      },
      {
        "ChallengeCode":"com.soa.challenge.question.color",
        "Answer":"fluorescent beige"
      },
      {
        "ChallengeCode":"com.soa.challenge.question.pet",
        "Answer":"Chloe"
      }
    ]
  },
  "AcceptedAgreementID":[
    "signupagrmtv1.acmepaymentscorp"
  ]
}

Request Headers

For general information on request header values, refer to HTTP Request Headers.

Header Description
Accept application/json, application/vnd.soa.v71+json, application/vnd.soa.v72+json, application/vnd.soa.v80+json, application/vnd.soa.v81+json
Content-Type

Any one of the following media types is valid for the request Content-Type:

application/json, application/vnd.soa.v71+json, application/vnd.soa.v72+json, application/vnd.soa.v80+json, application/vnd.soa.v81+json

Request Parameters

Parameter Parm Type Data Type Required Description
User Body User Required Contains information about a platform user.
InvitationCode Path string Optional The invitation code sent to the user, if the user is signing in after receiving an invitation code (invited by another platform user).

Response

If successful on user self-signup, this operation returns HTTP status code 200, with the user information including the assigned UserID. Because email confirmation is needed, the user's state is pending_validation.

If the user signed up with the invitation code, to complete the signup, and the operation is successful, it returns HTTP 200. At this point, the user's state changes from pending_validation to registered.

Sample Response

The sample response below shows the user information returned in the form of a JSON object.

Sample response headers 

HTTP/1.1 200 OK
Date: Fri, 25 Sep 2015 14:20:42 GMT
Content-Type: application/json
Set-Cookie: AtmoAuthToken_acmepaymentscorp=TokenID%3Dbc6f82c8-cfb9-11e2-9437-cdd24b34e538%2Cclaimed_id%3Durn%3acmepaymentscorp%3Auser%3Aacmepaymentscorp%3Auser
10026%2CissueTime%3D1370640742244%2CexpirationTim%3D1370642541186%2CGroups%3D%5B%22registeredusers%252Eopen%22%5D%2CAt
tributesIncluded%3Dtrue%2CUserFDN%3Duser10026%252Eopen%2CUserName%3DJaneSaoirse%2Csig%3DgtutJWV457xtJLymmleZJUz3aOsSooVAsx
_U4TfjXllVNmdR5L8ob3Sz1boZfDdaBHPKwu0XgVU_86oUac-vmafKGnsItKfi9pAmdl2vx8tW0nxSXHNg1RqCqQZ4_W4jIJrBN1fWqxnxPG2LH9AXgIPww22
JCuZAmPNMAE8NagE

Sample response body

In the example below, a self-sign user initiated platform signup and provider the user information. The user's state is pending_validation until the user confirms the signup by responding to the email that was sent as part of the signup process.

{
  "state" : "pending_validation",
  "userID" : "6a686072-b9fa-434f-8b22-4b2a47b07d59.acmepaymentscorp",
  "firstName" : "Margaret",
  "lastName" : "Martinson",
  "userName" : "MargaretMartinson",
  "profileName" : "MargaretMartinson",
  "authIdentifier" : "",
  "userPhones" : {
    "UserPhone" : [ {
      "CountryCode" : "+1",
      "PhoneNumber" : "8181234567",
      "Verified" : false,
      "Primary" : false
    } ]
  },
  "emailAddress" : "mmartinson@example.com",
  "domainName" : "Local Domain",
  "expired" : false,
  "signupStatus" : "user.signup.confirm.email"
}

Response Headers

For general information on response header values, refer to HTTP Response Headers.

Header Description
Content-Type

Any one of the following media types is valid for the request Content-Type:

application/json, application/vnd.soa.v71+json, application/vnd.soa.v72+json, application/vnd.soa.v80+json, application/vnd.soa.v81+json
Set-Cookie The set-cookie response header sets, updates, or expires the platform cookie to reflect changes made by the operation.

Response Body

Name Type Description
Response SignupResponse Contains basic signup information about the user, including the unique user ID assigned by the platform.

Error Codes/Messages

If the call is unsuccessful an error code/message is returned. One or more examples of possible errors for this operation are shown below.

Item Value
400 Bad request: Returned if the client sends a malformed request; for example, invalid parameters or body content.For example, you might get this response if a value was not provided for the email field in the request.
500 An error occurred processing the call.

More information about Akana API Platform API error messages.