Aller au contenu

Endpoints

Configuration

API URL : https://api.neomia.ai/pulse

API Key

To use this API, please send your neomia Pulse API key in the headers for each request. 

1
    {'apikey' : '<APIKEY>'}
*Replace <APIKEY> with your own api key.

For further details, please consult our documentation Swagger here.

User Reference

The parameter indicated userRef represents your custom user ID. We recommend using a name respecting email format conventions.

Request : Status

GET /status

This endpoint allows to know if Pulse API is up to receive request.

Response : OK

1
2
3
4
5
6
7
{
    "timestamp": "2023-09-15T12:31:15.467Z",
    "success": true,
    "message": "The server is up and ready to receive requests.",
    "status": "OK",
    "version": "b03da725"
}

Response : NOK

1
2
3
4
5
6
7
{
    "timestamp": "2023-09-15T12:31:15.467Z",
    "success": true,
    "message": "The server is up but is not ready to receive requests. There are no available classifiers/workers.",
    "status": "NOK",
    "version": "b03da725"
}

Request : User Verify

POST /user-verify/{userRef}

This is the main API endpoint that allows to check the pattern of a user.

  • If a tId is provided, the pattern will be compared to a reference pattern having the same tId.
  • If a tId is not provided, the pattern will be compared to the existing associated patterns.
  • If the user does not exists in the database, the API return a 404 when the headers does not contain x-enrollment : USER property.
User Enrollment

By default this endpoint does not create a user. If you want allow the user creation please add the following header property :

1
{'x-enrollment' : 'USER'}

If the user allready exists, this has no effect.

Request Body (Pattern)

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
{
  "agent": {
    "type": "web",
    "version": "0.6.6",
    "mode": "one-time"
  },
  "version": "0.6.6",
  "sId": "24324b3f-3202-45a1-80c6-eddbea4b3c9b",
  "kevt": [
    {
      "t": 1694782167307,
      "et": 5495.600000000093,
      "type": "keydown",
      "eId": "exampleInputEmail1",
      "ss": null,
      "se": null,
      "k": "h",
      "c": "KeyH",
      "kc": 72,
      "r": false,
      "l": 0,
      "ctrlKey": false,
      "altKey": false,
      "shiftKey": false,
      "metaKey": false,
      "seqn": 0
    },
    {
      "t": 1694782167371,
      "et": 5559.699999999721,
      "type": "keyup",
      "eId": "exampleInputEmail1",
      "ss": null,
      "se": null,
      "k": "h",
      "c": "KeyH",
      "kc": 72,
      "r": false,
      "l": 0,
      "ctrlKey": false,
      "altKey": false,
      "shiftKey": false,
      "metaKey": false,
      "seqn": 0
    },
    {
      "t": 1694782167402,
      "et": 5591.5,
      "type": "keydown",
      "eId": "exampleInputEmail1",
      "ss": null,
      "se": null,
      "k": "e",
      "c": "KeyE",
      "kc": 69,
      "r": false,
      "l": 0,
      "ctrlKey": false,
      "altKey": false,
      "shiftKey": false,
      "metaKey": false,
      "seqn": 1
    },
    {
      "t": 1694782167466,
      "et": 5655.600000000093,
      "type": "keyup",
      "eId": "exampleInputEmail1",
      "ss": null,
      "se": null,
      "k": "e",
      "c": "KeyE",
      "kc": 69,
      "r": false,
      "l": 0,
      "ctrlKey": false,
      "altKey": false,
      "shiftKey": false,
      "metaKey": false,
      "seqn": 1
    }
  ],
  "d": {
    "ua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/117.0.0.0 Safari/537.36",
    "uaData": {
      "architecture": "x86",
      "bitness": "64",
      "brands": [
        {
          "brand": "Chromium",
          "version": "117"
        },
        {
          "brand": "Not;A=Brand",
          "version": "8"
        }
      ],
      "fullVersionList": [
        {
          "brand": "Chromium",
          "version": "117.0.5938.63"
        },
        {
          "brand": "Not;A=Brand",
          "version": "8.0.0.0"
        }
      ],
      "mobile": false,
      "model": "",
      "platform": "Windows",
      "platformVersion": "15.0.0",
      "uaFullVersion": "117.0.5938.63",
      "wow64": false
    },
    "sH": 1080,
    "sW": 1920,
    "iH": 923,
    "iW": 1920,
    "pxd": 24,
    "dpr": 1,
    "tz": "Europe/Paris",
    "cpuThreads": 12,
    "navCookiesEnabled": true,
    "navLanguage": "fr",
    "gpu": "ANGLE (Intel, Intel(R) UHD Graphics 770 Direct3D11 vs_5_0 ps_5_0, D3D11)",
    "fonts": [
      "Agency FB",
      "Calibri",
      "Century",
      "Century Gothic",
      "Consolas",
      "Franklin Gothic",
      "Haettenschweiler",
      "Leelawadee",
      "Lucida Bright",
      "Lucida Sans",
      "Liberation Mono",
      "MS Outlook",
      "MS Reference Specialty",
      "MS UI Gothic",
      "MT Extra",
      "Marlett",
      "Microsoft Uighur",
      "Monotype Corsiva",
      "Pristina",
      "Segoe UI Light",
      "Tahoma"
    ]
  },
  "m": [
    {
      "et": 1016.1000000000931,
      "type": "mousemove",
      "sX": 370,
      "sY": 118,
      "mX": 0,
      "mY": 0
    },
    {
      "et": 1023.5,
      "type": "mousemove",
      "sX": 417,
      "sY": 157,
      "mX": 47,
      "mY": 39
    }
  ],
  "tId": 99162322,
  "k": [
    {
      "k": "h",
      "c": "KeyH",
      "kc": 72,
      "et": 5495.600000000093,
      "s": 5495.6,
      "h": 64.1
    },
    {
      "k": "e",
      "c": "KeyE",
      "kc": 69,
      "et": 5591.5,
      "s": 95.9,
      "h": 64.1
    },
    {
      "k": "l",
      "c": "KeyL",
      "kc": 76,
      "et": 5751.600000000093,
      "s": 160.1,
      "h": 48.3
    }
  ]
}

Response : Enrollment

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
    "timestamp": "2023-09-15T12:53:36.589Z",
    "success": true,
    "message": "Done",
    "action": "enrolled",
    "actions": [
        "enrolled"
    ],
    "authentication": null,
    "biometricStatus": "in-progress",
    "refPatternsStatus": {
        "textVisible": "ok",
        "textSensitive": "ok"
    },
    "reason": ""
}
Status code : 201

Response : Verify

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
    "timestamp": "2023-09-15T12:54:14.000Z",
    "success": true,
    "message": "Done",
    "action": "verified",
    "actions": [
        "verified"
    ],
    "authentication": {
        "id": "650453f5d046ca4ac0080bae",
        "timestamp": "2023-09-15T12:54:13.985Z",
        "authenticated": true,
        "confidence": 0.9561016974429224,
        "confidenceBiometrics": 0.9561016974429224,
        "confidenceContext": 1.0,
        "recommendedAction": "auth",
        "patternTestId": "650453f5d046ca4ac0080ba5",
        "policyId": "650436012b2a971a0488408a",
        "nPatternsRef": 1,
        "nPatternsRefUsed": 1
    },
    "biometricStatus": "in-progress",
    "refPatternsStatus": {
        "textVisible": "ok",
        "textSensitive": "ok"
    },
    "reason": ""
}
Status code : 200

Response : User does not exists

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
    "timestamp": "2023-01-27T10:57:54.662Z",
    "success": false,
    "message": "This user does not exist. Add 'x-enrollment: USER' to headers to enroll a new user.",
    "action": "none",
    "actions": [
        "none"
    ],
    "authentication": null,
    "reason": "USER_NOT_FOUND"
}

Status code : 404

Response : Robot detected

If a pattern is generated by a bot (for example, a password manager), Pulse returns a bot detection response.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
    "timestamp": "2023-01-27T15:25:32.434Z",
    "success": true,
    "message": "Done",
    "action": "verified",
    "actions": [
        "verified"
    ],
    "authentication": {
        "id": "63d3ecec10c7080287349ef2",
        "timestamp": "2023-01-27T15:25:32.548Z",
        "authenticated": false,
        "confidence": 1.0,
        "confidenceBiometrics": null,
        "confidenceContext": 0.8333333333333333,
        "recommendedAction": "block",
        "patternTestId": "63d3ecec10c7080287349eef",
        "policyId": "6204f77ddea5790f2660d450"
    },
    "biometricStatus": "in-progress",
    "refPatternsStatus": {
        "textVisible": "ok",
        "textSensitive": "ok"
    },
    "reason": "detection-bot"
}

Status code : 200

Request : User Action

POST /user-action/{userRef}

Allow the client to execute different actions in relation with the specific userRef. The variable type determines the action and can take following values :

  • LINK_PATTERN : add the sended pattern as reference to user's profile.
  • LINK_PATTERN_ID : add the recorded pattern with the specific pattern identifier to user's profile.
  • UNLINK_PATTERN_ID : remove the recorded pattern with the specific pattern identifier to user's profile.
  • RESET_BIOMETRIC_PROFILE : remove all reference patterns from user's profile. If there is a pattern or a pattern id in data attribute, this pattern will be linked.

Add pattern ID as reference

Request body

1
2
3
4
{
    "type" : "LINK_PATTERN_ID",
    "data" : "5e3af589923e5b0010a77bb0"
}

Or

1
2
3
4
{
    "type" : "LINK_PATTERN_ID",
    "data" : ["63909817e02d78e2835d02a0", "639098a4e02d78e2835d0333", "639098f9e02d78e2835d03d5"]
}

Successful response

1
2
3
4
5
6
7
{
    "timestamp": "2021-08-23T07:14:42.185Z",
    "success": true,
    "message": "Done",
    "state": null,
    "id" : null
}

Add pattern as reference

Request body

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
{
    "type" : "LINK_PATTERN",
    "data" : {
        "ip": "172.23.32.1",
        "agent": {
            "type": "windows",
            "version": "0.0.1",
            "mode": "one-time"
        },
        "d": {
            "ua": "",
            "uaData": {
                "architecture": "x64",
                "bitness": "64",
                "mobile": false,
                "model": "",
                "platform": "Windows",
                "platformVersion": "Microsoft Windows NT 6.2.9200.0",
                "uaFullVersion": "4.0.30319.42000",
                "wow64": true,
                "brands": [
                ],
                "fullVersionList": [
                ]
            },
            "navCookiesEnabled": null,
            "cpuThreads": 6,
            "sW": 1920,
            "sH": 1080,
            "pxd": 24,
            "dpr": 1,
            "navLanguage": "fr-FR",
            "tz": "Paris, Madrid",
            "iH": 728,
            "iW": 632,
            "gpu": "Intel(R) UHD Graphics 630",
            "fonts": [
            "Agency FB"
            ]
        },
        "version": "0.6.4",
        "sId": "f177b438-bd09-4b43-b64b-e125a0b00923",
        "tId": -1198938152,
        "v": [],
        "m": [
        {
            "t": 1674663922453,
            "et": 7006.8144000000002,
            "type": "mousemove",
            "sX": 113,
            "sY": 417,
            "mX": 0,
            "mY": 0
        }
        ],
        "k": [
        {
            "et": 17101.952600000001,
            "s": 271.57310000000143,
            "h": 61.059499999999389
        }
        ]
    }
}

Successful response

1
2
3
4
5
6
7
{
    "timestamp": "2021-08-23T07:14:42.185Z",
    "success": true,
    "message": "Done",
    "id": null,
    "state" : null
}

Reset biometric profile

Request body

1
2
3
{
    "type" : "RESET_BIOMETRIC_PROFILE"
}

Successful response

1
2
3
4
5
6
7
{
    "timestamp": "2021-08-23T07:14:42.185Z",
    "success": true,
    "message": "Done",
    "id": "63ec9c6bf4ad424a0320aabd",
    "state": "PENDING"
}

Deletes patterns in references.

We recommend using the Pulse Dahboard to perform this operation !

Request : Get Users

GET /users/{userRef}

This endpoint get information about a user and his associated patterns.

Response : User Exist

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
    "timestamp": "2023-09-15T13:03:33.508Z",
    "success": true,
    "message": "Done",
    "org_id": "60d09f47b2f17ea547375768",
    "user_id": "650453d0af3aded65427d68b",
    "org_consumer_id": "systancia_dev",
    "orgName": "systancia_dev",
    "userRef": "dev@neomia.ai",
    "nPatterns": 2,
    "nPatternsRef": 1,
    "biometricStatus": "ok",
    "refPatternsStatus": {
        "textVisible": "ok",
        "textSensitive": "ok"
    },
    "created": "2023-09-15T12:53:36.546Z"
}

Status code : 200

Patterns Status

  • If the value of refPatternsStatus.textVisible is ok, the user is ready to be authenticated with Pulse BiometricPass.

  • If the value of refPatternsStatus.textVisible is nok, the user must be re-onboarded. We recommend using the procedure indicated here to re-onboard the user (method complete-profile).

Response : User not Exist

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
    "timestamp": "2023-09-15T13:27:30.278Z",
    "success": false,
    "message": "User not found",
    "org_id": null,
    "user_id": null,
    "org_consumer_id": null,
    "orgName": null,
    "userRef": null,
    "nPatterns": 0,
    "nPatternsRef": 0,
    "biometricStatus": "not-ready",
    "refPatternsStatus": {
        "textVisible": "nok",
        "textSensitive": "nok"
    },
    "created": null
}

Status code : 404

Request : Delete Users

DELETE /users/{userRef}

This endpoint delete a user and his associated patterns.

Successful Response

The API response return the number of patterns that has been deleted.

1
2
3
4
5
6
7
{
    "timestamp": "2021-08-19T15:49:27.747Z",
    "success": true,
    "message": "Done",
    "user_id": "649abe035c158000e36f36af",
    "n_patterns_deleted": 10
}