Introduction

Base URL

https://barcodes.fakeidsolutions.com/api/v2/

Explore the barcode service API documentation and examples to integrate our barcode service into your application or workflow.

The barcode service API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Authentication

Authenticated Request

curl https://barcodes.fakeidsolutions.com/api/v2/ \
  -H "Authorization: Bearer <token>"

Make sure to replace <token> with your API key.

The barcode service uses API keys to authenticate requests. You can view and manage your API key on your account page.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

The barcode service expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer <token>

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

You must replace <token> with your secret API key.

Balance

GET /api/v2/balance

curl https://barcodes.fakeidsolutions.com/api/v2/balance \
  -H "Authorization: Bearer <token>"

Response

{
  "credits": 50
}

Retrieves the current account balance, for the account that was authenticated in the request.

HTTP Request

GET /api/v2/balance

Parameters

No parameters.

Jurisdictions

GET /api/v2/jurisdictions

curl https://barcodes.fakeidsolutions.com/api/v2/jurisdictions \
  -H "Authorization: Bearer <token>"

Response

{
  "USA": {
    "AL": {
      "name": "Alabama",
      "iin": "636033"
    },
    "AK": {
      "name": "Alaska",
      "iin": "636059"
    },
    ...
    "WI": {
      "name": "Wisconsin",
      "iin": "636031"
    },
    "WY": {
      "name": "Wyoming",
      "iin": "636060"
    }
  },
  "CAN": {
    "AB": {
      "name": "Alberta",
      "iin": "604432"
    },
    "BC": {
      "name": "British Columbia",
      "iin": "636028"
    },
    ...
    "SK": {
      "name": "Saskatchewan",
      "iin": "636044"
    },
    "YT": {
      "name": "Yukon Territory",
      "iin": "604429"
    }
  }
}

Retrieves available jurisdictions and their corresponding issuer identification number (IIN).

When a jurisdiction must be specified for an endpoint, it may be specified by:

Issuer Identification Number (IIN): 636033
Country and Jurisdiction Code: USA-AL
Jurisdiction Code: AL
Jurisdiction Name: Alabama

HTTP Request

GET /api/v2/jurisdictions

Parameters

Parameter	Required	Description
country	false	Filter jurisdictions by country code. Must be `USA` or `CAN`.

Revisions

GET /api/v2/revisions

curl https://barcodes.fakeidsolutions.com/api/v2/revisions \
  -X "GET" -G \
  -H "Authorization: Bearer <token>" \
  -d "jurisdiction=636010"

Response

{
  "0900-2020": {
    "revision": "2020-03-01",
    "aamva_version": "09",
    "jurisdiction_version": "00",
    "start": "2020-08-01",
    "end": null
  },
  "0900-2019": {
    "revision": "2019-05-01",
    "aamva_version": "09",
    "jurisdiction_version": "00",
    "start": "2019-05-01",
    "end": "2020-08-01"
  },
  "0900-2017": {
    "revision": "2017-03-16",
    "aamva_version": "09",
    "jurisdiction_version": "00",
    "start": "2017-08-01",
    "end": "2019-08-01"
  },
  "0102": {
    "revision": "2012-09-01",
    "aamva_version": "01",
    "jurisdiction_version": "02",
    "start": "2012-09-01",
    "end": "2014-06-01"
  }
}

Retrieves available revisions, organized by revision code.

When a revision may be specified for an endpoint, it must be specified by the revision code (e.g. 1000 or 0900-2020). If no revision is specified, the latest revision is used.

HTTP Request

GET /api/v2/revisions

Parameters

Parameter	Required	Description
jurisdiction	true	IIN (`636033`), country and jurisdiction code (`USA-AL`), jurisdiction code (`AL`), or name (`Alabama`).

Data Elements

GET /api/v2/elements

curl https://barcodes.fakeidsolutions.com/api/v2/elements \
  -X "GET" -G \
  -H "Authorization: Bearer <token>" \
  -d "jurisdiction=636010" \
  -d "revision=0900-2020"

Response

{
  "DL": {
    "DAQ": {
      "element": "Drivers License Number",
      "type": "text",
      "default": "",
      "options": []
    },
    "DCS": {
      "element": "Customer Family Name",
      "type": "text",
      "default": "NONE",
      "options": []
    },
    "DDE": {
      "element": "Family Name Truncation",
      "type": "text",
      "default": "N",
      "options": {
        "T": "Truncated",
        "N": "Not Truncated",
        "U": "Unknown"
      }
    },
    ...
    "DDJ": {
      "element": "Under 21 Until",
      "type": "date",
      "default": "",
      "options": []
    },
    "DDK": {
      "element": "Organ Donor Indicator",
      "type": "text",
      "default": 0,
      "options": [
        "No",
        "Yes"
      ]
    },
    "DDL": {
      "element": "Veteran Indicator",
      "type": "text",
      "default": 0,
      "options": [
        "No",
        "Yes"
      ]
    }
  },
  "ZF": {
    "ZFA": {
      "element": "Replaced Date",
      "type": "text",
      "default": "",
      "options": []
    },
    "ZFB": {
      "element": "Special Restrictions",
      "type": "text",
      "default": "",
      "options": []
    },
    "ZFC": {
      "element": "Safe Driver Indicator",
      "type": "text",
      "default": "SAFE DRIVER",
      "options": {
        "SAFE DRIVER": "Yes",
        "": "No"
      }
    },
    ...
    "ZFI": {
      "element": "Fish & Wildlife Designations",
      "type": "text",
      "default": "",
      "options": {
        "": "None",
        "SP": "Sportsman",
        "BO": "Boater",
        "FW": "Freshwater Fishing",
        "SW": "Saltwater Fishing",
        "HT": "Hunting"
      }
    },
    "ZFJ": {
      "element": "Customer Number",
      "type": "text",
      "default": "",
      "options": []
    },
    "ZFK": {
      "element": "Reserved for Future Use",
      "type": "text",
      "default": "",
      "options": []
    }
  }
}

Retrieves all data elements for the specified jurisdiction and revision.

HTTP Request

GET /api/v2/elements

Parameters

Parameter	Required	Description
jurisdiction	true	IIN (`636033`), country and jurisdiction code (`USA-AL`), jurisdiction code (`AL`), or name (`Alabama`).
revision	false	Revision code (e.g. `1000` or `0900-2020`)

Generate Barcode

POST /api/v2/barcode

curl https://barcodes.fakeidsolutions.com/api/v2/barcode \
  -X "POST" \
  -H "Authorization: Bearer <token>" \
  -H "Accept: text/plain" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "jurisdiction=636010" \
  -d "revision=0900-2020" \
  -d "data[DAC]=John" \
  -d "data[DCS]=Doe" \
  -d "data[DAG]=123 Cherry Avenue" \
  -d "data[DAI]=Panama City" \
  -d "data[DAJ]=FL" \
  -d "data[DAK]=32404" \
  -d "data[DBC]=1" \
  -d "data[DAU]=70" \
  -d "data[DDA]=F"

Response

@

ANSI 636010090002DL00410259ZF03000056DLDAQD000460032180
DCSDOE
DDEN
DACJOHN
DDFN
DADNONE
DDGN
DCAE
DCBNONE
DCDNONE
DBD09202020
DBB06182003
DBA06182028
DBC1
DAU070 IN
DAG123 CHERRY AVENUE
DAIPANAMA CITY
DAJFL
DAK324040000  
DCFE802009203873
DCGUSA
DCK0100291578060730
DDAF
DDB03012020
DDJ06182024
ZFZFA
ZFB
ZFC
ZFD
ZFE
ZFF
ZFG
ZFH
ZFI
ZFJ0726870711
ZFK

Generates a new PDF417 barcode. All data elements will be appropriately processed, truncated, and formatted. Any data elements not provided will be generated automatically.

If the save parameter is true, the barcode ID will be returned in the response X-Barcode-ID header. This barcode ID can be passed to other endpoints to work with the same barcode without generating it again.

HTTP Request

POST /api/v2/barcode

Parameters

Parameter	Required	Description
jurisdiction	true	You must identify the jurisdiction by one of: Issuer Identification Number (IIN): e.g. `636033` Country and Jurisdiction Code: e.g. `USA-AL` Jurisdiction Code: e.g. `AL` Jurisdiction Name: e.g. `Alabama` For best results, we recommend using the IIN.
revision	false	Barcode revision code (e.g. `1000` or `0900-2020`) If not specified, the latest revision will be used.
document	false	Document type: Drivers License: `DL` Identification Card: `ID` Commercial Drivers License: `CDL` Default: `DL`
save	false	Save the generated barcode to your barcode history. The saved barcode ID will be returned in the `X-Barcode-ID` response header. Default: `true`
data	true	Array of input data. The keys must be valid data elements (e.g. `DCS`). Any data elements not provided will be automatically generated. Elements of type `date` must be formatted as `YYYY-MM-DD`.

Response

The response type is determined by the MIME type in the Accept header.

image/png: PNG
image/jpeg: JPEG
image/bmp: BMP
image/svg+xml: SVG
application/json: Processed data
text/plain: Raw barcode data

If an invalid MIME type is provided, the server will return 415 Unsupported Media Type.

Export PDF417 Barcode

GET /api/v2/export

curl https://barcodes.fakeidsolutions.com/api/v2/export \
  -X "GET" -G \
  -H "Authorization: Bearer <token>" \
  -H "Accept: image/png" \
  -d "barcode_id=00000000-0000-4000-0000-000000000000"

Accept: image/png or Accept: image/jpeg or Accept: image/bmp

Binary output

Accept: image/svg+xml

XML-based file format

Accept: text/plain

@
ANSI 636010090002DL00410259ZF03000056DLDAQD000460032670
DCSDOE
DDEN
DACJOHN
DDFN
DADNONE
DDGN
DCAE
DCBNONE
DCDNONE
DBD04092023
DBB07272003
DBA07272031
DBC1
DAU070 IN
DAG123 CHERRY AVENUE
DAIPANAMA CITY
DAJFL
DAK324040000  
DCFM712304093106
DCGUSA
DCK0100740380994582
DDAF
DDB03012020
ZFZFA272024
ZFB
ZFC
ZFD
ZFE
ZFF
ZFG
ZFH
ZFI
ZFJ0445764164

Accept: application/json

{
  "barcode_id": "9beb6b69-2323-4753-9669-594a53a66ac7",
  "jurisdiction": "Florida",
  "revision": "0900-2020",
  "data": {
    "document": "DL",
    "DAQ": "D000460032670",
    "DCS": "DOE",
    "DDE": "N",
    "DAC": "JOHN",
    "DDF": "N",
    "DAD": "NONE",
    "DDG": "N",
    "DCA": "E",
    "DCB": "NONE",
    "DCD": "NONE",
    "DBD": "04092023",
    "DBB": "07272003",
    "DBA": "07272031",
    "DBC": "1",
    "DAU": "070 IN",
    "DAG": "123 CHERRY AVENUE",
    "DAI": "PANAMA CITY",
    "DAJ": "FL",
    "DAK": "324040000  ",
    "DCF": "M712304093106",
    "DCG": "USA",
    "DCK": "0100740380994582",
    "DDA": "F",
    "DDB": "03012020",
    "DDJ": "07272024",
    "ZFA": "",
    "ZFB": "",
    "ZFC": "",
    "ZFD": "",
    "ZFE": "",
    "ZFF": "",
    "ZFG": "",
    "ZFH": "",
    "ZFI": "",
    "ZFJ": "0445764164",
    "ZFK": ""
  }
}

Export a generated PDF417 barcode.

HTTP Request

GET /api/v2/export

Parameters

Parameter	Required	Description
barcode_id	true	Barcode ID (36 characters)

Export Parameters

You should not modify these, however they are given as an option if required. The default values vary for each barcode revision.

Parameter	Required	Description
ecl	false	Error correction level (0-8) Default: automatic
ratio	false	X to Y ratio (2-7) Default: automatic
cols	false	Number of columns of codewords (1-30) Default: automatic
rows	false	Number of rows of codewords (3-90) Default: automatic
bwr	false	Bar width reduction Default: `0`

Response

The response type is determined by the MIME type in the Accept header.

image/png: PNG
image/jpeg: JPEG
image/bmp: BMP
image/svg+xml: SVG
application/json: Processed data
text/plain: Raw barcode data

If an invalid MIME type is provided, the server will return 415 Unsupported Media Type.

Export Linear Barcode

GET /api/v2/linear

curl https://barcodes.fakeidsolutions.com/api/v2/linear \
  -X "GET" -G \
  -H "Authorization: Bearer <token>" \
  -H "Accept: image/png" \
  -d "barcode_id=00000000-0000-4000-0000-000000000000" \

Accept: image/png or Accept: image/jpeg

Binary output

Accept: image/svg+xml or Accept: text/html

XML-based file format

Accept: text/plain

0100740380994582

Accept: application/json

{
  "type": "Code128",           // Code 128 or Code39
  "value": "0100740380994582", // Encoded value
  "height": 120,               // Barcode height
  "width": 3,                  // Bar width
  "display": false             // Display value under barcode
}

Export the accompanying linear (Code 128 or Code39) barcode for a generated barcode.

HTTP Request

GET /api/v2/linear

Parameters

Parameter	Required	Description
barcode_id	true	Barcode ID (36 characters)

Response

The response type is determined by the MIME type in the Accept header.

image/png: PNG
image/jpeg: JPEG
image/svg+xml: SVG
text/html: HTML Document
text/plain: Raw encoded data
application/json: Barcode metadata

If an invalid MIME type is provided, the server will return 415 Unsupported Media Type.

Validate Barcode

GET /api/v2/validate

curl https://barcodes.fakeidsolutions.com/api/v2/validate \
  -X "GET" -G \
  -H "Authorization: Bearer <token>" \
  -d "barcode_id=00000000-0000-4000-0000-000000000000"

Response

{
  "fidscan": {
    "valid": true,
    "confidence": 100,
    "errors": []
  },
  "veriscan": {
    "valid": true,
    "confidence": 100,
    "errors": []
  },
  "checkpoint": {
    "valid": true,
    "confidence": 100,
    "errors": []
  },
  "intellicheck": {
    "valid": true,
    "confidence": 100,
    "errors": []
  }
}

Validate a generated barcode with the leading third-party digital identity validation platforms.

If there is an error communicating with any of the providers, the response for that provider will be null. You may repeat the request to attempt validation again.

You will only be charged on the first request, subsequent requests will not be charged again and will return the previous validation result.

HTTP Request

GET /api/v2/validate

Parameters

Parameter	Required	Description
barcode_id	true	Barcode ID (36 characters)

Response

The validation result will be returned as JSON. Each validator (fidscan, veriscan, checkpoint, and intellicheck) will return the following results:

valid: true / false if the data surpassed the confidence threshold
confidence: confidence that the data is valid from 0 - 100
errors: list of returned errors in the data

Errors

The barcode service uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a parameter is invalid, etc.). Codes in the 5xx range indicate an error with Fake ID Solutions' servers (these are rare).

Some 4xx errors that could be handled programmatically (e.g., insufficient credits, a parameter is invalid, etc.) include an error code that briefly explains the error reported.

Status	Title	Meaning
200	OK	Everything worked as expected.
400	Bad Request	The request was unacceptable, often due to missing a required parameter.
401	Unauthorized	No valid API key provided.
402	Payment Required	You do not have enough credits to perform the request.
403	Forbidden	The API key doesn’t have permissions to perform the request.
404	Not Found	The requested resource doesn’t exist.
409	Conflict	The request conflicts with another request.
429	Too Many Requests	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
5xx	Server Error	Something went wrong on our end.