API

Use the ScanMeFindMe API to automate QR code generation or create QR codes in bulk.

Before you start using the API:

  • Register for ScanMeFindMe PRO (the API is also available in the free 14-days trial version)
  • Generate at least one API key in your PRO panel
  • Create your own preset (optional)

API endpoint

Base URL: https://api.scanmefindme.com/v1

Authentication

Use header Authentication: Bearer MYAPIKEY or X-Api-Key: MYAPIKEY. Alternatively you can add the apikey parameter to the query string.

Quick example

https://api.scanmefindme.com/v1/create?apikey=MYAPIKEY&text=MYTEXT

Response codes and billing

Depending on your membership tier you have different limits of API requests. The requests counter is reset on each yearly renewal. Only successful requests are counted towards the limit.

Possible response codes:

Response codeStatusPossible error messages
200OK
401Unauthorized
Missing API key
API key is not valid
403Forbidden
API calls limit reached
413Payload Too Large
HTTP content length exceeded 10485760 bytes
400Bad request
Either parameter "text" or "type" is required
Preset not found
Unknown QR code type
...

Commands

/create

Supported methods: GET, POST.

Creates static or dynamic QR codes, returns the generated QR code. The response headers also contain:

Response headerDescription
content-typeDepending on the format parameter, will be one of: image/png, image/svg+xml, application/pdf or application/postscript
x-code-text The text encoded in the generated QR code. If the text parameter was passed it will return the same value.
For dynamic codes this will be the short URL (either passed via the shorturl parameter or automatically generated).
x-code-idThe unique id of the QR code if the code was saved. This id can be used in the /download command.
Note that static codes are only saved if the saveas parameter was specified. Dynamic codes are always saved.

Command /create accepts the following parameters:

ParameterDescription
text For static QR codes: the text that you want to encode, this can be either URL (starting with http:// or https://) or anything else recognised by smartphones. What information can be stored in QR codes?
type
v.param1
v.param2
...
For dynamic QR codes and some static QR codes: specify the type of the QR code you want to generate and the parameters specific for this particular type. To be used instead of the text parameter. See below details for:
formatFormat of the output file - png, pdf, ps, svg or none. Default is png

Value none can be used for dynamic codes or static codes that have the saveas parameter if you do not need the generated QR code image and are only interested in the x-code-id response header.
presetYou can specify a name of a preset that you have already created in your account or a shared preset, more about presets
You can check the list of available presets and their defaults using the /summary command
templateYou can specify the name of a template that you have already created in your account or a shared template, more about templates . If you specify both a preset and a template, the template used in the preset will be ignored.
When neither template nor preset is specified, the QR code will be generated without any margins. Remember that QR codes will not scan if they do not have a "quiet zone" around them.
If you want to add margins to the output specify:
template=shared/withmargin
t.caption
t.caption2
...
Captions to be displayed next to the QR code. The parameter names must correspond to the caption element names in the currently used template.
You can check the list of available captions for each template using the /summary command
t.caption-fontsize
...
Font size for the corresponding caption, in % from the default (100).
width
height
size
Specify either width or height of the output (parameter size is treated as a minimum of width or height). The aspect ratio of the QR code or template cannot be changed, only one of these dimension parameters is needed.
The dimension can be specified in pixels (px), millimeters (mm), centimeters (cm), or inches (in). When the dimension is only a number, pixels are assumed.
When neither is specified the default will be size=640px.
This parameter only affects the download size and is not needed if the output format is set to none.
dpi"Dots per inch" (or "pixels per inch") ratio. This is necessary for generating PDF and PostScript files and can also be used for PNG/SVG images to convert dimensions to pixels.
The default is 150 pixels per inch which is an equivalent to about 59 pixels per centimeter. This is considered a low resolution.
Medium-resolution images have between 200-300 dpi. The industry standard for quality images is typically 300 dpi.
Most businesses consider 600 dpi and higher to be a high-resolution image or print.
This parameter only affects the download size and is not needed if the output format is set to none.
saveasName under which you want to save this code in your account.
For static codes, if not specified, the code will not be saved at all.
For dynamic codes, if not specified, the name will be generated automatically - dynamic codes are always saved.

The id for generated QR code can be found in the response header x-code-id.
shorturlFor dynamic codes only.
The short URL you would like to assign to the generated page. It must have one of the supported domains (qrs.re, qrz.re or your custom domain) and the path must be at least 6 characters long.
If the specified short url is not available, the request will return a 400 response code, the QR code will not be generated and this API request will not be counted towards the limit.
If not specified, the short URL will be randomly generated and can be found in the x-code-text response header.

Example:
https://api.scanmefindme.com/v1/create?apikey=MYAPIKEY&text=tel:1234567890123&template=shared/withcaption&t.caption=CALL+US&format=pdf&width=5cm&dpi=300
will generate a QR code to call the phone number 1234567890123 with a caption "CALL US" in PDF format

Static QR code. Contact details in MeCard format

ParameterDescription
typeTo generate this type of code set the parameter type to static.mecard
v.firstname
v.lastname
First and last name of the person.
v.n Instead of passing first and last name separately, you can optionally pass one parameter v.n. When a field is divided by a comma (,), the first half is treated as the last name and the second half is treated as the first name.
v.tel
v.tel1
v.tel2
...
The canonical number string for a telephone number for telephone communication.
v.emailEmail
v.urlWebsite
v.noteSupplemental information to be set as a memo in the phonebook.
v.adr The physical delivery address. According to the MeCard specification, this has to be: the fields divided by commas (,) denote PO box, room number, house number, city, prefecture, zip code and country, in order.
However many phones don't split address in multiple fields and save it as is
... MeCard format allows more fields such as NICKNAME, BDAY, TEL-AV and SOUND. The ScanMeFindMe QR generator supports them too, however not all phones recognise them.

Static QR code. Calendar event

ParameterDescription
typeTo generate this type of code set the parameter type to static.vevent
v.summaryEvent summary. Required
v.locationEvent location
v.dtstart Start date of the event, required. The format has to follow the iCalendar specification. It has to consist of year, month, day, letter T for time, hour (24h format), minute, second, strictly in this order; every number has to be exactly 2 digits except for the year that has to be exactly 4 digits. The time component is optional.
Here are some examples:
20210131 - 31st of January 2021,
20210131T153000 - 31st of January 2021 3:30pm (15:30) in the local timezone,
20210131T090500Z - 31st of January 2021 9:05am in UTC
v.dtendEnd date of the event, follows the same format as v.dtstart
v.duration Duration of the event, see specification. Examples:
P3D - three days,
PT1H - one hour
PT1H30M - one hour 30 minutes.
Parameter v.duration cannot be specified at the same time as v.dtend. If neither is specified, the event duration is assumed to be one day.

Dynamic QR code. Short URL

ParameterDescription
typeTo generate this type of code set the parameter type to url
v.urlURL where user should be redirected when they scan the QR code

Dynamic QR code. Contact card

ParameterDescription
typeTo generate this type of code set the parameter type to contact
v.firstnamePrénom
v.lastnameNom de famille
v.orgOrganisation
v.titleTitre d'emploi
v.phone1Téléphone mobile
v.phone2Téléphone de travail
v.phone3Autre télephone
v.emailE-mail
v.urlSite Internet
v.instagramInstagram
v.snapchatSnapchat
v.twitterTwitter
v.facebookFacebook
v.tiktokTiktok
v.whatsappWhatsApp
v.notesRemarques
v.logoPath to the temporary file with a photo or logo

Dynamic QR code. Page with files

ParameterDescription
typeTo generate this type of code set the parameter type to page
v.headingPage title
v.descriptionDescription. HTML markup is allowed, it must be clean HTML with all tags closed, ready to be inserted inside the <div> element, for example:
<p class="text-justify">Welcome to our hotel. Enjoy your stay</p>
v.displaytypeDisplay type: list or thumb. Default is list
v.logoPath to the temporary file with a logo
v.filesPath to the temporary files that will be used on the page. More than one file can be submitted, for example v.files=sample.png&v.files=mypath/file.txt; in case of JSON request the v.files parameter value can be an array

The file name (without extension) will become the description of the file. If you want to change this description, add it after the file name and a semicolon, for example: v.files=file.pdf;Description of the file

/summary

Summary of API key usage, library and temporary files. A valid API key is required, however requests to /summary are not counted towards the API requests limit.

Supported methods: GET, POST. This command does not take any parameters.

Example:
https://api.scanmefindme.com/v1/summary?apikey=MYAPIKEY
will return a JSON-encoded array with keys apirequests, tempfiles, library.

Requests can be performed even when API requests limit is reached but in this case it will only return the apirequests section.

/uploadfile

Upload file or multiple files to temporary files. A valid API key is required, however requests to /uploadfile are not counted towards the API requests limit.

Supported method: POST.

ParameterDescription
filesDestination file name once saved to the temporary files area. Has to be a valid file name (for example, not using special characters like '*', ';', etc). File names may contain paths.
More than one files parameter can be submitted, for example files=sample.png&files=mypath/file.txt; in case of JSON request the files parameter value can be an array

The command returns a JSON-encoded array of pre-signed URLs for upload. The URLs are returned in the same order as the files parameters.
The actual files can be uploaded to these URLs using PUT method without any authentication or any other additional headers. The pre-signed URLs will expire in 24 hours.

/uploadfile/{filename}

Upload a single small file to the temporary files area in one step. A valid API key is required, however requests to /uploadfile are not counted towards the API requests limit.

Supported method: PUT.

Request size to the API endpoint is limited to 10Mb, it is difficult to say what will be the exact maximum size of the uploaded file (because of how file is encoded and request is formed) but it is probably around 5Mb. Use the one-step upload endpoint only for small files.

/download

Advanced download of one or multiple QR codes that were previously generated. A valid API key is required, however requests to /download are not counted towards the API requests limit.

Supported methods: GET, POST.

ParameterDescription
codesCode ids of the already generated QR codes that you want to download. They can be either obtained from the x-code-id response headers of the /create command or from the web interface.
More than one codes parameter can be submitted, for example codes=D-222222-33333-yyyyy&codes=S-000000-11111-zzzzz; in case of JSON request the codes parameter value can be an array.
formatFormat of the output file - png, pdf, ps, or svg. Default is png

Note that only PDF (pdf) and PostScript (ps) file formats can contain more than one page.
If more than one page is generated and the specified format was png or svg then a zip archive will be returned.
width
height
size
Specify either width or height of each code (parameter size is treated as a minimum of width or height).
The dimension can be specified in pixels (px), millimeters (mm), centimeters (cm), or inches (in). When the dimension is only a number, pixels are assumed.
When neither is specified the default will be size=640px.
dpi"Dots per inch" (or "pixels per inch") ratio. This is necessary for generating PDF and PostScript files and can also be used for PNG/SVG images to convert dimensions to pixels.
The default is 150 pixels per inch which is an equivalent to about 59 pixels per centimeter. This is considered a low resolution.
Medium-resolution images have between 200-300 dpi. The industry standard for quality images is typically 300 dpi.
Most businesses consider 600 dpi and higher to be a high-resolution image or print.
bgcolor Page background color, by default transparent.
The value can be in one of the following formats: RGB hex (#00ff00); RGBA hex (#ff000080); RGB (rgb(214, 122, 127)); RGBA (rgba(34, 12, 64, 0.6)); color keyword (white).

This parameter defines the background of the page. If the QR codes already have non-transparent background, the page background will not be visible.
paperwidth
paperheight
Width and height of the page.
Each dimension can be specified in pixels (px), millimeters (mm), centimeters (cm), or inches (in). When the dimension is only a number, pixels are assumed.
For example, for A4 specify paperwidth=210mm&paperheight=297mm, for Letter paperwidth=8.5in&paperheight=11in.

When not specified, each QR code will be printed once per page and the page will have exactly the same size as the code. All other parameters below will be ignored.
marginleft
margintop
marginright
marginbottom
Respective page margins.
Each dimension can be specified in pixels (px), millimeters (mm), centimeters (cm), or inches (in). When the dimension is only a number, pixels are assumed.

These parameters are ignored if paperwidth and paperheight are not set.
repeat How many times to repeat each QR code. Default is 1.
If set to -1 the code will be repeated as many times as possible to fill the whole page.

This parameter is ignored if paperwidth and paperheight are not set.
spacingx
spacingy
Horizontal and vertical spacing between QR codes on the same page.
Each dimension can be specified in pixels (px), millimeters (mm), centimeters (cm), or inches (in). When the dimension is only a number, pixels are assumed.

These parameters are ignored if paperwidth and paperheight are not set. They also do not have any effect if there is only one code without repeats or one code on each page.
showcutlines Display crop lines on the margins, by default do not display. Set to 1 to enable.

This parameter is ignored if paperwidth and paperheight are not set. Also crop lines will not be visible without margins.