API Documentation

API documentation

Welcome to the ValidShapes API documentation. You can see below all API methods we provide you to use our captcha service.

captcha

GET /captcha
Description

Generate an unique validshapes captcha and return the html view. You can customize your captcha thanks to all parameters below.

Parameters
  • Field
    Type
    Description
  • publicKey (*)
    String
    The public key is a mandatory parameter. After your registration in our website, you will receive this key.Max lenght : 45
  • positionAccuracy
    Integer
    We can allow the user to do some mistakes in the box positioning. The accuracy is in pixel for the vertical and horizontal.Min value: 1, default value: 2 and max value: 3
  • audioCharactersAccuracy
    Integer
    We can allow the user to do some mistakes in the audio recognition. The accuracy is in characters for the text entered by the user.Min value: 0, default value: 1 and max value: 2
  • shapesDensity
    Integer
    Determine the density of shapes into the captcha. More the value is high and more you will have shapes.Min value: 1, default value: 2 and max value: 3
  • maxBackgroundWidth
    Integer
    Determine the maximum width for the generated pictures with shapes. As the html is responsive, the picture can be smaller.Min value: 270, default value: 320 and max value: 420
  • maxBackgroundHeight
    Integer
    Determine the maximum height for the generated pictures with shapes. As the html is responsive, the picture can be smaller.Min value: 100, default value: 110 and max value: 140
  • validBoxSize
    Integer
    Determine the valid box size into the captcha. It is fixed value for the moment.Min value: 80, default value: 80 and max value: 80
  • colorTheme
    Enum
    You can select a specific theme for your captcha. By default, it is random.Values: {blue, blueHuePlus30, coralBlue, violet, purple, coralRed, hazelnut, green, grassGreen, paleGreen, gold}
  • lang
    Enum
    Determine the language used into the ValidShapes.Values: {auto-detect, en, fr, de, custom}
  • instructionHelp
    String
    The user instruction below the shapes box. Override the translation if you have choosed custom value for the lang parameter.
  • audioHelp
    String
    The place holder text inside the audio input. Override the translation if you have choosed custom value for the lang parameter.
Success 200 (html)

audio

GET /audio
Description

Generate an unique mp3 captcha. The generated sound is a succession of letters and numbers.

Parameters
  • Field
    Type
    Description
  • token (*)
    String
    The token in send to the html view of a validshapes captcha @see the captcha method. A hidden input named vs_token is always generated. You need to send this parameter to be able to call this method with success.Max lenght : 45
Success 200 (audio/mp3)

validateShapes

POST /validate/shapes
Description

Check if the shape is on the right position into the ValidShapes captcha. The accuracy required depends on the configuration you have done on the captcha method @see positionAccuracy parameter.

Parameters
  • Field
    Type
    Description
  • token (*)
    String
    The token in send to the html view of a validshapes captcha @see the captcha method. A hidden input named vs_token is always generated. You need to send this parameter to be able to call this method with success.Max lenght : 45
  • privateKey (*)
    String
    The private key is a mandatory parameter. After your registration in our website, you will receive this key. Do not provide this key on front end side.Max lenght : 45
  • xCoord (*)
    Integer
    The abscissa coordinate of the top left valid box.Min value: 0 and max value: 1000
  • yCoord (*)
    Integer
    The ordinate coordinate of the top left valid box.Min value: 0 and max value: 1000
Success 200 (json)
  • Field
    Type
    Description
  • success
    Bool
    Determine if the validation was successful or not.
  • status
    Enum
    Allow you to have more details on the response answer. If the code is greater than zero, the validation has failed.Values: {Success, InvalidToken, WrongPosition}

validateAudio

POST /validate/audio
Description

Check if the audio heard by the user is correct. The tolerance to validate the solution depends on the configuration you have done on the captcha method @see audioCharactersAccuracy parameter.

Parameters
  • Field
    Type
    Description
  • token (*)
    String
    The token in send to the html view of a validshapes captcha @see the captcha method. A hidden input named vs_token is always generated. You need to send this parameter to be able to call this method with success.Max lenght : 45
  • privateKey (*)
    String
    The private key is a mandatory paramater. After your registration in our website, you will receive this key. Do not provide this key on front end side.Max lenght : 45
  • audioSolution (*)
    String
    The audio solution that users will enter into the dedicated field.Max lenght : 30
Success 200 (json)
  • Field
    Type
    Description
  • success
    Bool
    Determine if the validation was successful or not.
  • status
    Enum
    Allow you to have more details on the response answer. If the code is greater than zero, the validation has failed.Values: {Success, InvalidToken, InvalidSolution}

serversName

GET /servers/name
Description

Allows to know all webservers name used by Valid shapes. You will need this method on backend side, to validate a captcha on the right server. You will find more details on this topic in all samples we provide in this website. The result can be cached for maximum one day.

Success 200 (json)
  • Field
    Type
    Description
  • names
    String[]
    List of all web server names. Array of string.

If anything is unclear in this documentation, feel free to contact us on the forum or directly by e-mail