user subscription  subscribe

api description


subscribe starts a subscription process by sending to a potential subscriber a customizable email which contains a confirmation link and a default password which will be enabled on confirmation. See the optional parameters pwd_type and pwd_len to customize the default password.

From a user perspective, the only required parameters are an email address and the right answer to a simple visual challenge (see the API challenge_new).

From a service provider perspective, the email subject and content, as well as the callback url and its life time are fully customizable. By default, the sender address is service@auvercloud.com.

http method: POST

call cost: 1 point

See the pricing section for more details.

mandatory parameter(s)

parameter values / comments
key E.g. "c54e7837e0cd0ced286cb5995327d1ab54e35987179b2". It is an application key generated by AuverCloud Studio.
emailVisitor email address.
tokenToken ID generated by challenge_new.
challengeUser answer to the visual challenge.
subjectSubscription email subject e.g. "Please confirm your subscription to XYZ."
contentSubscription email HTML content e.g. "To confirm your subscription to XYZ, please click the following <a href='%link%'>link</a>. Then your user ID will be %email% and your password will be %password%."

PLEASE NOTE: In the example below few keywords are important!

  • %link% will be replaced by a link dynamically computed by the API. See also callback in the optional parameters.
  • %email% will be replaced by the user email address.
  • %password% will be replaced by a password generated by the API server.

optional parameters(s)

parameter values / comments
callbackThis is the callback URL for the confirmation. The default value is the API server "".

We suggest you to replace this default address with a customized one in order to provide the end user with some personalized feedback. In that case, your customized address must intercept the parameters and then forward them to the API server in a transparent way.

For instance, if you choose the callback address http://xyz.com, the confirmation link would look like http://xyz.com?any_parameter=any_value. Whatever the page http://xyz.com does, it must forward the parameters to the standard API server to finalize the process, here ?any_parameter=any_value.

ttl This defines the confirmation link time-to-live before being disabled. The default value is one "hour". Other possible values are "day" or "week".
pwd_type This defines the type of password which is generated: "num" (default), "alpha" or "alphanum".
pwd_len This defines the length of the password in characters. It is an integer between 6 and 16. The default value is 8.

call sample

This example is the code used in the test case below. It assumes that jQuery and the JavaScript AuverCloud runtime client are loaded in order to use the arc.api() method. See the API client section for more details.



code message comments
609 Forbidden parameter value. ttl value is wrong.
641 Unknown token. Either the token ID is unknown or is already burned.
643 Wrong challenge or token value. The challenge is not the expected one.
650 Email address is already used. You cannot subscribe a user twice.

See also the Common errors section.

test bed


To test the API with your own keys, please see the section Application keys in AuverCloud Studio.