Overview
The Message API is a low-level, REST API for developers to integrate to the PassByME platform. Messaging has three different methods to send messages to smartphone devices that has the PassByME application ready and installed.
- Authorization messages for adding strong two-factor authentication to your website or application.
- General messages to send simple text messages to registered PassByME users.
- eSign messages to sign documents with your mobile device. If you interested in eSign solution, please contact us on email.
First Step
You'll need a PassByME account, and a certificate to access the messaging API from your application. Sign Up using the web-based administration interface, and register a new organization if you haven’t registered before. If you have already registered into the PassByME service, please log in as an administrator with your previously created credential data (username/password and your PassByME ready mobile device).
To access the PassByME service URL you should have a valid authentication certificate and key (PFX file): The PassByME management service URL can be used only with a valid authentication certificate, which you can acquire after the registration process.
Download PFX:
- Log into your administration page.
- Select the "Access Keys" menu.
- Create an application by clicking on the "Add access key" button.
- Choose "Application key" as access key type and choose a name for the new access key".
- Click your newly created application icon.
- Choose "Download PFX" option.
This certificate has a software-based private key inside the downloaded PFX. The PFX file is protected with a passphrase, which can be printed on the administration website. Note that the certificate can be downloaded in PEM format as well.
Important! The authentication certificate identifies the registered APPLICATION in the PassByME service.
This API is available for FREE up to 10 users!
Check out PassByME REST API client libraries and sample source code for Java, C#, Node.js and PHP.
Message Delivery
Sending Message
Sends a message to the smartphones of the given users.
post
/messages
Parameters
json
in request body.| Field | Mandatory | Description |
|---|
| recipients | Required | A JSON Array of PassByME IDs. |
| subject | Required | A string that contains the message subject. Maximum size is 254 characters. |
| body | Required | A string that contains the message body. Maximum size is 16376 characters. |
| preview | Optional | A string that contains the message preview. Maximum size is 300 characters. |
| availability | Required | An integer that denotes the availability of the message in seconds. |
| type | Required | Message type: "authorization", "message", "esign" or "oneTimePassword". |
| callbackUrl | Optional Only available when PassByME is deployed on premise. Contact sales@passbyme.com for on premise offers | A string that contains a callback url used for recipient status reporting. Maximum size is 254 characters. Method: POST Request body: tracking info in JSON format. See Output |
| minimumTrustLevel | Optional | This level defines the trustiness of the certificate required to upload the evidence of the message :"any", "advanced" or "qualified" (optional, default: "any"). |
| organization | Optional Only available when the sender organization has right to do that. | The recipient organization OID where the recipients should be searched for. This organization will be used for push credentials as well (optional, available only if the sender organization has rights to do so) |
| checkSecureId | Optional | A boolean flag to force that the user must validate secureId on the device (optional, default: false). |
| forceReadingDocuments | Optional | A boolean flag to indicate that the user must read all documents in the message before approving (optional, default: false). |
| secureId | Optional | The secureId of the message can be set by the sender (optional, default: server-side generated random value). |
| externalId | Optional | The unique part of the message id can be set by the sender (optional, default: server-side generated random value). |
| documents | Optional | A JSON Array of documents to attach |
| recipientDeviceLabel | Optional | If specified, the message will only be available to devices that have the given label. |
| unlisted | Optional | An unlisted message will not appear in the message lists on mobile, when browsing the active and archive message list. We are sending no push notifications for unlisted messages. |
Request example
/messages
{"recipients":["john.doe@passbyme.com","second.example@passbyme.com"],"subject":"Example message subject","body":"The body of your message.","preview":"The preview of your message.","availability":300,"type":"authorization","callbackUrl":"www.report.sales.passbyme.com","minimumTrustLevel":"any","organization":"1.2.3.4.5.6","checkSecureId":"false","forceReadingDocuments":"false","secureId":"abc123","externalId":"fZFbDOsv","documents":[{"name":"documentName","require":true,"description":"The document name","value":"Example file name"},{"name":"downloadUrl","require":true,"description":"Download URL","value":"https://any.hu/any.doc"},{"name":"downloadUrlExpiry","require":true,"description":"The expiration date of the download URL","value":"2020-04-01T20:00:00Z"}],"recipientDeviceLabel":"test_label","unlisted":"false"}
Success response format
| Field | Type | Description |
|---|
| messageId | String | Identifier of the sent message. |
| expirationDate | String (ISO 8601) | The expiry date of the current message. |
| recipients | Array | A list of recipients and their status information. |
Success response
HTTP/1.0 200 OK
{"messageId":"@pbmcore1-1.3.6.1.4.1.21528.3.3.2.9045.2.10111-fZFbDOsv","expirationDate":"2016-08-16T12:49:03.833Z","recipients":[{"userId":"john.doe@passbyme.com","status":"PENDING"}]}
Tracking Message
Returns the status of a message, identified by the given messageId.
get
/messages/:messageId
Parameters
query string
| Field | Mandatory | Description |
|---|
| messageId | Required | The identifier of the message to be tracked. |
Request example
/messages/@pbmcore1-1.3.6.1.4.1.21528.3.3.2.9045.2.10111-fZFbDOsv
Success response format
| Field | Type | Description |
|---|
| messageId | String | Identifier of the sent message. |
| expirationDate | String (ISO 8601) | The expiry datetime of the current message. |
| recipients | Array | A list of recipients and their status information. |
| secureId | String | The session identifier of the message. This id shows up in the mobile device after receiving an authentication message. |
Success response
HTTP/1.0 200 OK
{"messageId":"@pbmcore1-1.3.6.1.4.1.21528.3.3.2.9045.2.10111-fZFbDOsv","expirationDate":"2016-08-16T12:49:03.833Z","recipients":[{"userId":"john.doe@passbyme.com","status":"PENDING"}],"secureId":"N7voX4"}
Cancelling Message
Cancels a message, identified by the given messageId.
delete
/messages/:messageId
Parameters
query string
| Field | Mandatory | Description |
|---|
| messageId | Required | The identifier of the message. |
Request example
/messages/@pbmcore1-1.3.6.1.4.1.21528.3.3.2.9045.2.10111-fZFbDOsv
Success response format
| Field | Type | Description |
|---|
| messageId | String | Identifier of the sent message. |
| expirationDate | String (ISO 8601) | The expiry datetime of the current message. |
| recipients | Array | A list of recipients and their status information. |
| secureId | String | The session identifier of the message. This id shows up in the mobile device after receiving an authentication message. |
Success response
HTTP/1.0 200 OK
{"messageId":"@pbmcore1-1.3.6.1.4.1.21528.3.3.2.9045.2.10111-fZFbDOsv","expirationDate":"2016-08-16T12:49:03.833Z","recipients":[{"userId":"john.doe@passbyme.com","status":"PENDING"}],"secureId":"N7voX4"}
ConfigurationUpdate Message
Cancels a message, identified by the given messageId.
post
/messages/configurationUpdate
Parameters
json
in request body.| Field | Mandatory | Description |
|---|
| vendorId | Required | Identifier of the selected user's device. |
| subject | Required | A string that contains the message subject. Maximum size is 254 characters. |
| body | Required | Contains a ConfigUpdateBody. |
| preview | Optional | A string that contains the message preview. Maximum size is 300 characters. |
| availability | Required | An integer that denotes the availability of the message in seconds. |
| externalId | Optional | The unique part of the message id can be set by the sender (optional, default: server-side generated random value). |
Request example
/messages/configurationUpdate
{"vendorId":"0ecgjX4cCBkDLe2EokMnlP6jjII=","subject":"Example message subject","body":{"message":"Example message value. Please accept this message. ","configuration":{"scepUrl":"https:www.microsec.hu","expireDate":"2017-09-18T09:33:02+02:00","deviceCertificateConfig":{"USER_SIGN":{"challengePassword":"password"},"DEVICE_SIGN":{"challengePassword":"password"}}}},"preview":"The preview of your message.","availability":300,"externalId":"fZFbDOsv"}
Success response format
| Field | Type | Description |
|---|
| messageId | String | Identifier of the sent message. |
| expirationDate | String (ISO 8601) | The expiry datetime of the current message. |
| recipients | Array | A list of recipients and their status information. |
| secureId | String | The session identifier of the message. This id shows up in the mobile device after receiving an authentication message. |
Success response
HTTP/1.0 200 OK
{"messageId":"@pbmcore1-1.3.6.1.4.1.21528.3.3.2.9045.2.10111-fZFbDOsv","expirationDate":"2016-08-16T12:49:03.833Z","recipients":[{"userId":"0ecgjX4cCBkDLe2EokMnlP6jjII=","status":"PENDING"}],"secureId":"N7voX4"}
Broadcast Message
Sends a message to every user in the current organization.
post
/messages/broadcast
Parameters
json
in request body.| Field | Mandatory | Description |
|---|
| subject | Required | A string that contains the message subject. Maximum size is 254 characters. |
| body | Required | A string that contains the message body. Maximum size is 16376 characters. |
| preview | Optional | A string that contains the message preview. Maximum size is 300 characters. |
| availability | Required | An integer that denotes the availability of the message in seconds. |
| type | Required | Message type: "authorization", "message", "esign" or "oneTimePassword". |
| callbackUrl | Optional Only available when PassByME is deployed on premise. Contact sales@passbyme.com for on premise offers | A string that contains a callback url used for recipient status reporting. Maximum size is 254 characters. Method: POST Request body: tracking info in JSON format. See Output |
| minimumTrustLevel | Optional | This level defines the trustiness of the certificate required to upload the evidence of the message :"any", "advanced" or "qualified" (optional, default: "any"). |
| organization | Optional Only available when the sender organization has right to do that. | The recipient organization OID from which the recipients will be addressed. |
| checkSecureId | Optional | A boolean flag to force that the user must validate secureId on the device (optional, default: false). |
| forceReadingDocuments | Optional | A boolean flag to indicate that the user must read all documents in the message before approving (optional, default: false). |
| secureId | Optional | The secureId of the message can be set by the sender (optional, default: server-side generated random value). |
| externalId | Optional | The unique part of the message id can be set by the sender (optional, default: server-side generated random value). |
| documents | Optional | A JSON Array of documents to attach |
| unlisted | Optional | An unlisted message will not appear in the message lists on mobile, when browsing the active and archive message list. We are sending no push notifications for unlisted messages. |
Request example
/messages/broadcast
{"subject":"Example message subject","body":"The body of your message.","preview":"The preview of your message.","availability":300,"type":"authorization","callbackUrl":"www.report.sales.passbyme.com","minimumTrustLevel":"any","organization":"1.2.3.4.5.6","checkSecureId":"false","forceReadingDocuments":"false","secureId":"abc123","externalId":"fZFbDOsv","documents":[{"name":"documentName","require":true,"description":"The document name","value":"Example file name"},{"name":"downloadUrl","require":true,"description":"Download URL","value":"https://any.hu/any.doc"},{"name":"downloadUrlExpiry","require":true,"description":"The expiration date of download URL","value":"2020-04-01T20:00:00Z"}],"unlisted":"false"}
Success response format
| Field | Type | Description |
|---|
| messageId | String | Identifier of the sent message. |
| expirationDate | String (ISO 8601) | The expiry datetime of the current message. |
| recipients | Array | A list of recipients and their status information. |
Success response
HTTP/1.0 200 OK
{"messageId":"@pbmcore1-1.3.6.1.4.1.21528.3.3.2.9045.2.10111-fZFbDOsv","expirationDate":"2016-08-16T12:49:03.833Z","recipients":[{"userId":"john.doe@passbyme.com","status":"PENDING"}]}
Renotify recipients
Returns the status of the message after renotification, identified by the given messageId.
post
/messages/:messageId/renotify
Parameters
query string
| Field | Mandatory | Description |
|---|
| messageId | Required | The identifier of the message for which the renotifications will be send |
Request example
/messages/@pbmcore1-1.3.6.1.4.1.21528.3.3.2.9045.2.10111-fZFbDOsv/renotify
Success response format
| Field | Type | Description |
|---|
| messageId | String | Identifier of the sent message. |
| expirationDate | String (ISO 8601) | The expiry datetime of the current message. |
| recipients | Array | A list of recipients and their status information. |
| secureId | String | The session identifier of the message. This id shows up in the mobile device after receiving an authentication message. |
Success response
HTTP/1.0 200 OK
{"messageId":"@pbmcore1-1.3.6.1.4.1.21528.3.3.2.9045.2.10111-fZFbDOsv","expirationDate":"2016-08-16T12:49:03.833Z","recipients":[{"userId":"john.doe@passbyme.com","status":"PENDING"}],"secureId":"N7voX4"}
Identification
Start identification
Start an identification process.
post
/identification
Parameters
json
in request body.| Field | Mandatory | Description |
|---|
| subject | Required | A string that contains the identification message subject. Maximum size is 254 characters. |
| body | Required | A string that contains the identification message body. Maximum size is 16376 characters. |
| preview | Optional | A string that contains the message preview. Maximum size is 300 characters. |
| availability | Required | An integer that denotes the availability of the identification message in seconds. |
| callbackUrl | Optional Only available when PassByME is deployed on premise. Contact sales@passbyme.com for on premise offers | A string that contains a callback url used for recipient status reporting. Maximum size is 254 characters. Method: POST Request body: tracking info in JSON format. See Output |
| minimumTrustLevel | Optional | This level defines the trustiness of the certificate required to upload the evidence of the message :"any", "advanced" or "qualified" (optional, default: "any"). |
| externalId | Optional | The unique part of the message id can be set by the sender (optional, default: server-side generated random value). |
Request example
/identification
{"subject":"Example message subject","body":"The body of your message.","preview":"The preview of your message.","availability":300,"callbackUrl":"www.report.sales.passbyme.com","minimumTrustLevel":"any","externalId":"LsdyqjBQ"}
Success response format
| Field | Type | Description |
|---|
| messageId | String | Identifier of the sent identification message. |
| qrContent | String | This content should be presented in a QR code for the user to be identified. |
| expirationDate | String (ISO 8601) | The expiry date of the current identification message. |
Success response
HTTP/1.0 200 OK
{"messageId":"@pbmdevcore1-1.3.6.1.4.1.21528.3.3.2.1.121376.2.122416-LsdyqjBQ","qrContent":"pbmid:@pbmdevcore1-1.3.6.1.4.1.21528.3.3.2.1.121376.2.122416-LsdyqjBQ","expirationDate":"2018-05-25T13:29:46.820Z"}
Tracking Identification Message
Returns the identifier of the customer, who has adopted the identification message, identified by the given messageId.
Before a valid identification it is returning a HTTP 204 response (No content) with empty body.
get
/identification/:messageId
Parameters
query string
| Field | Mandatory | Description |
|---|
| messageId | Required | The identifier of the identification message to be tracked. |
Request example
/identification/@pbmdevcore1-1.3.6.1.4.1.21528.3.3.2.1.121376.2.122416-LsdyqjBQ
Success response format
| Field | Type | Description |
|---|
| ID | String | Unique OID of the identified customer identity. |
Success response
HTTP/1.0 200 OK
{"ID":"1.3.6.1.4.1.21528.3.3.2.1.121376.2.126602"}
Evidences API
Download evidence
Download an evidence knowing the corresponding messageId, recipientId and evidenceId.
get
/download/messages/:messageId/recipients/:recipientId/evidences/:evidenceId
Parameters
query string
| Field | Mandatory | Description |
|---|
| messageId | Required | The identifier of the message belonging to the actual evidence. |
| recipientId | Required | The identifier of the recipient who uploaded the evidence. |
| evidenceId | Required | The identifier of the evidence to be downloaded. |
Request example
/download/messages/@pbm1-1.3.6.1.4.1.21528.3.3.2.1.2.122416-LTggLGHV/recipients/1.3.6.1.4.1.21528.3.3.2.1.1.121377/evidences/410196
Success response format
| Field | Type | Description |
|---|
| P7S | The downloadable evidence in p7s (pkcs7 signature) format. |
Success response
HTTP/1.0 200 OK
"<P7S bytes>"
Download evidence
Download an evidence knowing the corresponding messageId, recipientId and evidence type.
get
/download/messages/:messageId/recipients/:recipientId/evidencetype/:evidenceType
Parameters
query string
| Field | Mandatory | Description |
|---|
| messageId | Required | The identifier of the message belonging to the actual evidence. |
| recipientId | Required | The identifier of the recipient who uploaded the evidence. |
| evidenceType | Required | The identifier of the evidence type to be downloaded: "pod" (proof of delivery) or "st" (signed transaction). |
Request example
/download/messages/@pbm1-1.3.6.1.4.1.21528.3.3.2.1.2.122416-LTggLGHV/recipients/1.3.6.1.4.1.21528.3.3.2.1.1.121377/evidencetype/pod
Success response format
| Field | Type | Description |
|---|
| P7S | The downloadable evidence in p7s (pkcs7 signature) format. |
Success response
HTTP/1.0 200 OK
"<P7S bytes>"
Download evidence by evidenceId
Download an evidence by its id.
get
/download/evidences/:evidenceId
Parameters
query string
| Field | Mandatory | Description |
|---|
| evidenceId | Required | The identifier of the evidence to be downloaded. |
Request example
/download/evidences/410196
Success response format
| Field | Type | Description |
|---|
| P7S | The downloadable evidence in p7s (pkcs7 signature) format. |
Success response
HTTP/1.0 200 OK
"<P7S bytes>"
Download message details
Download detailed information of the specified message.
get
/download/messages/:messageId
Parameters
query string
| Field | Mandatory | Description |
|---|
| messageId | Optional | Identifier of the sent message. |
Request example
/download/messages/@pbmcore1-1.3.6.1.4.1.21528.3.3.2.9045.2.10111-fZFbDOsv
Success response format
| Field | Type | Description |
|---|
| messageId | String | Identifier of the sent message. |
| submitDate | String (ISO 8601) | The datetime of submitting the message. |
| subject | String | A string that contains the sent message subject |
| senderApplicationName | String | A string that contains the sent message subject |
| senderApplicationId | String | A id of the sender application |
| expiration | String (ISO 8601) | The expiry datetime of the current message. |
| messageType | String ("message", "esign", "authorization", "oneTimePassword", "configurationUpdate" or "identification") | The type of the message. |
| recipients | Array | A list of recipients and their status information. |
Success response
HTTP/1.0 200 OK
{"messageId":"@pbmcore1-1.3.6.1.4.1.21528.3.3.2.9045.2.10111-fZFbDOsv","submitDate":"2016-08-16T11:49:03.833Z","subject":"subject","senderApplicationName":"TestApplication","senderApplicationId":"1.3.6.1.4.1.21528.3.3.2.1.121376.2.122416","expiration":"2016-08-16T12:49:03.833Z","messageType":"message","recipients":[{"userId":"john.doe@passbyme.com","oid":"1.3.6.1.4.1.21528.3.3.2.1.121376.1.121377","status":"PENDING","lastUpdateDate":"2016-08-16T11:55:03.833Z","evidences":[{"status":"PENDING","deviceName":"Vendor F12G","submitDate":"2016-08-16T11:55:03.833Z","evidenceType":"PROOF_OF_DELIVERY","evidenceUrl":"https://admin.passbyme.com/register/rest/download/messagehistory/@pbmcore1-1.3.6.1.4.1.21528.3.3.2.9045.2.10111-fZFbDOsv/recipients/1.3.6.1.4.1.21528.3.3.2.1.121376.1.121377/evidenceType/pod","attachment":"PROOF_OF_DELIVERY","format":"JSON"}]}]}
Status Codes
Messages has the following valid status codes.
| Status Code | Description |
|---|
| PENDING | Initial status of the message. |
| NOTIFIED | The recipient has been notified about a new message. |
| DOWNLOADED | The recipient has downloaded the message, but has not uploaded the evidence yet. |
| SEEN | The recipient has seen the message and uploaded the evidence. |
| NOT_SEEN | The recipient has not seen the message. |
| NOT_NOTIFIED | The recipient has not received the notification. |
| NOT_DOWNLOADED | The recipient received the notification about the message but has not downloaded the message. |
| NO_DEVICE | The message could not be sent because the recipient had no PassByME ready device that supports messaging. |
| FAILED | The message could not be sent because of an error. |
| DISABLED | The message could not be sent because the recipient is disabled. |
| CANCELLED | The message was cancelled by the sender. |
| APPROVED | Authentication has finished successfully. |
| DENIED | The user has cancelled the authentication. |