Age verification endpoints

This section describes the APIs that are used for verifying an individual's age and storing the responses.

Note: Running these APIs in production will incur costs. Review the Avalara Supplemental Terms for more information.

Verify age

The VerifyAge endpoint is used to determine whether a purchaser or recipient can legally purchase or receive alcoholic beverages in the specified jurisdiction. AvaTax will consider the address and (optional) date of birth specified in the request. If the response results in anisOfAge value offalse, then the endpoint will also return one or more of the following failure codes:

not_found: A public records search did not return any results for the subject.
dob_unverifiable: A public records search did not return a DoB, or the DoB does not match public records.
under_age: The subject is below 21 years of age.
suspected_fraud: Based on the input data, the subject is associated with a high-risk alert from IDology.
deceased: Public records indicate that the subject is deceased.
unknown_error: An unknown error occurred. Please contact Avalara support.

Endpoint

POST /api/v2/ageverification/verify

Input fields for age verification

The table below describes the required and optional fields for the age verification request.

Field name	Description	Required?
`firstName`	The first name of the person whose age you want to verify.	Yes
`lastName`	The last name of the person whose age you want to verify.	Yes
`address`	The address of the person whose age you want to verify. One of the following sets of attributes are required for`address`: `line1`,`city`,`region` `line1`,`postalCode` A`country` field can also be provided, but only`US` and`USA` are valid.	Yes
`DOB`	The ISO-8601 compliant date of birth of the person whose age you want to verify. Note that a date of birth can be specified in a transaction using the`PurchaserDOB` and`RecipientDOB` parameters.	No

Parameters

The table below describes a parameter that can specified in the age verification request URL on Sandbox only. For example:

https://sandbox-rest.avatax.com/api/v2/ageverification/verify?simulatedFailureCode=under_age

Note: ThesimulatedFailureCode parameter is only available in Sandbox. You will receive an error if you attempt to use this in Production. This optional parameter provides you with a method for testing whether your integration can consume these failure codes, without incurring costs associated with running this endpoint in production.

Request

curl
    -X POST
    -H 'Accept: application/json'
    -H 'Authorization: Basic aHR0cHdhdQNoOmY='
    -H 'Content-Type: application/json'
    --data '{
      {
        "firstName": "John",
        "lastName": "Doe",
        "address": {
          "line1": "255 S King St",
          "city": "Seattle",
          "region": "WA",
          "country": "US",
          "postalCode": "98104"
        },
        "DOB": "1994-10-01"
      }
    }
    'https://sandbox-rest.avatax.com/api/v2/ageverification/verify'

Response

The response returns"isOfAge": true if purchaser or recipient is within the legal age limit. If the verification fails, the response returns"isOfAge":false, and thefailureCodes line in the response will describe the reason.

{
  "isOfAge": true,
  "failureCodes": []
}

Store verification

The VerifyAge endpoint verifies a person's age using IDology's age verification service. If you use another service, run the StoreAgeVerification endpoint to store an age verification response from another provider whereisOfAge istrue.

Endpoint

PUT /api/v2/ageverification/store/identity

Input fields for store verification

The table below describes the required and optional fields for the store age verification request.

Field name	Description	Required?
`firstName`	The first name of the person whose age you want to verify.	Yes
`lastName`	The last name of the person whose age you want to verify.	Yes
`address`	The address of the person whose age you want to verify. One of the following sets of attributes are required for`address`: `line1`,`city`,`region` `line1`,`postalCode` A`country` field can also be provided, but only`US` and`USA` are valid.	Yes
`DOB`	The ISO-8601 compliant date of birth of the person whose age you want to verify. Note that a date of birth can be specified in a transaction using the`PurchaserDOB` and`RecipientDOB` parameters.	No
`isOfAge`	A Boolean indicating whether the individual is within the legal limit to purchase or receive alcohol. Specify this in a response model.	Yes
`failureCodes`	A list of failure codes that describe why the response returns`isOfAge=false`. Available failure codes include: `not_found` `dob_unverifiable` `under_age` `suspected_fraud` `deceased` `unknown_error`	Yes

Request

The following request stores a verification for a person whose date of birth could not be verified and is deceased.

curl
    -X POST
    -H 'Accept: application/json'
    -H 'Authorization: Basic aHR0cHdhdQNoOmY='
    -H 'Content-Type: application/json'
    --data '{
      "request": {
        "firstName": "John",
        "lastName": "Doe",
        "address": {
          "line1": "255 S King St",
          "city": "Seattle",
          "region": "WA",
          "country": "US",
          "postalCode": "98104"
        },
        "DOB": "1994-10-01"
      },
      "response": {
        "isOfAge": false,
        "failureCodes": [
          "deceased",
          "dob_unverifiable"
        ]
      }
    }'
    'https://sandbox-rest.avatax.com/api/v2/ageverification/store/identity'

Response

The response returns 204 upon success.

Find an age verification record

Run the FindAgeVerification endpoint to retrieve a previously stored age verification response.

Endpoint

PUT /api/v2/ageverification/store/identity/find

Input fields for find verification

The table below describes the required and optional fields for the find age verification request.

Field name	Description	Required?
`firstName`	The first name of the person whose age you want to verify.	Yes
`lastName`	The last name of the person whose age you want to verify.	Yes
`address`	The address of the person whose age you want to verify. One of the following sets of attributes are required for`address`: `line1`,`city`,`region` `line1`,`postalCode` A`country` field can also be provided, but only`US` and`USA` are valid.	Yes
`DOB`	The ISO-8601 compliant date of birth of the person whose age you want to verify. Note that a date of birth can be specified in a transaction using the`PurchaserDOB` and`RecipientDOB` parameters.	No

Request

curl
    -X POST
    -H 'Accept: application/json'
    -H 'Authorization: Basic aHR0cHdhdQNoOmY='
    -H 'Content-Type: application/json'
    --data '{
      "firstName": "John",
      "lastName": "Doe",
      "address": {
        "line1": "255 S King St",
        "city": "Seattle",
        "region": "WA",
        "country": "US",
        "postalCode": "98104"
      },
      "DOB": "1994-10-01"
    }'
    'https://sandbox-rest.avatax.com/api/v2/ageverification/store/identity/find'

Response

The response returns information about the stored age verification.

{
  "isOfAge": false,
  "failureCodes": [
    "deceased",
    "dob_unverifiable"
  ],
  "createdUtc": "2022-10-07T18:40:53.534Z"
}

Store if verified

The StoreIfVerified endpoint conditionally performs an age verification check. If a record matching the request is found, the associated response is returned. If a record matching the request is not found, then an age verification check is performed, and the response is stored if the individual is determined to be of age.

Endpoint

POST api/v2/ageverification/store/identity/storeIfVerified

Input fields for store if verified

The table below describes the required and optional fields for the store if verified request.

Field name	Description	Required?
`firstName`	The first name of the person whose age you want to verify.	Yes
`lastName`	The last name of the person whose age you want to verify.	Yes
`address`	The address of the person whose age you want to verify. One of the following sets of attributes are required for`address`: `line1`,`city`,`region` `line1`,`postalCode` A`country` field can also be provided, but only`US` and`USA` are valid.	Yes
`DOB`	The ISO-8601 compliant date of birth of the person whose age you want to verify. Note that a date of birth can be specified in a transaction using the`PurchaserDOB` and`RecipientDOB` parameters.	No

Parameters

The table below describes a parameter that can specified in the store if verified request URL on Sandbox only. For example:

https://sandbox-rest.avatax.com/api/v2/ageverification/store/identify/storeIfVerified?simulatedFailureCode=not_found

Request

This request searches the internal store for an existing age verification record. If the record does not exist, the request then runs an age verification check and stores the response ifisOfAge=true.

curl
    -X POST
    -H 'Accept: application/json'
    -H 'Authorization: Basic aHR0cHdhdQNoOmY='
    -H 'Content-Type: application/json'
    --data '{
      "firstName": "John",
      "lastName": "Doe",
      "address": {
        "line1": "255 S King St",
        "city": "Seattle",
        "region": "WA",
        "country": "US",
        "postalCode": "98104"
      },
      "DOB": "1994-10-01"
    }'
    'https://sandbox-rest.avatax.com/api/v2/ageverification/store/identity/storeIfVerified'

Response

The response returns a record that already exists for this individual.

{
  "isOfAge": false,
  "failureCodes": [
    "deceased",
    "dob_unverifiable"
  ],
  "fromStore": true,
  "createdUtc": "2022-10-07T18:40:53.534Z"
}

Previous Next