Introduction to API

Contact the Support Team to create an API Account and become our partner.

Authorisation

At this stage, we assume that you are a partner of Bonder and our Support Team has provided you with the Username, Password and API client name.
  • Command auth
  • Request POST
curl -k -X POST \
-H "Content-Type : application/json" \
-H "Accept : application/json" \
-d '{
  "username" : "USERNAME",
  "password" : "PASSWORD",
  "client" : "API_CLIENT_NAME",
  "rpt" : "10000"
}' \
"https:// {{API_URL}} /auth" \
Authorisation parameters
Parameter
Type
Description
username
string
API username
password
string
API password
client
string
API client name
rpt
integer
number of requests per token (RPT - Requests Per Token) rpt<1000, 100000>
Success HTTP/1.1 200 OK
{
  "success" : true,
  "errors" : [],
  "result" : {
    "token" : "access_token",
    "expire" : "1594924447"
  }
}
Response
Parameter
Type
Description
token
string
your token
expire
integer
timestamp of token expiry date expire=time()+3600
The expire and rpt variables are racing. The one which reaches the target value first will deactivate the token.
Failure HTTP/1.1 200 OK
{
  "success" : false,
  "errors" : [error-code],
  "result" : {}
}
error-code
Error
Description
INVALID_CREDENTIALS_ERROR
Invalid Password, invalid e-mail or Account was deleted or does not exist
SERVER_OFFLINE_ERROR
Server is offline due to ongoing maintenance works.
Possible software update
  • Suggestions: try again in 45-60 min
AUTH_SERVICE_OFFLINE_ERROR
The authentication service is temporarily unavailable for all Users.
Possible software update
  • Suggestions: try again in 45-60 min
API_SERVICE_OFFLINE_ERROR
The API service is temporarily unavailable.
Possible software update
  • Suggestions: try again in 45-60 min
ACCOUNT_INACTIVE_ERROR
The API Account is suspended or intended for deletion
  • Suggestions: contact the Support Team
INTERNAL_SERVER_ERROR
Internal server error
  • Suggestions: try again
DATABASE_ERROR
Database connection error
  • Suggestions: try again

Data structure

Before we move to other commands, we will explain to you the data structure used by Bonder.

Data types

data types
Type
Description
translatable
should be saved separately in each language
non-translatable
are stored in a separate table and are added to the Business Card in each language
For example: If you change a non-translatable value such as email or mobile, all language versions of the Business Card will be updated.

Business Card modes

Due to the fact that your client may not be a natural person but an enterprise, e.g. Totally-not-scary-dental-services, we created the top level variable - displayName. If !empty(displayName), the Business Card will operate in the business mode and the name lastname position variables will be omitted when generating the Business Card (however, the server will still keep the values).
Business Card modes
Mode
Condition
business
if (!empty(displayName)) {
 businessMode = TRUE
}
personal
if (empty(displayName)) {
 businessMode = FALSE
}
In the English version, the displayName variable has a value assigned so the server will keep the data, however, name lastname position will be ignored when generating the Business Card. "en" : {
  "displayName" : "Non-scary-dental-services",
  "name" : "John",
  "lastname" : Kowalski",
  "position" : "CEO"
},
In the Polish version, the name Jan Kowalski (on the position of the President) will be displayed. "pl" : {
  "displayName" : "",
  "name" : "Jan",
  "lastname" : "Kowalski",
  "position" : "Prezes"
},
The Russian version will not be available for download, despite storing a part of the data on the server. "ru" : {
  "displayName" : "",
  "name" : "",
  "lastname" : "Ковалский",
  "position" : "Директор"
}

Variables

Each variable need to be preliminary validated before sending it to the server. If the value of the sent variable is not in line with the regular expression assigned to it, the server will assign it with null and, despite that, will send the success=true positive response about saving data.
Variables
Name
Type
Translatable
Description
name
string
name
  • required to generate the Business Card in the personal mode
  • saved and ignored in the business mode
  • /^[a-zA-Z0-9]{2,25}$/
lastname
string
surname
  • required to generate the Business Card in the personal mode
  • saved and ignored in the business mode
  • /^[a-zA-Z0-9]{32,128}$/
displayName
string
display name
  • required to generate the Business Card in the business mode
  • /^[a-zA-Z0-9]{32,128}$/
company
string
company name
  • /^[a-zA-Z0-9]{32,128}$/
position
string
position
  • saved and ignored in the business mode
  • /^[a-zA-Z0-9]{32,128}$/
keywords
string
keywords which best describe a given person or company
  • comma as a separator
  • /^[a-zA-Z0-9]{1,150}$/
thumbnail
string
user's photo or logo displayed on a mobile device
  • image encoded in base64
  • fixed size 300px x 300px
  • maximum file size 50KB
phoneA
string
phone number
  • leading zeros and non-numeric characters will be cut
  • a client should provide their country code
  • we will add "+" at the beginning
  • /^[a-zA-Z0-9]{32,128}$/
phoneB
string
as above
mobileA
string
mobile phone number
  • leading zeros and non-numeric characters will be cut
  • a client should provide their country code
  • we will add "+" at the beginning
  • /^[a-zA-Z0-9]{32,128}$/
mobileB
string
as above
skypeA
string
Skype username
  • /^[a-zA-Z0-9]{32,128}$/
skypeB
string
as above
faxA
string
fax number
  • leading zeros and non-numeric characters will be cut
  • a client should provide their country code
  • we will add "+" at the beginning
  • /^[a-zA-Z0-9]{32,128}$/
faxB
string
as above
emailA
string
e-mail
emailB
string
as above
webA
string
URL
  • /^[a-zA-Z0-9]{32,128}$/
webB
string
as above
webC
string
as above
addrStreet
string
address - street
  • /^[a-zA-Z0-9]{32,128}$/
addrCity
string
address - city
  • /^[a-zA-Z0-9]{32,128}$/
addrState
string
address – state / province
  • /^[a-zA-Z0-9]{32,128}$/
addrZip
string
address - postal code
  • /^[a-zA-Z0-9]{32,128}$/
addrCountry
string
address - country
  • /^[a-zA-Z0-9]{32,128}$/

Parameters

Parameters
Variable
Type
Description
langStatus
integer
0 = off, 1 = on
Enable / disable language version without deleting data
  • default = 0
usePhoto
integer
0 = off, 1 = on
Enable / disable photo without deleting it
  • default = 1
cardStatus
integer
0 = off, 1 = on
Enable / disable Business Card without deleting it
  • default = 1

Language support

Bonder allows its Users to create Business Cards in more than 60 languages and this key functionality is also available for API Users. For your convenience, we prepared repositories with translated language codes supported by Bonder, which you can use when creating your own application. We use the lang variable to manage language versions. You will use it to add, edit and delete language versions.
  • Command repositories
  • Request GET
curl -k -X GET \
-H "X-Auth-Key : {{access_token}}" \
-H "X-Auth-Email : {{username}}" \
-H "Content-Type : application/json" \
-H "Accept : application/json" \
"https:// {{API_URL}} /repositories \
Success HTTP/1.1 200 OK
{
  "success": true,
  "errors" : [],
  "result" : {
    "langList" : [local, lang]
  }
}
langList
value
Type
Description
lang
string
language code compliant with ISO 639-1:2002
local
string
list of local language names, e.g.: en => English, ru => Русский
Example of response The server returns the list of available resources: local, English, Russian, Polish, Chinese HTTP/1.1 200 OK
{
  "success": true,
  "errors" : [],
  "result" : {
    "langList" : ["local", "en", "ru", "pl", "zh"]
  }
}
Use the values from langList to download resources which you need. The response will always be in the form of the key : value pairs.

Download the list of local language names

  • Command repositories
  • Request GET
curl -k -X GET \
-H "X-Auth-Key : {{access_token}}" \
-H "X-Auth-Email : {{username}}" \
-H "Content-Type : application/json" \
-H "Accept : application/json" \
"https:// {{API_URL}} /repositories/local" \
Success HTTP/1.1 200 OK
{
  "success": true,
  "errors" : [],
  "result" : {
    "pl" : "Polski",
    "en" : "English",
    "ru" : "Русский",
    ...,
    "key" : "value"
 }
}

Download translated language names

  • Command repositories
  • Request GET
Change the query above according to the example below: "https:// {{API_URL}} /repositories/ru" \
"https:// {{API_URL}} /repositories/en" \
If we do not have a resource which you look for in our repositories, inform the Support Team about that. We will fill the gaps as soon as possible. If you cannot wait for our response, we suggest downloading available language codes and preparing your own translations.
Failure HTTP/1.1 200OK
{
  "success" : false,
  "errors" : [error-code],
  "result" : {}
}
error-code
Error
Description
INVALID_CREDENTIALS_ERROR
Invalid Password or e-mail or invalid token
  • Suggestions: repeat authentication
RESOURCE_NOT_FOUND_ERROR
The resource you are looking for does not exist
  • Suggestions: check the query
other
see ERROR-CODE in the Authorisation section

Creating a new Profile

  • Command users
  • Request post
curl -k -X POST \
-H "X-Auth-Key : {{access_token}}" \
-H "X-Auth-Email : {{username}}" \
-H "Accept : application/json" \
"https:// {{API_URL}} /users" \
Success HTTP/1.1 200 OK
{
  "success": true,
  "errors" : [],
  "result" : {
    "cardId" : string,
    "cardQrc" : string,
    "cardAddr" : string (url)
  }
}
QUERY RESULTS
Variable
Type
Description
cardId
string
Business Card identifier of a created Profile
  • case-sensitive
  • /^[a-zA-Z0-9]{32,128}$/
cardAddr
string
address of a created Business Card
cardQrc
string
the QR code of the Business Card's address encoded in base64
The cardId cardQrc cardAddr variables should be stored locally on your server and assigned to a given Profile. The cardId variable is necessary for correct communication with API.
Failure HTTP/1.1 200 OK
{
  "success" : false,
  "errors" : [error-code],
  "result" : {}
}
error-code
Error
Description
INVALID_CREDENTIALS_ERROR
Invalid Password or e-mail or invalid token
  • Suggestions: repeat authentication
PROFILE_LIMIT_REACHED_ERROR
Profile limit reached
  • Suggestions: contact the Support Team to change Account Settings
other
see ERROR-CODE in the Authorisation section

Saving data

  • We do not use fixed inquiries. Send only this data which needs to be updated.
  • Use the PUT command to create a new Profile.
  • Add a language using the lang keys in the translatable section.
  • If a client does not want to specify a language version, set lang=un which means universal.
  • Modify up to five languages within one query (updating, adding). Language versions above 5 will be ignored.
  • Command users
  • Request put
curl -k -X PUT \
-H "X-Auth-Key : {{access_token}}" \
-H "X-Auth-Email : {{username}}" \
-H "Content-Type : application/json" \
-H "Accept : application/json" \
-d ' {
When cardStatus=0, the Business Card will be disabled and it will not be possible to download it.   "settings" : {
    "cardStatus" : "0",
    "usePhoto" : "1"
  },
  "translatable" : {
Use langStatus to enable and disable languages.     "pl" : {
      "name" : "John",
      "lastname" : "Connor",
      "position" : "Dyrektor Zarządzający"
    },
When adding a new language, we set langStatus=0 by default. You can bypass this setting by assigning langStatus=1 when adding a language.     "en" : {
      "name" : "John",
      "lastname" : "Connor",
      "position" : "Managing Director",
      "displayName" : "The Great John Connor",
      "keywords" : "steel, steel pipe, tubular products"
    },
Despite setting langStatus=1, a given language will not be ready for download until the (name!=null && lastname!=null) || displayName!=null condition is met.     "es" : {
      "langStatus" : "1",
      "name" : "John",
      "position" : "Director Ejecutivo"
    },
    "pt" : {
      "langStatus" : "1",
      "name" : "John",
      "lastname" : "Connor",
    },
    "ru" : {
      "langStatus" : "1",
      "name" : "",
      "lastname" : "Коннор",
    },
    "zh" : {
      "position" : "首席执行官"
    }
  },
  "non-translatable" : {
    "thumbnail" : "base64_encoded_image",
    "mobileA" : "123456789",
    "emailB" : "[email protected]"
  }
} ' \
"https:// {{API_URL}} /users/{{card_id}} \
Success HTTP/1.1 200 OK
{
  "success": true,
  "errors" : [error-code],
  "result" : {}
}
Despite returning success=true, the server may report an error if you add a profile photo to your query.
error-code
Error
Description
THUMBNAIL_REJECTED_ERROR
Data has been saved, however, the sent image has been rejected by the server
  • Suggestions: validate your image generator
Failure HTTP/1.1 200 OK
{
  "success" : false,
  "errors" : [error-code],
  "result" : {}
}
error-code
Error
Description
INVALID_CREDENTIALS_ERROR
Invalid Password or e-mail or invalid token
  • Suggestions: repeat authentication
CARD_ID_NOT_FOUND_ERROR
The Business Card cardId does not exist or you do not have authorisations to modify this resource.
  • Suggestions: check the query
other
see ERROR-CODE in the Authorisation section

Modifying settings

Parameters
Parameter
Type
Description
status
string
<enable, disable>

Changing Business Card status

  • Command users
  • Request put
curl -k -X PUT \
-H "X-Auth-Key : {{access_token}}" \
-H "X-Auth-Email : {{username}}" \
-H "Content-Type : application/json" \
-H "Accept : application/json" \
https:// {{API_URL}} /users/{{card_id}}/cardStatus/{{status}}

Changing photo status

  • Command users
  • Request put
curl -k -X PUT \
-H "X-Auth-Key : {{access_token}}" \
-H "X-Auth-Email : {{username}}" \
-H "Content-Type : application/json" \
-H "Accept : application/json" \
https:// {{API_URL}} /users/{{card_id}}/usePhoto/{{status}}

Changing language status

  • Command users
  • Request put
curl -k -X PUT \
-H "X-Auth-Key : {{access_token}}" \
-H "X-Auth-Email : {{username}}" \
-H "Content-Type : application/json" \
-H "Accept : application/json" \
https:// {{API_URL}} /users/{{card_id}}/langStatus/{{lang}}/{{status}}
Success HTTP/1.1 200 OK
{
  "success" : true,
  "errors" : [],
  "result" : {}
}
Failure HTTP/1.1 200 OK
{
  "success" : false,
  "errors" : [error-code],
  "result" : {}
}
error-code
Error
Description
all
see ERROR-CODE in the Saving data section

Downloading data

  • Command users
  • Request get
curl -k -X GET \
-H "X-Auth-Key : {{access_token}}" \
-H "X-Auth-Email : {{username}}" \
-H "Content-Type : application/json" \
-H "Accept : application/json" \
"https:// {{API_URL}} /users/{{card_id}}" \
Success HTTP/1.1 200 OK
{
"success": true,
"errors" : [],
"result" : {
  "translatable" : {
    "lang" : {
      "langStatus" : "1",
      "key" : "value"
    },
    "lang" : {
      "langStatus" : "0",
      "key" : "value"
    }
  },
  "non-translatable" : {
    "thumbnail" : "base64_encoded_image",
    "key" : "value"
  },
  "settings" : {
    "cardStatus" : "1",
    "usePhoto" : "1",
    "cardQrc" : "base64_encoded_image",
    "cardAddr" : "URL",
    "usePhoto" : "1"
  }
}
Failure HTTP/1.1 200 OK
{
  "success" : false,
  "errors" : [error-code],
  "result" : {}
}
error-code
Error
Description
INVALID_CREDENTIALS_ERROR
Invalid Password or e-mail or invalid token
  • Suggestions: repeat authentication
CARD_ID_NOT_FOUND_ERROR
The Business Card cardId does not exist or you do not have authorisations to modify this resource.
  • Suggestions: check the query
other
see ERROR-CODE in the Authorisation section

Deleting data

Deleting language

  • Command users
  • Request delete
curl -k -X DELETE \
-H "X-Auth-Key : {{access_token}}" \
-H "X-Auth-Email : {{username}}" \
-H "Content-Type : application/json" \
-H "Accept : application/json" \
"https:// {{API_URL}} /users/{{card_id}}/{{lang}}" \

Deleting Profile

  • Command users
  • Request delete
curl -k -X DELETE \
-H "X-Auth-Key : {{access_token}}" \
-H "X-Auth-Email : {{username}}" \
-H "Content-Type : application/json" \
-H "Accept : application/json" \
"https:// {{API_URL}} /users/{{card_id}}" \
Success HTTP/1.1 200 OK
{
  "success" : true,
  "errors" : [],
  "result" : {}
}
Failure HTTP/1.1 200 OK
{
 "success" : false,
 "errors" : [error-code],
 "result" : {}
}
error-code
Error
Description
INVALID_CREDENTIALS_ERROR
Invalid Password or e-mail or invalid token
  • Suggestions: repeat authentication
CARD_ID_NOT_FOUND_ERROR
The Business Card cardId does not exist or you do not have authorisations to modify this resource.
  • Suggestions: check the query
other
see ERROR-CODE in the Authorisation section
Previous page