Name Normalization

Overview

The Name Normalization method takes quasi-structured name data provided as a string and outputs the data in a structured manner. It also returns a likelihood based only on the order of the given name and family name as seen in the US population. At this time query parameters require all characters for names to be in the range of A-Z or a-z.

Requests

JSON

curl -H"X-FullContact-APIKey:$your_key" 'https://api.fullcontact.com/v2/name/normalizer.json?q=mr%20john%20(johnny)%20michael%20smith%20jr%20mba'

XML

curl -H"X-FullContact-APIKey:$your_key" 'https://api.fullcontact.com/v2/name/normalizer.xml?q=mr%20john%20(johnny)%20michael%20smith%20jr%20mba'

Parameters

q

The q parameter allows you to pass a quasi-structured full name string which can include standard prefix, first name, nickname, middle name, last name and suffix.

casing (optional)

  • uppercase (JOHN SMITH)
  • lowercase (john smith)
  • titlecase (John Smith)

Examples

The table below contains example API queries and responses. Values in the "q" column represent the API query input. The "Status" column contains the HTTP status code, the remaining columns contain the API response data for the query.

q Status Prefix First Name Middle Name Last Name Suffix Nickname Full Name Likelihood
John 200 John John 0.992
John Smith 200 John Smith John Smith 1
John Michael Smith 200 John Michael Smith John Michael Smith 0.95
Mr. John Michael Smith 200 Mr. John Michael Smith John Michael Smith 0.95
Mr. John Michael Smith Jr. 200 Mr. John Michael Smith Jr. John Michael Smith 0.857
Mr. John (Johnny) Michael Smith Jr. 200 Mr. John Michael Smith Jr. Johnny John Michael Smith 0.815
Mr. John (Johnny) Michael Smith CPA 200 Mr. John Michael Smith CPA Johnny John Michael Smith 0.815
John Michael Smith and Jane Doe 422

Responses

The API responds with JSON or XML.

JSON

{
  "status": 200,
  "likelihood": 0.774,
  "nameDetails": {
    "givenName": "John",
    "familyName": "Smith",
    "middleNames": 
    [
      "Michael"
    ],
    "prefixes": 
    [
      "Mr."
    ],
    "suffixes": 
    [
      "Jr.",
      "MBA"
    ],
    "nicknames": 
    [
      "Johnny"
    ],
    "fullName": "John Michael Smith"
  },
  "region": "USA"
}

XML

<?xml version="1.0" encoding="UTF-8" ?>
<person>
  <status>200</status>
  <likelihood>0.774</likelihood>
  <nameDetails>
    <givenName>John</givenName>
    <familyName>Smith</familyName>
    <middleNames>
      <middleNam>Michael</middleNam>
    </middleNames>
    <prefixes>
      <prefix>Mr.</prefix>
    </prefixes>
    <suffixes>
      <suffix>Jr.</suffix>
      <suffix>MBA</suffix>
    </suffixes>
    <nicknames>
      <nicknam>Johnny</nicknam>
    </nicknames>
    <fullName>John Michael Smith</fullName>
  </nameDetails>
  <region>USA</region>
</person>

Response Schema

The following is a description of the Name Normalization response schema. It includes every possible field, collection, and value you can expect to receive.

{
  "status": {"type":"number"},
  "likelihood": {"type":"number"},
  "nameDetails": {
    "givenName": {"type":"string"},
    "familyName": {"type":"string"},
    "middleNames": 
    [
      {"type":"string"}
    ],
    "prefixes": 
    [
      {"type":"string"}
    ],
    "suffixes": 
    [
      {"type":"string"}
    ],
    "nicknames": 
    [
      {"type":"string"}
    ],
    "fullName": {"type":"string"}
  },
  "region": {"type":"string"}
}

Name Deducer

Overview

The Name Deducer method takes a username or email address provided as a string and attempts to deduce a structured name. It also returns a likelihood based on US population data. This method is ideal for business email addresses due to the use of standard convention in corporate email address formats.

Requests

JSON

curl -H"X-FullContact-APIKey:$your_key" 'https://api.fullcontact.com/v2/name/deducer.json?email=johndsmith79@business.com'

XML

curl -H"X-FullContact-APIKey:$your_key" 'https://api.fullcontact.com/v2/name/deducer.xml?email=johndsmith79@business.com'

Parameters

email

The email parameter allows you to pass an email address.

curl -H"X-FullContact-APIKey:$your_key" 'https://api.fullcontact.com/v2/name/deducer.json?email=johndsmith79@business.com'

username

The username parameter allows you to pass a username.

curl -H"X-FullContact-APIKey:$your_key" 'https://api.fullcontact.com/v2/name/deducer.json?username=johndsmith79'

casing (optional)

  • uppercase (JOHN SMITH)
  • lowercase (john smith)
  • titlecase (John Smith)

Responses

The API responds with JSON or XML.

JSON

{
  "status": 200,
  "likelihood": 0.665,
  "nameDetails":  {
    "givenName": "John",
    "familyName": "Smith",
    "middleNames":  [
      "D."
    ],
    "fullName": "John D. Smith"
  },
  "region": "USA"
}

XML

<?xml version="1.0" encoding="UTF-8"?>
<person>
  <status>200</status>
  <likelihood>0.665</likelihood>
  <nameDetails>
    <givenName>John</givenName>
    <familyName>Smith</familyName>
    <middleNames>
      <middleNam>D.</middleNam>
    </middleNames>
    <fullName>John D. Smith</fullName>
  </nameDetails>
  <region>USA</region>
</person>

Response Schema

The following is a description of the Name Deducer response schema. It includes every possible field, collection, and value you can expect to receive.

{
  "status": {"type":"number"},
  "likelihood": {"type":"number"},
  "nameDetails":  {
    "givenName": {"type":"string"},
    "familyName": {"type":"string"},
    "middleNames":  [
      {"type":"string"}
    ],
    "fullName": {"type":"string"}
  },
  "region": {"type":"string"}
}

Name Similarity

Overview

The Name Similarity endpoint compares two names, given as the parameters q1 and q2, and returns a score indicating how similar they are. As the performance of different similarity algorithms can vary over different data sets, the endpoint provides 3 separate choices.

Requests

JSON

curl -H"X-FullContact-APIKey:$your_key" 'https://api.fullcontact.com/v2/name/similarity.json?q1=john&q2=johnathan'

XML

curl -H"X-FullContact-APIKey:$your_key" 'https://api.fullcontact.com/v2/name/similarity.xml?q1=john&q2=johnathan'

Parameters

q1,q2

The q1 and q2 parameters allow you to pass two names to compare.

casing (optional)

  • uppercase (JOHN SMITH)
  • lowercase (john smith)
  • titlecase (John Smith)

Responses

The API responds with JSON or XML.

JSON

{
  "result":  {
    "SimMetrics":  {
      "jaroWinkler":  {
        "similarity": 0.8,
        "timeEstimated": 0.0017368001,
        "timeActual": 0
      },
      "levenshtein":  {
        "similarity": 0.39999998,
        "timeEstimated": 0.0072,
        "timeActual": 0
      }
    },
    "SecondString":  {
      "jaroWinkler":  {
        "similarity": 0.7999999999999999,
        "timeTaken": "3 ms"
      },
      "levenshtein":  {
        "similarity": 0.4,
        "timeTaken": "3 ms",
        "distance": 6
      },
      "level2jaroWinkler":  {
        "similarity": 0.888888888888889,
        "timeTaken": "3 ms"
      },
      "level2levenshtein":  {
        "similarity": 0.5,
        "timeTaken": "1 ms",
        "distance": 5
      }
    },
    "FullContact":  {
      "BigramAnalysis":  {
        "dice":  {
          "similarity": 0.5,
          "timeTaken": "15 ms"
        }
      }
    }
  },
  "status": 200
}

XML

<?xml version="1.0" encoding="UTF-8"?>
<Similarity>
  <result>
    <SimMetrics>
      <jaroWinkler>
        <similarity>0.8</similarity>
        <timeEstimated>0.0017368001</timeEstimated>
        <timeActual>0</timeActual>
      </jaroWinkler>
      <levenshtein>
        <similarity>0.39999998</similarity>
        <timeEstimated>0.0072</timeEstimated>
        <timeActual>0</timeActual>
      </levenshtein>
    </SimMetrics>
    <SecondString>
      <jaroWinkler>
        <similarity>0.7999999999999999</similarity>
        <timeTaken>0 ms</timeTaken>
      </jaroWinkler>
      <levenshtein>
        <similarity>0.4</similarity>
        <timeTaken>0 ms</timeTaken>
        <distance>6.0</distance>
      </levenshtein>
      <level2jaroWinkler>
        <similarity>0.888888888888889</similarity>
        <timeTaken>0 ms</timeTaken>
      </level2jaroWinkler>
      <level2levenshtein>
        <similarity>0.5</similarity>
        <timeTaken>0 ms</timeTaken>
        <distance>5.0</distance>
      </level2levenshtein>
    </SecondString>
    <FullContact>
      <BigramAnalysis>
        <dice>
          <similarity>0.5</similarity>
          <timeTaken>1 ms</timeTaken>
        </dice>
      </BigramAnalysis>
    </FullContact>
  </result>
  <status>200</status>
</Similarity>

Response Schema

The following is a description of the Name Similarity response schema. It includes every possible field, collection, and value you can expect to receive.

{
  "result":  {
    "SimMetrics":  {
      "jaroWinkler":  {
        "similarity": {"type":"number"},
        "timeEstimated": {"type":"number"},
        "timeActual": {"type":"number"}
      },
      "levenshtein":  {
        "similarity": {"type":"number"},
        "timeEstimated": {"type":"number"},
        "timeActual": {"type":"number"}
      }
    },
    "SecondString":  {
      "jaroWinkler":  {
        "similarity": {"type":"number"},
        "timeTaken": {"type":"string"}
      },
      "levenshtein":  {
        "similarity": {"type":"number"},
        "timeTaken": {"type":"string"},
        "distance": {"type":"number"}
      },
      "level2jaroWinkler":  {
        "similarity": {"type":"number"},
        "timeTaken": {"type":"string"}
      },
      "level2levenshtein":  {
        "similarity": {"type":"number"},
        "timeTaken": {"type":"string"},
        "distance": {"type":"number"}
      }
    },
    "FullContact":  {
      "BigramAnalysis":  {
        "dice":  {
          "similarity": {"type":"number"},
          "timeTaken": {"type":"string"}
        }
      }
    }
  },
  "status": {"type":"number"}
}

Name Stats

Overview

The Name Stats method has a variety of parameters that can be used to determine more about a name. Some of the things that can be determined are:

  • The likelihood the name is a given name or last name.
  • The likelihood the person with the name is male or female.
  • The estimated count of living people with the name in the US.
  • The rank of popularity of the name in the US.
  • The frequency in the US population that the name occurs.
  • The mean age of people with the particular name.
  • The mode age of people with the particular name.
  • The quartiles and median age of people with the particular name.

NOTE: All statistics are based on US population numbers only. More information on the math behind the Name API can be found here.

Requests

JSON

curl -H"X-FullContact-APIKey:$your_key" 'https://api.fullcontact.com/v2/name/stats.json?name=john'

XML

curl -H"X-FullContact-APIKey:$your_key" 'https://api.fullcontact.com/v2/name/stats.xml?name=john'

Parameters

name

The name parameter can be used when you only know a single name and you are uncertain whether it is the given name or family name.

curl -H"X-FullContact-APIKey:$your_key" 'https://api.fullcontact.com/v2/name/stats.json?name=john'

givenName

The givenName parameter can be used when you know that the name is a given name (first name).

curl -H"X-FullContact-APIKey:$your_key" 'https://api.fullcontact.com/v2/name/stats.json?givenName=john'

familyName

The familyName parameter can be used when you know that the name is a family name (last name).

curl -H"X-FullContact-APIKey:$your_key" 'https://api.fullcontact.com/v2/name/stats.json?familyName=smith'

givenName & familyName

The givenName and familyName parameters can be used together when you know both the first name and last name of the person.

curl -H"X-FullContact-APIKey:$your_key" 'https://api.fullcontact.com/v2/name/stats.json?givenName=john&familyName=smith'

casing (optional)

  • uppercase (JOHN SMITH)
  • lowercase (john smith)
  • titlecase (John Smith)

Responses

name

JSON

{
  "status": 200,
  "name": {
    "value": "John",
    "given": {
      "likelihood": 0.992,
      "count": 3499150,
      "rank": 3,
      "male": {
        "count": 3484136,
        "likelihood": 0.996,
        "rank": 3,
        "frequencyRatio": 0.026305137,
        "age": {
          "densityCurve": {
            "mode": {
              "count": 77174,
              "modeAge": 
              [
                47
              ]
            },
            "meanAge": 51.2,
            "quartiles": {
              "q1": 35.3,
              "q2": 50.5,
              "q3": 62.9
            }
          }
        }
      },
      "female": {
        "count": 15015,
        "likelihood": 0.004,
        "rank": 928,
        "frequencyRatio": 0.00011386,
        "age": {
          "densityCurve": {
            "mode": {
              "count": 297,
              "modeAge": 
              [
                43
              ]
            },
            "meanAge": 48.5,
            "quartiles": {
              "q1": 34.8,
              "q2": 49.4,
              "q3": 69.4
            }
          }
        }
      }
    },
    "family": {
      "likelihood": 0.008,
      "count": 27643,
      "rank": 1161,
      "frequencyRatio": 0.00011417
    }
  },
  "region": "USA"
}

XML

<?xml version="1.0" encoding="UTF-8" ?>
<person>
 <status>200</status>
 <name>
   <value>John</value>
   <given>
     <likelihood>0.992</likelihood>
     <count>3499150</count>
     <rank>3.0</rank>
     <male>
       <count>3484136</count>
       <likelihood>0.996</likelihood>
       <rank>3.0</rank>
       <frequencyRatio>0.026305137</frequencyRatio>
       <age>
         <densityCurve>
           <mode>
             <count>77174</count>
             <modeAge>
               <modeAge>47.0</modeAge>
             </modeAge>
           </mode>
           <meanAge>51.2</meanAge>
           <quartiles>
             <q1>35.3</q1>
             <q2>50.5</q2>
             <q3>62.9</q3>
           </quartiles>
         </densityCurve>
       </age>
     </male>
     <female>
       <count>15015</count>
       <likelihood>0.004</likelihood>
       <rank>928.0</rank>
       <frequencyRatio>0.00011386</frequencyRatio>
       <age>
         <densityCurve>
           <mode>
             <count>297</count>
             <modeAge>
               <modeAge>43.0</modeAge>
             </modeAge>
           </mode>
           <meanAge>48.5</meanAge>
           <quartiles>
             <q1>34.8</q1>
             <q2>49.4</q2>
             <q3>69.4</q3>
           </quartiles>
         </densityCurve>
       </age>
     </female>
   </given>
   <family>
     <likelihood>0.008</likelihood>
     <count>27643</count>
     <rank>1161</rank>
     <frequencyRatio>0.00011417</frequencyRatio>
   </family>
 </name>
 <region>USA</region>
</person>

givenName

JSON

{
  "status": 200,
  "name": {
    "value": "John",
    "given": {
      "count": 3499150,
      "rank": 3,
      "male": {
        "count": 3484136,
        "likelihood": 0.996,
        "rank": 3,
        "frequencyRatio": 0.026305137,
        "age": {
          "densityCurve": {
            "mode": {
              "count": 77174,
              "modeAge": 
              [
                47
              ]
            },
            "meanAge": 51.2,
            "quartiles": {
              "q1": 35.3,
              "q2": 50.5,
              "q3": 62.9
            }
          }
        }
      },
      "female": {
        "count": 15015,
        "likelihood": 0.004,
        "rank": 928,
        "frequencyRatio": 0.00011386,
        "age": {
          "densityCurve": {
            "mode": {
              "count": 297,
              "modeAge": 
              [
                43
              ]
            },
            "meanAge": 48.5,
            "quartiles": {
              "q1": 34.8,
              "q2": 49.4,
              "q3": 69.4
            }
          }
        }
      }
    }
  },
  "region": "USA"
}

XML

<?xml version="1.0" encoding="UTF-8" ?>
<person>
  <status>200</status>
  <name>
    <value>John</value>
    <given>
      <count>3499150</count>
      <rank>3.0</rank>
      <male>
        <count>3484136</count>
        <likelihood>0.996</likelihood>
        <rank>3.0</rank>
        <frequencyRatio>0.026305137</frequencyRatio>
        <age>
          <densityCurve>
            <mode>
              <count>77174</count>
              <modeAge>
                <modeAge>47.0</modeAge>
              </modeAge>
            </mode>
            <meanAge>51.2</meanAge>
            <quartiles>
              <q1>35.3</q1>
              <q2>50.5</q2>
              <q3>62.9</q3>
            </quartiles>
          </densityCurve>
        </age>
      </male>
      <female>
        <count>15015</count>
        <likelihood>0.004</likelihood>
        <rank>928.0</rank>
        <frequencyRatio>0.00011386</frequencyRatio>
        <age>
          <densityCurve>
            <mode>
              <count>297</count>
              <modeAge>
                <modeAge>43.0</modeAge>
              </modeAge>
            </mode>
            <meanAge>48.5</meanAge>
            <quartiles>
              <q1>34.8</q1>
              <q2>49.4</q2>
              <q3>69.4</q3>
            </quartiles>
          </densityCurve>
        </age>
      </female>
    </given>
  </name>
  <region>USA</region>
</person>

familyName

JSON

{
  "status": 200,
  "name": {
    "value": "Smith",
    "family": {
      "count": 2376206,
      "rank": 1,
      "frequencyRatio": 0.009814123
    }
  },
  "region": "USA"
}

XML

<?xml version="1.0" encoding="UTF-8" ?>
<person>
  <status>200</status>
  <name>
    <value>Smith</value>
    <family>
      <count>2376206</count>
      <rank>1</rank>
      <frequencyRatio>0.009814123</frequencyRatio>
    </family>
  </name>
  <region>USA</region>
</person>

givenName & familyName

JSON

{
  "status": 200,
  "name": {
    "value": "John Smith",
    "given": {
      "count": 3499150,
      "rank": 3,
      "male": {
        "count": 3484136,
        "likelihood": 0.996,
        "rank": 3,
        "frequencyRatio": 0.026305137,
        "age": {
          "densityCurve": {
            "mode": {
              "count": 77174,
              "modeAge": 
              [
                47
              ]
            },
            "meanAge": 51.2,
            "quartiles": {
              "q1": 35.3,
              "q2": 50.5,
              "q3": 62.9
            }
          }
        }
      },
      "female": {
        "count": 15015,
        "likelihood": 0.004,
        "rank": 928,
        "frequencyRatio": 0.00011386,
        "age": {
          "densityCurve": {
            "mode": {
              "count": 297,
              "modeAge": 
              [
                43
              ]
            },
            "meanAge": 48.5,
            "quartiles": {
              "q1": 34.8,
              "q2": 49.4,
              "q3": 69.4
            }
          }
        }
      }
    },
    "family": {
      "count": 2376206,
      "rank": 1,
      "frequencyRatio": 0.009814123
    }
  },
  "region": "USA"
}

XML

<?xml version="1.0" encoding="UTF-8" ?>
<person>
  <status>200</status>
  <name>
    <value>John Smith</value>
    <given>
      <count>3499150</count>
      <rank>3.0</rank>
      <male>
        <count>3484136</count>
        <likelihood>0.996</likelihood>
        <rank>3.0</rank>
        <frequencyRatio>0.026305137</frequencyRatio>
        <age>
          <densityCurve>
            <mode>
              <count>77174</count>
              <modeAge>
                <modeAge>47.0</modeAge>
              </modeAge>
            </mode>
            <meanAge>51.2</meanAge>
            <quartiles>
              <q1>35.3</q1>
              <q2>50.5</q2>
              <q3>62.9</q3>
            </quartiles>
          </densityCurve>
        </age>
      </male>
      <female>
        <count>15015</count>
        <likelihood>0.004</likelihood>
        <rank>928.0</rank>
        <frequencyRatio>0.00011386</frequencyRatio>
        <age>
          <densityCurve>
            <mode>
              <count>297</count>
              <modeAge>
                <modeAge>43.0</modeAge>
              </modeAge>
            </mode>
            <meanAge>48.5</meanAge>
            <quartiles>
              <q1>34.8</q1>
              <q2>49.4</q2>
              <q3>69.4</q3>
            </quartiles>
          </densityCurve>
        </age>
      </female>
    </given>
    <family>
      <count>2376206</count>
      <rank>1</rank>
      <frequencyRatio>0.009814123</frequencyRatio>
    </family>
  </name>
  <region>USA</region>
</person>

Response Schema

The following is a description of the Name Stats response schema. It includes every possible field, collection, and value you can expect to receive.

{
  "status": {"type":"number"},
  "name": {
    "value": {"type":"string"},
    "given": {
      "count": {"type":"number"},
      "rank": {"type":"number"},
      "male": {
        "count": {"type":"number"},
        "likelihood": {"type":"number"},
        "rank": {"type":"number"},
        "frequencyRatio": {"type":"number"},
        "age": {
          "densityCurve": {
            "mode": {
              "count": {"type":"number"},
              "modeAge": 
              [
                {"type":"number"}
              ]
            },
            "meanAge": {"type":"number"},
            "quartiles": {
              "q1": {"type":"number"},
              "q2": {"type":"number"},
              "q3": {"type":"number"}
            }
          }
        }
      },
      "female": {
        "count": {"type":"number"},
        "likelihood": {"type":"number"},
        "rank": {"type":"number"},
        "frequencyRatio": {"type":"number"},
        "age": {
          "densityCurve": {
            "mode": {
              "count": {"type":"number"},
              "modeAge": 
              [
                {"type":"number"}
              ]
            },
            "meanAge": {"type":"number"},
            "quartiles": {
              "q1": {"type":"number"},
              "q2": {"type":"number"},
              "q3": {"type":"number"}
            }
          }
        }
      }
    },
    "family": {
      "count": {"type":"number"},
      "rank": {"type":"number"},
      "frequencyRatio": {"type":"number"}
    }
  },
  "region": {"type":"string"}
}

Name Parser

Overview

The Name Parser method can be used when you have two names but don't know which one is the first name and which is the last name. Pass the name to this endpoint via the q parameter.

Requests

JSON

curl -H"X-FullContact-APIKey:$your_key" 'https://api.fullcontact.com/v2/name/parser.json?q=john%20smith'

XML

curl -H"X-FullContact-APIKey:$your_key" 'https://api.fullcontact.com/v2/name/parser.xml?q=john%20smit'

Parameters

q

The q parameter allows you to pass an ambiguous name and determine what the given name and family name is.

casing (optional)

  • uppercase (JOHN SMITH)
  • lowercase (john smith)
  • titlecase (John Smith)

Examples

The table below contains example API queries and responses. Values in the "q" column represent the API query input. The "Status" column contains the HTTP status code, the remaining columns contain the API response data for the query.

q Status First Name Last Name Likelihood
John 422
John Smith 200 John Smith 1
Smith John 200 John Smith 1
John Michael-Smith 200 John Michael-Smith 0.873
Jane Maria Doe 422

Responses

The API responds with JSON or XML.

JSON

{
  "status": 200,
  "ambiguousName": "John Smith",
  "result": {
    "givenName": "John",
    "familyName": "Smith",
    "likelihood": 1
  },
  "region": "USA"
}

XML

<?xml version="1.0" encoding="UTF-8" ?>
<person>
  <status>200</status>
  <ambiguousName>John Smith</ambiguousName>
  <result>
    <givenName>John</givenName>
    <familyName>Smith</familyName>
    <likelihood>1</likelihood>
  </result>
  <region>USA</region>
</person>

Response Schema

The following is a description of the Name Parser response schema. It includes every possible field, collection, and value you can expect to receive.

{
  "status": {"type":"number"},
  "ambiguousName": {"type":"string"},
  "result": {
    "givenName": {"type":"string"},
    "familyName": {"type":"string"},
    "likelihood": {"type":"number"}
  },
  "region": {"type":"string"}
}

Name API Flow Diagram

Name Flow Diagram