Business User Events

Create a Business User Event

POST

POST Business User Events

/events/business/user endpoint allows you to operate on the Business User Events entity.

User events are created after the initial POST /business/users call (which creates a user) and are used to:

  • Update the STATE and KYC Status of the user, using the userStateDetails or kycStatusDetails field
  • Update the user details, using the updatedBusinessUserAttributes field.

If you have neither of the above two use cases, you do not need to use user events.

Payload

Each user event needs three mandatory fields:

  • timestamp- the timestamp of when the event was created or occured in your system
  • userId - The ID of the transaction for which this event is generated.

In order to make individual events retrievable, you also need to pass in a unique eventId to the request body.

Query parameters

allowUserTypeConversionenumOptional
Boolean string whether Flagright should allow a Business user event to be applied to a Consumer user with the same user ID. This will converts a Consumer user to a Business user.
Allowed values: truefalse

Request

This endpoint expects an object.
timestamp
doubleRequired
Timestamp of the event
userId
stringRequired
Transaction ID the event pertains to
eventId
stringOptional
Unique event ID
reason
stringOptional
Reason for the event or a state change
eventDescription
stringOptional
Event description
updatedBusinessUserAttributes
objectOptional
Model for a business user - optional fields

Response

This endpoint returns an object
userId
string
Unique user ID for the user
createdTimestamp
double
Timestamp when the user was created
legalEntity
object
Model for business user legal entity details
userStateDetails
objectOptional
kycStatusDetails
objectOptional
shareHolders
list of objectsOptional
Shareholders (beneficiaries) of the company that hold at least 25% ownership. Can be another company or an individual
directors
list of objectsOptional
Director(s) of the company. Must be at least one
transactionLimits
objectOptional
Model for transaction limits for a given user
riskLevel
enumOptional
Allowed values: VERY_HIGHHIGHMEDIUMLOWVERY_LOW
allowedPaymentMethods
list of enumsOptional
linkedEntities
objectOptional
acquisitionChannel
enumOptional
Model for User acquisition channel
savedPaymentDetails
list of unionsOptional
mccDetails
objectOptional
tags
list of objectsOptional
Additional information that can be added via tags
executedRules
list of objectsOptional
Model for list of executed rules
hitRules
list of objectsOptional
Model for list of hit rules
riskScoreDetails
objectOptional

Errors

POST
1curl -X POST https://sandbox.api.flagright.com/events/business/user \
2 -H "x-api-key: <apiKey>" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "timestamp": 1.1,
6 "userId": "userId"
7}'
1{
2 "userId": "userId",
3 "createdTimestamp": 1.1,
4 "legalEntity": {
5 "companyGeneralDetails": {
6 "legalName": "Ozkan Hazelnut Export JSC",
7 "businessIndustry": [
8 "Farming"
9 ],
10 "mainProductsServicesSold": [
11 "Hazelnut"
12 ],
13 "userSegment": "SOLE_PROPRIETORSHIP",
14 "userRegistrationStatus": "REGISTERED",
15 "tags": [
16 {
17 "key": "customKey",
18 "value": "customValue"
19 }
20 ]
21 },
22 "companyFinancialDetails": {
23 "expectedTransactionAmountPerMonth": {
24 "amountValue": 800,
25 "amountCurrency": "GBP"
26 },
27 "expectedTurnoverPerMonth": {
28 "amountValue": 8000,
29 "amountCurrency": "USD"
30 },
31 "tags": [
32 {
33 "key": "customKey",
34 "value": "customValue"
35 }
36 ]
37 },
38 "companyRegistrationDetails": {
39 "registrationIdentifier": "PSJ554342",
40 "registrationCountry": "DE",
41 "taxIdentifier": "taxIdentifier",
42 "legalEntityType": "legalEntityType",
43 "dateOfRegistration": "dateOfRegistration",
44 "tags": [
45 {
46 "key": "customKey",
47 "value": "customValue"
48 }
49 ]
50 },
51 "reasonForAccountOpening": [
52 "reasonForAccountOpening"
53 ],
54 "sourceOfFunds": [
55 "Earnings"
56 ],
57 "contactDetails": {
58 "emailIds": [
59 "emailIds"
60 ],
61 "contactNumbers": [
62 "contactNumbers"
63 ],
64 "faxNumbers": [
65 "faxNumbers"
66 ],
67 "websites": [
68 "websites"
69 ],
70 "addresses": [
71 {
72 "addressLines": [
73 "Klara-Franke Str 20"
74 ],
75 "city": "Berlin",
76 "country": "Germany",
77 "postcode": "10557",
78 "state": "Berlin",
79 "tags": [
80 {
81 "key": "customKey",
82 "value": "customValue"
83 }
84 ]
85 }
86 ]
87 }
88 },
89 "userStateDetails": {
90 "state": "UNACCEPTABLE",
91 "userId": "userId",
92 "reason": "reason"
93 },
94 "kycStatusDetails": {
95 "reason": "reason",
96 "status": "SUCCESSFUL",
97 "userId": "userId"
98 },
99 "shareHolders": [
100 {
101 "generalDetails": {
102 "name": {
103 "firstName": "Baran",
104 "middleName": "Realblood",
105 "lastName": "Ozkan"
106 },
107 "dateOfBirth": "1991-01-01",
108 "countryOfResidence": "US",
109 "countryOfNationality": "DE"
110 },
111 "legalDocuments": [
112 {
113 "documentType": "passport",
114 "documentNumber": "Z9431P",
115 "documentIssuedCountry": "DE",
116 "documentIssuedDate": 1639939034000,
117 "documentExpirationDate": 1839939034000,
118 "tags": [
119 {
120 "key": "customerType",
121 "value": "wallet"
122 }
123 ],
124 "nameOnDocument": {
125 "firstName": "Baran",
126 "middleName": "Realblood",
127 "lastName": "Ozkan"
128 }
129 }
130 ],
131 "contactDetails": {
132 "emailIds": [
133 "baran@flagright.com"
134 ],
135 "contactNumbers": [
136 "+371 123132"
137 ],
138 "websites": [
139 "flagright.com"
140 ],
141 "addresses": [
142 {
143 "addressLines": [
144 "Klara-Franke Str 20"
145 ],
146 "city": "Berlin",
147 "country": "Germany",
148 "postcode": "10557",
149 "state": "Berlin",
150 "tags": [
151 {
152 "key": "customKey",
153 "value": "customValue"
154 }
155 ]
156 }
157 ]
158 },
159 "pepStatus": [
160 {
161 "isPepHit": true
162 }
163 ],
164 "tags": [
165 {
166 "key": "customKey",
167 "value": "customValue"
168 }
169 ]
170 }
171 ],
172 "directors": [
173 {
174 "generalDetails": {
175 "name": {
176 "firstName": "Baran",
177 "middleName": "Realblood",
178 "lastName": "Ozkan"
179 },
180 "dateOfBirth": "1991-01-01",
181 "countryOfResidence": "US",
182 "countryOfNationality": "DE"
183 },
184 "legalDocuments": [
185 {
186 "documentType": "passport",
187 "documentNumber": "Z9431P",
188 "documentIssuedCountry": "DE",
189 "documentIssuedDate": 1639939034000,
190 "documentExpirationDate": 1839939034000,
191 "tags": [
192 {
193 "key": "customerType",
194 "value": "wallet"
195 }
196 ],
197 "nameOnDocument": {
198 "firstName": "Baran",
199 "middleName": "Realblood",
200 "lastName": "Ozkan"
201 }
202 }
203 ],
204 "contactDetails": {
205 "emailIds": [
206 "baran@flagright.com"
207 ],
208 "contactNumbers": [
209 "+371 123132"
210 ],
211 "websites": [
212 "flagright.com"
213 ],
214 "addresses": [
215 {
216 "addressLines": [
217 "Klara-Franke Str 20"
218 ],
219 "city": "Berlin",
220 "country": "Germany",
221 "postcode": "10557",
222 "state": "Berlin",
223 "tags": [
224 {
225 "key": "customKey",
226 "value": "customValue"
227 }
228 ]
229 }
230 ]
231 },
232 "pepStatus": [
233 {
234 "isPepHit": true
235 }
236 ],
237 "tags": [
238 {
239 "key": "customKey",
240 "value": "customValue"
241 }
242 ]
243 }
244 ],
245 "transactionLimits": {
246 "maximumDailyTransactionLimit": {
247 "amountValue": 800,
248 "amountCurrency": "GBP"
249 },
250 "maximumWeeklyTransactionLimit": {
251 "amountValue": 800,
252 "amountCurrency": "GBP"
253 },
254 "maximumMonthlyTransactionLimit": {
255 "amountValue": 800,
256 "amountCurrency": "GBP"
257 },
258 "maximumQuarterlyTransactionLimit": {
259 "amountValue": 800,
260 "amountCurrency": "GBP"
261 },
262 "maximumTransactionLimit": {
263 "amountValue": 800,
264 "amountCurrency": "GBP"
265 },
266 "maximumYearlyTransactionLimit": {
267 "amountValue": 800,
268 "amountCurrency": "GBP"
269 }
270 },
271 "riskLevel": "VERY_HIGH",
272 "allowedPaymentMethods": [
273 "ACH"
274 ],
275 "linkedEntities": {
276 "parentUserId": "parentUserId",
277 "childUserIds": [
278 "childUserIds"
279 ]
280 },
281 "acquisitionChannel": "ORGANIC",
282 "mccDetails": {
283 "code": 1.1,
284 "description": "description"
285 },
286 "tags": [
287 {
288 "key": "customKey",
289 "value": "customValue"
290 }
291 ],
292 "executedRules": [
293 {
294 "ruleInstanceId": "ruleInstanceId",
295 "ruleName": "Proof of funds for high value transactions",
296 "ruleDescription": "If a user makes a remittance transaction >= 1800 in EUR - ask for proof of funds",
297 "ruleAction": "BLOCK",
298 "ruleHit": true,
299 "ruleId": "R-1a",
300 "vars": [
301 {
302 "value": {}
303 }
304 ],
305 "labels": [
306 "UNEXPECTED_BEHAVIOR"
307 ],
308 "nature": "AML",
309 "isShadow": true
310 }
311 ],
312 "hitRules": [
313 {
314 "ruleInstanceId": "ruleInstanceId",
315 "ruleName": "Proof of funds for high value transactions",
316 "ruleDescription": "If a user makes a remittance transaction >= 1800 in EUR - ask for proof of funds",
317 "ruleAction": "BLOCK",
318 "ruleId": "R-1a",
319 "labels": [
320 "UNEXPECTED_BEHAVIOR"
321 ],
322 "nature": "FRAUD",
323 "isShadow": true
324 }
325 ],
326 "riskScoreDetails": {
327 "kycRiskScore": 1.1,
328 "craRiskScore": 1.1,
329 "kycRiskLevel": "VERY_HIGH",
330 "craRiskLevel": "VERY_HIGH"
331 }
332}