API

Cette page n'est pas disponible en Français, vous trouverez ci-dessous le texte en anglais.

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

More examples

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 code	Status	Possible error messages
200	OK
401	Unauthorized	Missing API key API key is not valid
403	Forbidden	API calls limit reached
413	Payload Too Large	HTTP content length exceeded 10485760 bytes
400	Bad request	Either parameter "text" or "type" is required Preset not found Unknown QR code type ...

Commands

/create - Create new QR code
/summary - Summary of API key usage, library and temporary files
/uploadfile - Upload one or multiple files to temporary file area (POST)
/uploadfile/{filename} - Upload a file to temporary file area (PUT)
/download - Advanced download of the previously generated QR codes

/create

Supported methods: GET, POST.

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

Response header	Description
content-type	Depending 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-id	The 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:

Parameter	Description
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: Static QR code. Contact details in MeCard format Static QR code. Calendar event Dynamic QR code. Short URL Dynamic QR code. Contact card Dynamic QR code. Page with files
format	Format 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.
preset	You 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
template	You 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.
saveas	Name 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.
shorturl	For 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

Parameter	Description
type	To 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.email	Email
v.url	Website
v.note	Supplemental 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

Parameter	Description
type	To generate this type of code set the parameter type to static.vevent
v.summary	Event summary. Required
v.location	Event 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.dtend	End 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

Parameter	Description
type	To generate this type of code set the parameter type to url
v.url	URL where user should be redirected when they scan the QR code

Dynamic QR code. Contact card

Parameter	Description
type	To generate this type of code set the parameter type to contact
v.firstname	Prénom
v.lastname	Nom de famille
v.org	Organisation
v.title	Titre d'emploi
v.phone1	Téléphone mobile
v.phone2	Téléphone de travail
v.phone3	Autre télephone
v.email	E-mail
v.url	Site Internet
v.instagram	Instagram
v.snapchat	Snapchat
v.twitter	Twitter
v.facebook	Facebook
v.tiktok	Tiktok
v.whatsapp	WhatsApp
v.notes	Remarques
v.logo	Path to the temporary file with a photo or logo

Dynamic QR code. Page with files

Parameter	Description
type	To generate this type of code set the parameter type to page
v.heading	Page title
v.description	Description. 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.displaytype	Display type: list or thumb. Default is list
v.logo	Path to the temporary file with a logo
v.files	Path 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.

Parameter	Description
files	Destination 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.

Parameter	Description
codes	Code 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.
format	Format 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.