-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathapi-reference.txt
5574 lines (4366 loc) · 291 KB
/
api-reference.txt
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
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
Sift API Overview
Sift is the leader in Digital Trust & Safety, empowering organizations of all sizes
to unlock new revenue without risk using machine learning. Sift helps businesses
to make accurate, real-time decisions that both improve user experience and increase
revenue. You can use Sift whether you’re building a brand new risk system or looking
to augment an existing legacy system.
Sift makes risk predictions in real-time using your own data and data from across
Sift’s global network. Our machine learning systems identify
patterns of behavior across thousands of device, user, network, and transactional
signals. These are often patterns that only a machine learning system can spot. Using
Sift, businesses have stopped 100s billions of dollars of fraud worldwide.
There are many abuse use cases that Sift can stop:
- Payment Protection - Reduce friction at checkout to increase revenue and stop
chargebacks before they hurt your business.
- Account Defense
-- Account Abuse - Stop fake accounts from polluting your service and
block fraudulent users before they harm your business.
-- Account Takeover - Stop fraudulent actors from hijacking users accounts. Keep
your users safe and ensure that they always trust your service.
- Content Integrity - Stop spammy and scammy posts from polluting your service.
Keep your users safe from malicious actors.
- Promotion Abuse - Make sure you’re only rewarding real users by stopping
referral rings and repeated use of promotions.
Sift easily integrates into your existing systems using modern REST APIs , Javascript snippet , and SDKs for iOS and Android. In addition, Sift offers Workflows , a powerful rules automation platform, and
Review Queues. These enable you to build a complete solution with Sift.
The next sections will walk you through getting started with Sift.
Sending Data to Sift
To use Sift, we need to know about the transactions and events on your website and/or mobile apps and
what actions you take in response to them. This includes:
- How your users are interacting on your website and/or mobile apps (e.g., what pages
they are visiting, which devices they are using, how long they spend on each page, etc).
We automatically collect this data when you add our JavaScript snippet to your
website and our Mobile SDKs to your app.
- What actions your users are taking, usually key user lifecycle events (e.g., creating an
account, placing an order, posting content to other users, etc.). You will send this data
from your application to Sift via our REST API .
- What actions your business is taking in response to users (e.g., approve an order, block and event
due to fraud, cancel order due to chargeback, etc). You will also send this data from your
application to Sift via our Decisions API .
Because Sift gets smarter the more data it has about your business, you can jump start your
integration by backfilling a few months worth of historical data.
If you have any questions about what data to send to Sift, check our integration guides for recommendations based on your type of
business. If you have any other questions, don’t hesitate to contact us at [email protected] .
Get Started with Sift Scores
Once you start sending data, Sift starts to make predictions about whether a user’s actions are
legitimate or fraudulent. Sift represents this risk with a score between 0 and 100, where risky events
have higher scores. Sift generates a unique score per type of fraud you're preventing
(e.g., payment fraud, content abuse, etc.), so a user’s events could have a high score for one type
of abuse and a low score for another.
Sift’s risk scores are generated in real-time in response to whatever data has been sent.
As you send more data for an event, the predictions will become more accurate. Scores can
both increase or decrease in response to new data. It all depends on whether the user is
exhibiting legitimate or risky patterns.
You’ll use Sift risk scores to help you make decisions about your users’ actions at key lifecycle
events (e.g., creating an account, placing an order, etc.). For example, whether you want to
automatically block an order, send it to manual review or approve it, all these choices can
be decided based on the Sift Score. Since all businesses are different, finding your unique
score thresholds that achieve your business goals is key. Don’t hesitate to email [email protected] if you need any help
choosing the score thresholds that make sense for you.
Build your Business Logic With Sift Scores
The final step to using Sift is adding business logic that makes Decisions based
on the Sift risk score. This step is so important because the real power of Sift
is using machine learning to efficiently and accurately automate decisions in your business.
Here’s an example of using Sift to stop payments fraud. When an order is created by a user,
the business checks the Sift Score:
- If the score is low, automatically approve the order.
- If the score is high, automatically block the order and flag the user ID.
- If the score is mid range, send the order to a review queue where an analyst can decide the best next step.
To build this business logic, there are two different approaches that you can take.
You should choose your approach based on your business needs.
Create a Sift Workflow
You can build your business logic on Sift with our Workflows Platform. Workflows let you set
up criteria that get evaluated whenever specified events occur. For example, you can setup a
Workflow that evaluates whenever a user creates an account. You can specify criteria (e.g.,
country = “Canada” & Sift Score > 80) that when met, Sift will auto-block, auto-accept, or send the user
ID to a Sift Review Queue for manual review. The configuration is all up to you, and logic can be
updated by your fraud manager without any developer involvement. Learn more about setting up Sift Workflows .
Create Business Logic Within Your App
You can build your business logic within your application using Sift Scores. You can request
Sift Scores synchronously each time you send an event. This will allow you to implement Sift Scores into your
existing internal systems and manual review tools. Note, make sure to send all of the decisions
from your system to Sift as Decision events.
For more information on building any of the above, check out our list of vertical-specific tutorials . They'll help you customize your Sift
integration to fit your unique business needs. Client libraries are also available.
Overview
The Core Topics section covers items that are generally applicable across
Sift’s APIs and answers questions common developers have about integrating
and using Sift.
Client Libraries
Sift provides client libraries in Python, Ruby, PHP and Java. They provide a wrapper for
Sift’s APIs and will help with sending events and decisions or receiving scores.
Installation instructions can be found in the Client Libraries Tutorial or in the respective Github repositories below:
Python - https://github.com/SiftScience/sift-python
Ruby - https://github.com/SiftScience/sift-ruby
PHP - https://github.com/SiftScience/sift-php
Java - https://github.com/SiftScience/sift-java
Note
If you’re not seeing a client library in a language you use, please let us know what you’d
like us to support via email: [email protected] .
Authentication
Authentication is required for requests to Sift. Sift uses API Keys to
authenticate REST API requests, and a separate Beacon Key to authenticate events from our
SDKs. Keys are available in two classes: production for your live site once you’ve
tested new parts of an integration, and sandbox for testing or getting started.
For greater security, you may also create a restricted API Key with
specific permissions to your account data. A restricted key provides
only permissions and access to data for an application that you permit,
protecting the data that the application doesn’t need. For example, you
may create a restricted key that grants only permission to retrieve Order
data for the purposes of informing your Chargeback Management service. API
Keys offer the ability to edit access to the following resources:
- Events API
- Scores - Score and Rescore
- Feedback - Labels and Decisions
- Device Fingerprinting
- Verifications API
- Webhooks API
- Retrieve Orders
- Console widget API
If a restricted key is no longer needed, or possibly compromised, access
to the key may be disabled or revoked at any time. You also have the ability
to edit the permissions of already existing keys.
Restricted keys are only intended to be used for applications which require
partial access to your Sift data, and should not be used for the standard Sift integration.
Keys can found within the Sift Console under API Keys .
Detailed guidance for each API or SDK can found within their reference sections.
Requirements for Component JS SDK, iOS SDK, and Android SDK - Authenticate with a Beacon Key
Requirements for Component Events API, Score API - Authenticate with API Keys
Requirements for Component Decisions API, Device Fingerprinting API - Authenticate with API Keys and the Account ID
Note
When integrating Sift, it’s strongly recommended that you first test your changes by
sending all data to the sandbox console with your sandbox API Keys prior to sending
data with production API Keys.
For authenticating Decision Webhooks sent to your servers by Sift, you can configure a Webhook Signature Key .
Sandbox
Sift recommends that developers utilize the sandbox environment when testing new
elements of Sift. This sandbox environment allows you to send test events or client data
to Sift without impacting the scores Sift produces in production. To get access to your
sandbox keys, visit the API Keys section
of the console Developer center and make sure you’ve selected sandbox mode. Selecting
sandbox mode will switch you to the sandbox view so you can see all your test data in
the console (e.g. Explore, Queues, Workflows, etc.).
Error Reference
A successful API request will respond with an HTTP 200 . An invalid API
request will respond with an HTTP 400 . The response body will be a JSON
object describing why the request failed. If Sift’s servers are dealing with unexpected
problems, you’ll get a HTTP 500 response. A non-zero status indicates an error.
In the case that you’re using the return_score or return_workflow_status query parameter, you’ll also want to examine the score object within the response for failures.
Possible Status Codes
- -4 Service currently unavailable. Please try again later.
- -3 Server-side timeout processing request. Please try again later.
- -2 Unexpected server-side error
- -1 Unexpected server-side error
- 0 Success
- 50 Invalid Request
- 51 Invalid API Key
- 52 Invalid characters in field name
- 53 Invalid characters in field value
- 54 Specified user_id has no scoreable events
- 55 Missing required field
- 56 Invalid JSON in request
- 57 Invalid HTTP body
- 58 Invalid event: Event occurs in future
- 59 $user_id not URI encoded
- 60 Rate limited
- 61 Account disabled
- 62 Product not selected
- 63 Invalid Credentials
- 100 Required fields missing
- 102 Parameter encoding failure
- 103 No events for user found
- 104 Invalid API version
- 105 Not a valid reserved field
- 106 Missing event specific fields (could reference the event)
- 107 Score not ready for user
- 108 No events for session
- 109 Invalid parameter value
- 110 Incorrect event sent to $transaction only account
- 111 Feature disabled
- 112 Abuse product disabled
- 113 Conflicting fields selected
- 114 Invalid event type
- 115 Invalid abuse type requested
- 116 Event cannot be processed due to legal restrictions
- 117 List exceeds maximum size
Changelog
This changelog tracks updates to Sift's APIs since February 2018. Detailed
changelogs can also be found for our client libraries and SDKs in Github.
Updates for Date December 2022 - API : Added fields $wallet_address and $wallet_type to $payment_method field. API : Added $digital_order complex field which should be used in $create_order , $update_order and $transaction events. API : Added fields $receiver_wallet_address and $receiver_external_address to $transaction event.
Updates for Date November 2022 - API : Added PSP Merchant Management API to manage PSP Merchant summaries.
Updates for Date April 2022 - API : Added $merchant_profile field to $create_account , $chargeback and $update_account events.
Updates for Date Oct 2021 - API : Added $merchant_profile complex field which should be used in $create_order , $update_order and $transaction events. API : Added allowed values $buy , $sell , $send , and $receive for $transaction_type field. API : Added allowed values $sepa_credit , $sepa_instant_credit , $sepa_direct_debit , $wire_credit , $wire_debit , $ach_credit , and $ach_debit for $payment_type field. API : Added fields $status_3ds , $triggered_3ds , $merchant_initiated_transaction , $sent_address , and $received_address to $transaction event. API : Added fields $shortened_iban_first6 , $shortened_iban_last4 , $sepa_direct_debit_mandate , $account_holder_name , $account_number_last5 , $bank_name , and $bank_country to $payment_method field.
Updates for Date July 2021 - API : Added the $shipping_tracking_numbers field and marking $shipping_tracking_number as "Deprecated" (which will later be removed)
Updates for Date December 2020 - API : Changed the description of $user_email field for $login event
Updates for Date September 2020 - API : Added $shipping_carrier and $shipping_tracking_number fields
to $create_order and $update_order events.
Updates for Date May 2020 - API : Added a new allowed value of $apple for $social_sign_on_type field. API : Added a new optional field $decline_category to $transaction to map common decline reason codes to a set of standardized decline categories.
Updates for Date April 2020 - API : Changed required fields on $chargeback event. The $user_id field is now recommended
instead of required, and only one of $order_id or $transaction_id is required.
Updates for Date February 2020 - API : Added more allowed values $face , $fingerprint , push , security_key to field $verification_type in reserved event $verification .
Updates for Date January 2020 - API : Added $client_language field to $app complex field. API : Added $accept_language and $content_language fields to $browser complex field. API : Added $ordered_from complex field which should be used in $create_order , $update_order and $transaction events. API : Added $site_country , $site_domain and $brand_name fields to
custom events and all reserved events except $chargeback , $link_session_to_user , and $flag_content .
Updates for Date February 2019 - API : Added $app and $browser complex fields
to the following reserved events: $content_status , $order_status , $security_notification , and $verification . API : Added $update_password event to capture user- and service-
initiated password changes. API : Added $account_types field to $login , $create_account and $update_account events, to optimize for
various types of user accounts. API : Added $verified_event and $verified_entity_id to the $verification event to track verifications triggered by most
reserved events. API : Added $reason to $verification events to
distinguish verifications that are always on from verifications triggered on risk. API : Added support for knowledge-based verifications through $shared_knowledge field in the $verification event. API : Added $social_sign_on_type to $login for use
in ATO workflows; add reserved values for $microsoft and $amazon accounts.
Updates for Date January 2019 - API : Changed references to Sift API calls in the developer
docs to api.sift.com . Previous requests to api3.siftscience.com will still function, this will simplify the experience for Sift developers. API : Added support for $failure_reason , $account_types , $username and $social_sign_on_type to $login event.
Updates for Date October 2018 - API : Added support for Rescore User and Get User Score APIs. API : Added $app and $browser complex fields
to the following reserved events: $add_item_to_cart , $add_promotion , $create_account , $create_content , $create_order , $logout , $remove_item_from_cart , $transaction , $update_account , $update_content and custom events.
Updates for Date June 2018 - API : Added support for retrieving the decision status of
a session to Decisions API .
Updates for Date March 2018 - API : Released Sift API Version 205, including major updates to $create_content and $update_content . API : Added support for content decisions to Decisions API .
Updates for Date February 2018 - API : Added support for $security_notification event. API : Added support for applying decisions to sessions and retrieve
the list of session-level decisions in Decisions API .
Tracking User IDs and Sessions
Sift uses user ID and session ID to track user IDs and sessions respectively. Both are important
for Sift to be able to understand the activity related to your user ID and it’s strongly
recommended that these are sent whenever possible. A $user_id should be a field
that the user cannot update (e.g. if they can change their email address, a different
unique identifier is recommended).
Tracking Anonymous Actions
You may have some periods of time when the $user_id is not apparent for a user –
either because they have not logged in, or because you’re doing something like guest
checkout where the $user_id has not been assigned yet. In those cases:
- In the Javascript Snippet, set _user_id to the empty string.
- In the Mobile SDKs, call setUserId once the user has signed in.
- In the REST API, for events that you do not need a score returned, set $user_id to an empty string and set $session_id to match the value provided in the JavaScript
snippet, if applicable. Events sent without a user ID will not be scored, and will not trigger
Workflows. Once the user has logged in or created an account, send a subsequent event, or a $link_session_to_user event with the user ID set, and the same session ID.
- In the REST API, for events that need a score returned, pass a different unique identifier
in the $user_id field (e.g. email address or transaction ID).
Reserved and Custom Events
When sending requests to the REST APIs, you can send both reserved and custom data.
Reserved events and fields are events that Sift has defined, that Sift can do advanced
analysis on. When possible, send the user actions taken on your site or app with
reserved events or fields. Reserved events or fields are denoted by the $ character
prior to the event or field name (e.g. $login event or $user_id field).
Each event accepts required, reserved, and custom fields.
Custom Events and Fields
Custom events are events you create to capture actions unique to your application. If
there are key actions or attributes your users take that are not captured by our
reserved events, send these as custom event or custom field. Custom events still require $type , $api_key , and the presence of $user_id or $session_id .
To learn more, see examples in the Custom Events and Fields section.
Backfilling
When you’re first sending data to Sift, you may want to send critical historical data to Sift
so there’s data available for our machine learning predictions. You’ll indicate an event is a
historical event by sending with a $time in the past (using UNIX millis timestamp).
You can then mark known fraudulent events through the Decisions API.
Event Backfill Guidelines
- Send the event with $time in millis.
- You should send 6-12 months of key events (e.g. account, order, content) for all user IDs
(regardless of whether they’re known to be fraudulent or legitimate.)
- Include as much historical data as you have available, including the user’s $ip if known.
- Test in sandbox first before you
send backfill data to production.
- Be aware of rate limits and build in retry logic.
Note: While we use up to 12 months of historical data, users with activity older
than 30 days will not show up in the console.
---Curl
// Sample $create_account event
{
// Required for backfilling
// UNIX timestamp in milliseconds as an integer
"$time" : 1456274104243, // Feb 24 2016 00:35:04 UTC
"$type" : "$create_account",
"$api_key" : "YOUR_API_KEY",
"$user_id" : "billy_jones_301",
"$user_email" : "[email protected]",
"$name" : "Bill Jones",
"$phone" : "1-415-555-6040",
"$ip" : "54.208.214.78"
}
---
---Ruby
require "sift"
client = Sift::Client.new(:api_key => "YOUR_API_KEY")
# Sample $create_account event
properties = {
# Required for backfilling
# UNIX timestamp in milliseconds as an integer
"$time" => 1456274104243, # Feb 24 2016 00:35:04 UTC
"$user_id" => "billy_jones_301",
"$user_email" => "[email protected]",
"$name" => "Bill Jones",
"$phone" => "1-415-555-6040",
"$ip" => "54.208.214.78"
}
response = client.track("$create_account", properties)
---
---Python
import sift
client = sift.Client(api_key='{apiKey}', account_id='{accountId}')
# Sample $create_account event
properties = {
# Required for backfilling
# UNIX timestamp in milliseconds as an integer
"$time" : 1456274104243, # Feb 24 2016 00:35:04 UTC
"$user_id" : "billy_jones_301",
"$user_email" : "[email protected]",
"$name" : "Bill Jones",
"$phone" : "1-415-555-6040",
"$ip" : "54.208.214.78"
}
response = client.track("$create_account", properties)
---
---PHP
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';
$client = new SiftClient(array('api_key' => 'YOUR_API_KEY'));
// Sample $create_account event
$properties = array(
// Required for backfilling
// UNIX timestamp in milliseconds as an integer
'$time' => 1456274104243, // Feb 24 2016 00:35:04 UTC
'$user_id' => 'billy_jones_301',
'$user_email' => '[email protected]',
'$name' => 'Bill Jones',
'$phone' => '1-415-555-6040',
'$ip' => '54.208.214.78'
);
$response = $client->track('$create_account', $properties);
---
---Java
import com.siftscience.SiftClient;
import com.siftscience.EventRequest;
SiftClient client = new SiftClient("YOUR_API_KEY");
EventRequest request = client.buildRequest(new CreateAccountFieldSet()
.setUserId("billy_jones_301")
.setSessionId("gigtleqddo84l8cm15qe4il")
.setUserEmail("[email protected]")
.setName("Bill Jones")
.setIP("54.208.214.78")
.setTime(1456274104243)
EventResponse response;
try {
response = request.send();
} catch (SiftException e) {
System.out.println(e.getApiErrorMessage());
return;
}
response.isOk(); // true
---
Decision Backfill Guidelines
- After you have backfilled historical data, use the DECISIONS API to send Block category
decisions for previously identified fraudulent user IDs.
- Decision Source should either be MANUAL_REVIEW , or CHARGEBACK depending on
how you identified the user ID as fraudulent. If you don’t know how the user ID was identified
as fraudulent originally, set the source to MANUAL_REVIEW .
---Curl
// Sample Decision Event
// Requires that you configure a Decision with this ID first
// Decisions are configured in the Sift Console
// Decisions should be named based on your real business actions
{
"decision_id" : "ban_user_payment_abuse",
"source" : "MANUAL_REVIEW",
"analyst" : "[email protected]",
"description" : "backfill known fraud users",
"time" : 1456274104243, // Feb 24 2016 00:35:04 UTC
}
---
---Ruby
# Sample Decision Event
# Requires that you configure a Decision with this ID first
# Decisions are configured in the Sift Console
# Decisions should be named based on your real business actions
require "sift"
client = Sift::Client.new(api_key: "{YOUR_API_KEY}", account_id: "accountId")
response = client.apply_decision({
"decision_id" => "ban_user_payment_abuse",
"description" => "backfill known bad users",
"source" =>"MANUAL_REVIEW",
"analyst" => "[email protected]",
"user_id" => "userId",
"time" => 1456274104243, # Feb 24 2016 00:35:04 UTC
})
if (!response.ok?)
puts "Unable to apply decision: " + response.api_error_message
end
---
---Python
# Sample Decision Event
# Requires that you configure a Decision with this ID first
# Decisions are configured in the Sift Console
# Decisions should be named based on your real business actions
import sift
client = sift.Client(api_key='{apiKey}', account_id='{accountId}')
applyDecisionRequest = {
'decision_id' : 'user_looks_ok_payment_abuse',
'source' : 'MANUAL_REVIEW',
'analyst' : '[email protected]',
'description' : 'backfill known bad users',
'time' : 1456274104243, # Feb 24 2016 00:35:04 UTC
}
response = client.apply_user_decision(user_id, applyDecisionRequest)
---
---PHP
// Sample Decision Event
// Requires that you configure a Decision with this ID first
// Decisions are configured in the Sift Console
// Decisions should be named based on your real business actions
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';
$client = new SiftClient(array('api_key' => 'YOUR_API_KEY'));
$options = array(
'analyst' => '[email protected]',
'description' => 'backfill known bad users',
'time' => 1456274104243
);
$response = $client->applyDecisionToUser('userId',
'ban_user_payment_abuse',
'MANUAL_REVIEW',
'time',
$options);
---
---Java
// Sample Decision Event
// Requires that you configure a Decision with this ID first
// Decisions are configured in the Sift Console
// Decisions should be named based on your real business actions
import com.siftscience.SiftClient;
import com.siftscience.DecisionStatusResponse;
import com.siftscience.DecisionStatusRequest;
import com.siftscience.model.DecisionStatusFieldSet;
SiftClient client = new SiftClient("{YOUR_API_KEY}");
ApplyDecisionRequest request;
ApplyDecisionRequest request = client.buildRequest(
new ApplyDecisionFieldSet()
.setAccountId("accountId")
.setUserId("userId")
.setDecisionId("ban_user_payment_abuse")
.setSource(DecisionSource.MANUAL_REVIEW)
.setDescription("backfill known fraud users")
.setAnalyst("[email protected]"))
.setTime(1456274104243);
ApplyDecisionResponse response;
try {
response = request.send();
} catch (SiftException e) {
System.out.println(e.getApiErrorMessage());
}
DecisionLog decisionLog = response.getDecisionLog();
---
Rate Limits
Rate limit errors from Sift show up as HTTP 400 or HTTP 429 responses with
status code 60. The default rate limits are below. If you need higher rate limits, please contact support for assistance on adjusting rate-
limits to the right level.
Rate Limit (requests/second) for Sift API Events API - 180 requests/second (and a per $user_id rate limit of 3 requests/second)
Rate Limit (requests/second) for Sift API Events API with synchronous score calls (return_score or return_workflow_status) - 20 requests/second
Rate Limit (requests/second) for Sift API Decisions API - 40 requests/second
Rate Limit (requests/second) for Sift API Decisions API w/ applying Block category Decisions - 20 requests/second
Rate Limit (requests/second) for Sift API JavaScript Snippet - 1000 requests/second
Rate Limit (requests/second) for Sift API Mobile SDKs - 180 requests/second
Rate Limit (requests/second) for Sift API Score API - 6 requests/second
Installing the JavaScript Snippet
The JavaScript snippet tracks user interactions with your website and collects device information.
Important: only include the JavaScript snippet when the page is accessed externally by a user of
your website. If your internal tools offer a way to simulate logging into a user's account,
for example to investigate a user or place a phone order, it is important that you do not include the JavaScript snippet in those cases so that we do not link your device and
IP address with the user.
Install the JavaScript Snippet
- To minimize download latency, we've hosted these files on Amazon Cloudfront .
To minimize page load delay, this code executes as asynchronously as possible, yielding several times.
- This code will set a long-lived cookie (four years) named __ssid on your domain, also known as a
first-party cookie. We only use this to identify unique visitors. You can optionally set the domain for the
cookie via another JavaScript parameter _setCookieDomain , _sift.push(['_setCookieDomain','subdomain.foo.com' );]
Mobile SDK Overview
The Sift Mobile SDKs collect and send device information and app life cycle events to Sift.
Broadly, the Mobile SDKs are the analogue to the Sift JavaScript snippet.
Just like the JavaScript snippet allows Sift to collect a range of browser properties
and client-side user actions, the Mobile SDKs allow mobile applications to collect
and send device properties and application lifecycle events to Sift. These events are
the foundational data that drives machine learning at Sift.
The Mobile SDKs operate at high performance and are designed to be simple, robust
and easy to integrate. Performance optimizations that reduce end-user impact include
batching, compression, deduplication, archiving, and many other techniques detailed
in this blog post .
iOS SDK – Integrate the iOS SDK into your mobile application.
Android SDK – Integrate the Android SDK into your mobile application.
iOS SDK
Installing the library
The SDK can be installed through either CocoaPods or Carthage .
CocoaPods:
- Add this to your Podfile: pod 'Sift' (this uses the latest version).
- Run pod install .
Carthage:
- Add this to your Cartfile: github "SiftScience/sift-ios" (this uses
the latest version)
- Run carthage update .
Configuration & Set Up:
At a bare minimum, configuring your use of the Sift iOS SDK requires passing in
your account id and beacon key. Your account id is retrievable by your
account's admin in your profile section .
The beacon key is the same key that is used in your Sift JS Snippet, and can be
found in the developer section . Note
in particular that this key is not considered secret; a sophisticated bad
actor could recover this key from your app, or from the JS beacon, and use it
to submit mobile events.
Android SDK
Installing the library
Add the latest version of the Sift SDK to your application's build.gradle file:
---Curl
dependencies {
...
compile 'com.siftscience:sift-android:VERSION'
...
}
---
If your application uses Google Play Services, you will need to configure your build.gradle file to fix its dependency version:
---Curl
compile 'com.google.android.gms:play-services-location:YOUR_GMS_VERSION'
---
You may also need to add the following packagingOptions to the
main android block:
---Curl
android {
...
packagingOptions {
exclude 'META-INF/DEPENDENCIES.txt'
exclude 'META-INF/LICENSE.txt'
exclude 'META-INF/NOTICE.txt'
exclude 'META-INF/NOTICE'
exclude 'META-INF/LICENSE'
exclude 'META-INF/DEPENDENCIES'
exclude 'META-INF/notice.txt'
exclude 'META-INF/license.txt'
exclude 'META-INF/dependencies.txt'
exclude 'META-INF/LGPL2.1'
}
...
}
---
Integration
There are two different integration paths to take for incorporating Sift into your
application.
The first one will be detailed below in the Application Integration section. Follow these instructions if your application flow is primarily based on
Activities.
If your application flow is based on a combination of Activities and Fragments,
please refer to the Custom Integration section.
Application Integration
Add Sift to your Application file
Create an Application file if you haven’t already. Create an internal class that implements
the ActivityLifecycleCallbacks interface and register Sift as shown below:
---Curl
import siftscience.android.Sift;
public class App extends Application {
@Override
public void onCreate() {
super.onCreate();
registerActivityLifecycleCallbacks(new ActivityLifecycleCallbacksHandler());
}
private static final class ActivityLifecycleCallbacksHandler
implements ActivityLifecycleCallbacks {
public void onActivityCreated(Activity activity, Bundle bundle) {
Sift.open(activity, new Sift.Config.Builder()
.withAccountId("YOUR_ACCOUNT_ID")
.withBeaconKey("YOUR_BEACON_KEY")
// Uncomment to disallow location collection
// .withDisallowLocationCollection(true)
.build());
Sift.collect();
}
public void onActivityPaused(Activity activity) {
Sift.pause();
}
public void onActivityResumed(Activity activity) {
Sift.resume(activity);
}
public void onActivityDestroyed(Activity activity) {
Sift.close();
}
}
}
---
Set the user ID
As soon as your application is aware of the user ID, set it on the Sift instance using
the code below. All subsequent events will be associated with that user ID.
---Curl
Sift.setUserId("SOME_USER_ID");
---
If the user logs out of your application or their session ends, you should unset the
user ID:
---Curl
Sift.unsetUserId();
---
Custom Integration
Initialize Sift in your main Activity
Configure the Sift object in the onCreate method of your application's main Activity
(the one that begins the application). If the user ID is known at this point, you
can set it here. Otherwise, you should set it as soon as it is known. In the main Activity,
also override onPause , onResume , and onDestroy as shown:
---Curl
import siftscience.android.Sift;
public class MainActivity extends AppCompatActivity {
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_hello_sift);
Sift.open(this, new Sift.Config.Builder()
.withAccountId("YOUR_ACCOUNT_ID")
.withBeaconKey("YOUR_BEACON_KEY")
// Uncomment to disallow location collection
// .withDisallowLocationCollection(true)
.build());
Sift.collect();
}
@Override
protected void onPause() {
super.onPause();
Sift.pause();
}
@Override
protected void onResume() {
super.onResume();
Sift.resume(this);
}
@Override
protected void onDestroy() {
super.onDestroy();
Sift.close();
}
}
---
Add Sift to your application flow
For each Activity or Fragment that represents a unique page in your application
flow, override onStart , onPause , onResume , and onDestroy :
---Curl
public class OtherActivity extends AppCompatActivity {
@Override
protected void onStart(Bundle savedInstanceState) {
super.onStart();
Sift.open(this);
// For Fragments, use Sift.open(this.getActivity()) instead
Sift.collect();
}
@Override
protected void onPause() {
super.onPause();
Sift.save();
}
@Override
protected void onResume() {
super.onResume();
// For Fragments, use Sift.open(this.getActivity()) instead
Sift.resume(this);
}
@Override
protected void onDestroy() {
super.onDestroy();
Sift.close();
}
}
---
Set the user ID
As soon as your application is aware of the user ID, set it on the Sift instance using
the code below. All subsequent events will be associated with that user ID.
---Curl
Sift.setUserId("SOME_USER_ID");
---
If the user logs out of your application or their session ends, you should unset the
user ID:
---Curl
Sift.unsetUserId();
---
Events API Reference
Use the Events API to record the core actions users take in your application. The more detail
we capture about user behaviors, the better we can distinguish between fraudulent and legitimate events.
We have two types of events:
- Reserved events are events are sent in a standard format, allowing us to do lots of advanced analysis
on the values sent. When possible, model the actions users take on your site or app with reserved events.
- Custom events are events you create to capture actions unique to your application. If there are key
actions most of your users take that are not captured by our reserved events, send these as custom event.
Each event has fields that provide details.
- Each event accepts required, reserved, and custom fields .
- Some fields are of type object or object list .
Events API Endpoint
Sift's Events API accepts event data as a JSON request body via a HTTP POST request at
this endpoint:
https://api.sift.com/v205/events
Every event must contain your $api_key , the event $type , and a $user_id (if this is not
available, you can alternatively provide a $session_id ). Make sure to look at our error codes .
Note
To receive information whether the event is a bot activity, send the parameter fields=bot_detection in the above request url. Bot Management should be enabled to receive bot related information.
$add_item_to_cart
Use $add_item_to_cart to record when a user adds an item to their shopping cart or list.
$type - required · String "$add_item_to_cart"
$api_key - required · String Your Sift REST API key.
$session_id - required if no User ID is provided · String The user's current session ID, used to tie a user's action before and after log in or account creation.
$user_id - send if known · String The user's account ID according to your systems. Note: User IDs are case sensitive .
Find valid $user_id values here .
$item - Item The product item added to cart.
Required subfields are $item_id , $product_title , and $price . The $quantity is specified as a subfield.
$browser - Browser The user agent of the browser that is used to add the item to cart. Represented by the $browser object.
Use this field if the client is a browser. Note: cannot be used in conjunction with $app .
$app - App The details of the app, os, and device that is used to add the item to cart. Represented by the $app object.
Use this field if the client is an app. Note: cannot be used in conjunction with $browser .
$brand_name - String Name of the brand of product or service being purchased.
$site_country - String Country the company is providing service from.
Use ISO-3166 country code.
$site_domain - String Domain being interfaced with.
Use fully qualified domain name .
$user_email - String Email of the user logging in. Note: If the user's email is also their account ID in your
system, set both the $user_id and $user_email fields to their
email address.
$verification_phone_number - String Phone number of the user. This phone number will be used to send One-Time Password (OTP) when required.
The phone number should be in E.164 format including + and a country code.
$keyless_user_id - String The Keyless user ID according to your Keyless SDK.
Find valid $keyless_user_id values here .
$add_promotion
Use $add_promotion to record when a user adds one or more promotions to their account.
$type - required · String "$add_promotion"
$user_id - required · String The user's account ID according to your systems. Note: User IDs are case sensitive .
Find valid $user_id values here .
$promotions - Array of Promotions Contains all promotions that have been newly applied to the referenced user.
$browser - Browser The user agent of the browser that is used to add the promotion. Represented by the $browser object.
Use this field if the client is a browser. Note: cannot be used in conjunction with $app .
$app - App The details of the app, os, and device that is used to add the promotion. Represented by the $app object.
Use this field if the client is an app. Note: cannot be used in conjunction with $browser .
$brand_name - String Name of the brand of product or service being purchased.
$site_country - String Country the company is providing service from.
Use ISO-3166 country code.
$site_domain - String Domain being interfaced with.
Use fully qualified domain name .
$user_email - String Email of the user logging in. Note: If the user's email is also their account ID in your
system, set both the $user_id and $user_email fields to their
email address.
$verification_phone_number - String Phone number of the user. This phone number will be used to send One-Time Password (OTP) when required.
The phone number should be in E.164 format including + and a country code.
$keyless_user_id - String The Keyless user ID according to your Keyless SDK.
Find valid $keyless_user_id values here .
$chargeback
Use $chargeback to capture a chargeback reported on a transaction. This event can be called
multiple times to record changes to the chargeback state.
Note: When you send a $chargeback event you also need to send a Decision event with a source of CHARGEBACK if you want
to prevent the user from making another purchase. It is recommended that you send both $order_id and $transaction_id to
link the chargeback to the associated user and order. However, only one of those fields is required to be sent in the call
(i.e. if $order_id is present, $transaction_id need not be sent and vice versa).
$type - required · String "$chargeback"
$api_key - required · String Your Sift REST API key.
$order_id - required · String The ID for the order that this chargeback is filed against. Note: Optional if the $transaction_id is present. This field is not required if this chargeback
was filed against a transaction with no $order_id .
$transaction_id - required · String The ID for the transaction that this chargeback is filed against. Note: Optional if $order_id is present.
$user_id - String The user's account ID according to your systems. Recommended for better chargeback matching.
Note that user IDs are case sensitive .
Find valid $user_id values here .
$chargeback_state - String The current state of the chargeback. Allowed Values
- "$received" "$accepted" "$disputed" "$won" "$lost"
$chargeback_reason - String This field can be used to capture the reason given. Allowed Values
- "$fraud" "$duplicate" "$product_not_received" "$product_unacceptable" "$other" "$authorization" "$consumer_disputes" "$processing_errors" "$cancel_subscription" "$friendly_fraud" "$ach_return" "$ach_reversal"
$merchant_profile - Merchant Profile The details about the merchant or seller providing the goods or service.
$keyless_user_id - String The Keyless user ID according to your Keyless SDK.
Find valid $keyless_user_id values here .
$ach_return_code - String The code returned, as defined by NACHA, which identifies the reason for return. Standard format begins with 'R' followed by a two digit number.
$content_status
Use $content_status to update the status of content that you’ve already sent to Sift.
If the status is the only thing that’s changing about the content, use this as a convenient way to change it
without having to resend the rest of the content's information. Useful for long lived content such as rentals,
dating profiles, and job postings. Status can also be set using $create_content or $update_content .
$type - required · String "$content_status"
$api_key - required · String Your Sift REST API key.
$user_id - required · String The user's internal account ID. Users without an assigned $user_id will not show up in the console.
Find valid $user_id values here .
$content_id - required · String The unique ID for the piece of content that you’re updating the status of. Note: content
IDs are case sensitive .
$status - required · String The status of the posting. Allowed Values
- $draft The posting has not yet been submitted by the user to go live.