NAV Navbar
shell

Introduction

Welcome to the documentation for form-api.com!

Our API offers a simple, RESTful interface with JSON-formatted responses. With it, you can simplify, autocomplete, and validate your forms. enhance and enrich your data, and much more.

The API includes :
* Gender API: Determine gender from first name or full name.
* Zip Code API: World zip code database.
* Validation API: Data validator using JSON object schema.

The API can be easily integrated into every platform.

Authentication

To interact with our API, an API key must be sent with each HTTP request as a query parameter. Any requests sent without valid API key will fail.
You can register a new API key at https://form-api.com/account/signup.
You should include you API key in any API request to the server: https://api.form-api.com/endpoint?key=YOUR_API_KEY

Gender API

Determines the gender of a first name, or full name.

> FULL NAME QUERY:
curl "https://form-api.com/api/gender/get?key=YOUR_API_KEY&name=dr+jon+doe;mohammad+ali&type=full_name"
> JSON RESPONSE:
{
  "status":"Ok",
  "results":{
    "dr jon doe":{
      "gender":"male",
      "title":"Dr",
      "first_name":"Jon",
      "last_name":"Doe"
      },
    "mohammad ali":{
      "gender":"male",
      "first_name":"Mohammad",
      "last_name":"Ali"
    }
  }
}

HTTP Request

GET https://form-api.com/api/gender/get

Query Parameters

Parameter Type Default Description
name String false One, or multiple first names or full names separated by ';' Required
type String first_name Name type, Your options are first_name or full_name. when full_name is set, the result will contain all the parsed components of the name like first name, last name, middle name and title.

Zip Code API

> World countries:
curl "https://form-api.com/api/geo/worldcountries?key=YOUR_API_KEY"
> JSON RESPONSE:
{
  "status":"Ok",
  "countries":{
    "AD":"Andorra", . . .    
  }
}
> States in Country :
curl "https://form-api.com/api/geo/country/states?key=YOUR_API_KEY&country=US"
> JSON RESPONSE:
{
  "status":"Ok",
  "country":"US",
  "states":[
    {"state_id":"AL", "state":"Alabama"},
    {"state_id":"AK","state":"Alaska"} . . . 
    ]
}
> Cities in State:
curl "https://form-api.com/api/geo/country/state/cities?key=YOUR_API_KEY&country=US&state=NY"
> JSON RESPONSE:
{
  "status":"Ok",
  "country":"US",
  "state_code":"NY",
  "cities":[
    {"city_id":1,"city":"Accord"},
    {"city_id":2,"city":"Acra"} . . .
  ]  
}
> Zip code in city:
curl "https://form-api.com/api/geo/country/state/city/zips?key=YOUR_API_KEY&country=US&state=NY&city=2"
> JSON RESPONSE:
{
  "status":"Ok",
  "country":"US",
  "state":"NY",
  "city":"2",
  "zip_codes":["12405"]
} 
> Zip code info:
curl "https://form-api.com/api/geo/country/zip?key=YOUR_API_KEY&country=US&zipcode=12405"
> JSON RESPONSE:
{
  "status":"Ok",
  "country":"US",
  "zip":"12405",
  "result":{
    "state":"New York",
    "level2area":"Greene County",
    "city":"Acra"}
  }

The Zip Code API exposes the following resources:

Ressource description Endpoint Parameters
world countries list of world countries GET /api/geo/worldcountries none
country states list of states in country GET /api/geo/country/states country
state cities list of cities in state GET /api/geo/country/state/cities [country, state_id]
city zip codes list of zip codes in city GET /api/geo/country/state/city/zips [country, state_id, city_id]
zip data zip code state and city GET /api/geo/country/zip [country, zip]

Validation API

Full stack object schema validator for JSON objects.

curl https://form-api.com/api/validate?key=YOUR_API_KEY \
  --request POST \
  --header "Content-Type: application/json"  \
  --data '
  {
    "name":               {"value": "Ali", "isAlpha": true, "isLength": {"min": 2, "max": 20}, "required": true},
    "email":              {"value": "test@google.com", "isEmail":"true",  "errorMessage":"invalid email"},
    "email_confirmation": {"value": "email@g.com", "isEqual":{"ref": "email"},"errorMessage": "emails do not match"},
    "age":                {"value": 18, "isInt":{"min": 18, "max": 99}, "errorMessage":"invalid value for age"},                      
    "start_date":         {"value": "10/10/2015", "isDate": "true", "format": "MM/DD/YYYY", "errorMessage":"invalid date"},
    "end_date":           {"value": "10/11/2016", "isAfter": {"ref": "start_date"}, "format": "MM/DD/YYYY", "errorMessage": "end date should be after start date"},
    "max_products":       {"value": 77, "isInt": "true", "isGreaterThan": 0, "match": {"pattern": "^[0-9]+$"}, "errorMessage":"max products should be valid number"},
    "products":           {"value": 10, "isInt": "true", "isLowerThan": {"ref": "max_products"}, "errorMessage": "products count should be lower than max products"},
    "password":           {"value": "k!Alk84B3swo", "isStrongPassword": true, "errorMessage": "password not strong enough"},
    "repassword":         {"value": "password1", "equals": {"ref": "password"}, "errorMessage": "rePasword does not match password"}
  }'
> JSON RESPONSE:
{
  "status":"Ok",
  "valid":true
}

HTTP Request

POST https://form-api.com/api/validate

Query Parameters

Parameter Description
data A JSON object to define validation rules. please check the curl example for more details.

Available validators

Validator Description
isEmail is valid email
isAlpha contains letters only (a-zA-Z)
isAlphanumeric contains letters and numbers only
isNotEmpty is not empty
isEmpty the string has a length of zero
isLength isLength: {min: 8, max: 20} or isLength: 12
isDate is valid date. you should provide the date format
match matches the provided regular expresion. ex: match: {pattern: "^[0-9]+$", modifier: 'i'}
isInt is integer
isFloat is float
isGreaterThan used to compare numbers. ex: age: {isGreaterThan: 21} or sell_price:{isGreaterThan: {ref: 'buy_price'}}
isAfter used to compare dates. you should provide the date format
isBefore used to compare dates. you should provide the date format
isStrongPassword contains at least one uppercase, one number, one special character. min length is 8

Schema Constraints

Constraint Description
required if true, the validation will fail if the value is empty, default true.
errorMessage the error message returned when validation fails. if the errorMessage is missing, a default error message is returned.
ref refrences another input in the validation shema. check the example query for more details.

Errors

Both successful and unsuccessful calls will return HTTP response codes. The most common codes you will encounter using our API are as follows:

Error Code Description
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
404 Not Found -- The specified end point, or ressource could not be found.
405 Method Not Allowed -- You tried to access the API with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
429 Too Many Requests