Login token & user / card API

This section explains how to login & manage user through Airfob Portal APIs.

Before start

Airfob portal account and portal site need to be created in advance to use Airfob portal API. For more information on how to sign up and create a portal site, please refer to the below links.
-	https://mocasystemen.crunch.help/admin/create-account
-	https://mocasystemen.crunch.help/admin/create-site

Portal sign-in

Your system needs to get 'token value' after login, and use it as bearer in the Authroization header with your following API requests.
Each token has one hour timelimit for its validiay. Once it expires, it needs to get a new token and change the bearer token to the new one for further API requests.

API base URL

api.mc.mocainc.com

Login / token request

URL: /login
Method: POST
Request

Key	Required	Type	Description
email	true	STRING	Portal email account ID
password	true	STRING	Password

Response

Key	Required	Type	Description
email	true	STRING	Portal email account ID
accountType	true	STRING	Account type
accessToken	true	STRING	Token data (one hour valid)
name	true	STRING	Account nickname
accountStatus	true	STRING	Account status

Example

POST - /login
Request:
{"email": "api@mocainc.com", "password": "moca1!system"}

Response:
{"status":200,"message":"success",
 "record":{
     "email":"api.mocainc.com",
     "accountType":"sitemanager",
     "accessToken":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhYyI6InNpdGVtYW5hZ2VyIiwiZW0iOiJjaGFybGVzQHN1cHJlbWEuY28ua3IiLCJleHAiOjE1Njk4MDYxNTYsImlhdCI6MTU2OTgwMjU1Nn0.1QR22Y41kEoHwwWbkrq5BJwcfg4OyWszkSgLIUT18Zw",
     "name":"TestUser",
     "accountStatus":"ACTIVATED"
     }
}

User & card creation

	User & card creation can be done together.
	Card type is automatically assigned acccording to the site card type.
	If the site is set to use 'Regular', the regular card will be issued.
	If the site is set to use 'Dynamic', the dynamic card will be issued, and the same is for 'Airfob Service'.

URL: /user/card
Method: POST
Request

Key	Required	Type	Description
siteid	true	STRING	Site unique ID
user.userKey	true	STRING	User ID
user.email	true	STRING	Email address (*Not required when using phone number)
user.phone	true	STRING	Phone number (e.g. +821022223333(Country code+phone number) / *Not required when using email)
user.meta		STRING	JSON String. Profile data. (field key: field value)
user.portraitData		STRING	Image Binary Data(JPG, JPEG, PNG) Base64Encoded
user.feedType		STRING	Feed type (EMAIL or PHONE(Text message))
card.number	true	STRING	Mobile card ID (numeric for GENERAL alphanumeric for ASCII)
card.StartDate	true	LONG	Start-time stamp (UTC)(*Not required when using REGULAR card type)
card.endDate	true	LONG	End-time stamp (UTC)(*Not required when using REGULAR card type)

Response

Key	Required	Type	Description
userid	true	STRING	User unique ID
userKey	true	STRING	User ID
email	true	STRING	EMAIL Address
phone	true	STRING	Phone number
meta	true	STRING	JSON String. Profile data. (field key: field value)
feedType	true	STRING	Feed type (EMAIL or PHONE(Text message))
portrait		STRING	User profile image link
card.id	true	STRING	Card unique ID
card.number	true	STRING	Card ID
card.status	true	STRING	Card status: INACTIVE, ACTIVATED, PAUSED, EXPIRED
card.cardType	true	STRING	REGULAR or DYNAMIC
card.format	true	STRING	Card format
card.cardTypeDesc	true	STRING	Card format Description
card.StartDate		LONG	Card start-time stamp (UTC)
card.endDate		LONG	Card end-time stamp (UTC)

Example

POST - /user/card
Request:
{"siteId": "0",
"user": {
"userKey": "1",
"email": "moca@mocainc.com",
"phone":"+821022223333",
"meta":"{\"name\":\"모카\",\"department\":\"모바일\",\"title\":\"팀원\"}",
"portraitData":"BASE64ENCODED-BINARY",
"feedType": "EMAIL"
},
"card": {
"number":"8352800",
"startDate":1587778190617,
"endDate":1587778250617
}
}
Response:
{"status":200,"message":"success",
"record": {
"userId":"3",
"userKey":"1",
"email":"moca@mocainc.com",
"phone":"+821022223333",
"meta":"{\"name\":\"모카\",\"department\":\"모바일\",\"title\":\"팀원\"}",
"portrait":"https://IMG-URL",
"feedType":"EMAIL",
"card":{
"id":"43548",
"number":"8352800",
"status":"INACTIVE",
"cardType":"DYNAMIC",
"format":"GENERAL",
"cardTypeDesc":"GENERAL",
"startDate":1587778190617,
"endDate":1587778250617}
}
}
}

User & card search

URL: /users/search
Method: POST
Request

Key	Required	Type	Description
siteid	true	STRING	Site unique ID
q		STRING	Search keyword (default: all data)
page		INT	Page to bring (default: 0)
size		INT	No of data to bring (default: 15)
order		STRING	asc. desc (default: asc)

Response

Key	Required	Type	Description
userid	true	STRING	User unique ID
userKey	true	STRING	User ID
email	true	STRING	EMAIL address
phone	true	STRING	Phone number
meta	true	STRING	JSON String. Profile data. (field key: field value)
feedType	true	STRING	Feed type (EMAIL or PHONE(Text message))
portrait		STRING	User profile image link
card.id	true	STRING	Card unique ID
card.number	true	STRING	Card ID
card.status	true	STRING	Card status: INACTIVE, ACTIVATED, PAUSED, EXPIRED
card.cardType	true	STRING	REGULAR or DYNAMIC
card.format	true	STRING	Card format
card.cardTypeDesc	true	STRING	Card format Description
card.StartDate		LONG	Card start-time stamp (UTC)
card.endDate		LONG	Card end-time stamp (UTC)

Example

POST - /users/search
Request:
{"siteId": "0"}
Response:
{"status":200,"message":"success","total":"1",
 "records":[
     {"userId":"3",
      "userKey":"1",
      "email":"moca@mocainc.com",
      "phone":"+821022223333",
      "meta":"{\"name\":\"모카\",\"department\":\"모바일\",\"title\":\"팀원\"}",
      "portrait":"https://IMG-URL",
      "feedType":"EMAIL",
      "card":{
          "id":"43548",
          "number":"8352800",
          "status":"INACTIVE",
          "cardType":"DYNAMIC",
          "format":"GENERAL",
          "cardTypeDesc":"GENERAL",
          "startDate":1587778190617,
          "endDate":1587778250617}
          }
      ]
}

User delete

URL: /users/delete
Method: POST
Request
- List

Key	Required	Type	Description
userid	true	STRING	User unique index ID

Response

Key	Required	Type	Description
status	true	INT	Each user delete STATUS
message	true	STRING	Each user delete Message

Example

POST - /users/delete
Request:
[{"userId": "303"},
 {"userId": "304"}
]
Response:
{"status":207,"message":"Multi-Status",
 "total":"2","success":"2","failure":"0",
 "records":[
     {"status":200,"message":"success"},
     {"status":200,"message":"success"}
     ]
}

Card delete

In order to delete the card, the status value needs to be 'FORCE_DELETE.'

URL: /cards
Method: PUT
Request
- List

Key	Required	Type	Description
cardid	true	STRING	Card unique index ID
status	true	STRING	FORCE_DELETE

Response

Key	Required	Type	Description
status	true	INT	Each card delete STATUS
message	true	STRING	Each card delete MESSAGE
record_status	true	STRING	Changed status value after delete

Example

PUT - /cards
Request:
[{"cardId": "202"
  "status": "FORCE_DELETE"},
 {"cardId": "203",
  "status": "FORCE_DELETE"}
]
Response:
{"status":207,"message":"Multi-Status",
 "total":"2","success":"2","failure":"0",
 "records":[
     {"status":200,"message":"success",
      "record": {"status": "DELETE"}},
     {"status":200,"message":"success",
      "record": {"status": "DELETE"}}
     ]
}

Card resend

Resend is for sending the download link again.
Therefore, it cannot be processed when the card is already activated.

URL: /card/send
Method: POST
Request

Key	Required	Type	Description
siteid	true	STRING	Site ID
number	false	STRING	Mobile Card ID(*Required when the below cardid is not included)
cardid	false	STRING	Card unique ID(*Required when the above number is not included)

Response
- None

Example

POST - /card/send
Request:
{"siteId": "0", "number": "43548"}

Response:
{"status":200,"message":"success"}

Card reissue

Reissue is for the same mobile card data resend.
Therefore, it cannot modify user & card data.

URL: /user/card
Method: PUT
Request

Key	Required	Type	Description
siteid	true	STRING	Site unique ID
userid	true	STRING	User unique ID
user.userKey		STRING	User ID
user.email		STRING	EMAIL Address
user.phone		STRING	Phone number
user.meta		STRING	JSON String. Profile data (field key: field value).
user.portraiteData		STRING	Feed type (EMAIL or PHONE(Text message))
user.feedType		STRING	Email or Phone
card.StartDate		LONG	Card start time stamp (UTC)
card.endDate		LONG	Card end time stamp (UTC)

Response

Key	Required	Type	Description
siteid	true	STRING	Site unique ID
userid	true	STRING	User unique ID
userKey	true	STRING	User ID
email	true	STRING	EMAIL address
phone	true	STRING	Phone number
meta	true	STRING	JSON String. Profile data (field key: field value).
feedType	true	STRING	Feed type (EMAIL or PHONE(Text message))
portrait		STRING	User profile image link
card.id	true	STRING	Card unique ID
card.number	true	STRING	Card ID
card.status	true	STRING	Card status: INACTIVE, ACTIVATED, PAUSED, EXPIRED
card.cardType	true	STRING	REGULAR or DYNAMIC
card.format	true	STRING	Card format
card.cardTypeDesc	true	STRING	Card format Description
card.StartDate		LONG	Card start time stamp (UTC)
card.endDate		LONG	Card end time stamp (UTC)

Example

PUT - /user/card
Request:
{"siteId": "0",
 "userId" : "3",
 "card": {
      "startDate":1587778190617,
      "endDate":1587778250617}
      }
}
Response:
{"status":200,"message":"success",
 "record": {
      "userId":"3",
      "userKey":"1",
      "email":"moca@mocainc.com",
      "phone":"+821022223333",
      "meta":"{\"name\":\"모카\",\"department\":\"모바일\",\"title\":\"팀원\"}",
      "portrait":"https://IMG-URL",
      "feedType":"EMAIL",
      "card":{
          "id":"43548",
          "number":"8352800",
          "status":"INACTIVE",
          "cardType":"DYNAMIC",
          "format":"GENERAL",
          "cardTypeDesc":"GENERAL",
          "startDate":1587778190617,
          "endDate":1587778250617}
          }
      }
}

Related Articles
[User Template] Create User registration template
Airfob Portal provides a default user template with the information needed to issue a mobile access card. However, depending on your site, you can create your own custom template if it has required input fields. Basic required items cannot be ...
Upload user images
Apply images to more than two users in drag and drop. Uploading multiple user images is an easy way to add user information to the card and user information at once when registering employees, visitors, members, etc. on the site. If not uploaded ...
[Card Template] Design mobile access card
Mobile access cards can be aesthetically pleasing and provide tailored information to represent your organization. Designing a mobile access card is the process of editing the user information, user image, and background image of the card in order to ...
Issue mobile access card
Mobile access cards can be issued to users on Airfob Portal. Issuing a mobile access card is the process of issuing a mobile access card to registered employees, visitors, and members. Users can download only one mobile access card per site onto the ...
Airfob Patch troubleshooting card format
Mobile card does not work on Airfob Patch. I've issued mobile card and the user downloaded the card on his phone but he failed to authenticate successfully when tapping on the card reader. Scenario. It is configured in custom card format Check the ...

Login token & user / card API

Login token & user / card API

Before start

Portal sign-in

API base URL

Login / token request

User & card creation

User & card search

User delete

Card delete

Card resend

Card reissue

Related Articles

[User Template] Create User registration template

Upload user images

[Card Template] Design mobile access card

Issue mobile access card

Airfob Patch troubleshooting card format