sift-java

The official Java bindings for the latest version (v205) of the Sift API.

Requirements

Java 1.7 or later.

Setup

Maven

<dependency>
<groupId>com.siftscience</groupId>
<artifactId>sift-java</artifactId>
<version>3.22.0</version>
</dependency>

Gradle

dependencies {
compile 'com.siftscience:sift-java:3.22.0'
}

Other

Download and install the latest Jar from the releases page. This zip file contains the Jar files of the libraries that sift-java depends on (Gson, OkHttp, and Okio), so those will have to be installed also.

You may also generate the distribution Zip from source.

$ git clone git@github.com:SiftScience/sift-java.git
$ cd sift-java
$ ./gradlew distZip # Zip file saved to ./build/distributions/

How To Use

Create a SiftClient object with your API key and account id. SiftClient is thread-safe and can be used to access all supported APIs.

SiftClientclient = newSiftClient("YOUR_API_KEY", "YOUR_ACCOUNT_ID");

Send Events

API Docs

All request types can be built using the overloaded client.buildRequest. Here's an example for the $create_order event type.

// Build the request object.EventRequestcreateOrderRequest = client.buildRequest(newCreateOrderFieldSet()
// Required fields ($api_key and $type) are automatically filled in by the library,// although $api_key can be overridden on a per-request basis.
.setUserId("bill_jones")
// Supported fields.
.setOrderId("ORDER-28168441")
.setUserEmail("bjones@altavista.com")
.setCurrencyCode("USD")
.setAmount(115940000L) // $115.94
.setBillingAddress(newAddress()
.setName("Bill Jones")
.setPhone("1-415-555-6041")
.setAddress1("2100 Main Street")
.setAddress2("Apt 3B")
.setCity("New London")
.setRegion("New Hampshire")
.setCountry("US")
.setZipCode("03257"))
.setExpeditedShipping(true)
// More supported fields documented at:// https://sift.com/developers/docs/java/events-api/reserved-events/create-order// Custom fields.
.setCustomField("digital_wallet", "apple_pay")
.setCustomField("coupon_code", "dollarMadness")
.setCustomField("shipping_choice", "FedEx Ground Courier")
.setCustomField("is_first_time_buyer", false)
);
// Send the request.EventResponseresponse;
try {
response = createOrderRequest.send();
} catch (SiftExceptione) {
SiftResponseerrorResponse = e.getSiftResponse();
// ... handle InvalidRequestException(4xx) and/or ServerException(5xx) subtypes.
}
// Inspect the response.response.isOk(); // trueresponse.getApiErrorMessage(); // "OK"response.getApiStatus(); // 0response.getHttpStatusCode(); // 200EventResponseBodybody = response.getBody();

Get Scores

Synchronous Scoring

API Docs

To get a score in the response body of an event request, build your event request as usual and then augment the request with a list of abuse types for which you would like scores returned using EventRequest#withScores.

Here's how the $create_order example above can be altered to respond with payment_abuse and promotion_abuse scores.

// Add a list of requested abuse types as an extra parameter.// The first parameter is the same as in the first example.EventRequestcreateOrderRequest = client.buildRequest(createOrderFieldSet)
.withScores("payment_abuse", "promotion_abuse");
// Send the request. May throw a SiftException.EventResponseresponse = createOrderRequest.send();
// Inspect scores.AbuseScorepaymentAbuseScore = response.getAbuseScore("payment_abuse");

You may also invoke the withScores method with no arguments to return scores for all abuse types.

EventRequest objects can also be modified to return a Score Percentiles using the EventRequest#withScorePercentiles method.

// Build the ScoreRequest with score percentilesEventRequestcreateOrderRequest = client.buildRequest(createOrderFieldSet)
.withScores("payment_abuse")
.withScorePercentiles();
// Send the request. May throw a SiftException.ScoreResponseresponse = request.send();
// Inspect score percentiles.Map<String, Double> percentiles = siftResponse.getAbuseScore("payment_abuse").getPercentiles();

Score API

API Docs

Scores may also be requested separately from incoming event requests. Provide a ScoreFieldSet containing a list of abuse types client.buildRequest to send a request to the Scores API.

// Build the ScoreRequest with a list of abuse types.ScoreRequestrequest = client.buildRequest(newScoreFieldSet()
.setUserId("bill_jones")
.setAbuseTypes(Arrays.asList("payment_abuse", "promotion_abuse"))
);
// Send the request. May throw a SiftException.ScoreResponseresponse = request.send();
// Inspect scores.AbuseScorepaymentAbuseScore = response.getAbuseScore("payment_abuse");

Labels

Label User

API Docs

To send a label, build a request using a LabelFieldSet;

LabelRequestrequest = client.buildRequest(newLabelFieldSet()
.setUserId("bill_jones")
.setIsBad(true)
.setAbuseType("payment_abuse")
.setDescription("The user was testing cards repeatedly for a valid card")
.setSource("manual review")
.setAnalyst("someone@your-site.com")
);

Unlabel User

API Docs

Similarly, use an UnlabelFieldSet to unlabel a user.

UnlabelRequestrequest = client.buildRequest(newUnlabelFieldSet()
.setUserId("billy_jones_301")
// Optional abuse type to unlabel for. Omit to unlabel for all abuse types.
.setAbuseType("payment_abuse"));

Workflow Status

Synchronous Workflow Statuses

API Docs

Similarly to the Scores API, EventRequest objects can also be modified to return a Workflow Status using the EventRequest#withWorkflowStatus method.

EventRequestcreateOrderRequest = client.buildRequest(createOrderFieldSet)
.withWorkflowStatus();

Workflow Status API

API Docs

To query the Workflow Status API, create a request with a WorkflowStatusFieldSet.

WorkflowStatusRequestrequest = client.buildRequest(newWorkflowStatusFieldSet()
.setWorkflowRunId("someid"));

Apply Decision API

API Docs

To apply a decision to a user, create a request with userId and ApplyDecisionFieldSet.

ApplyDecisionRequestrequest = client.buildRequest(
newApplyDecisionFieldSet()
.setUserId("a_user_id")
.setDecisionId("decision_id")
.setSource(DecisionSource.AUTOMATED_RULE)
.setDescription("description of decision applied")
);

To apply a decision to an order, create a request with userId, orderId, and ApplyDecisionFieldSet.

ApplyDecisionRequestrequest = client.buildRequest(
newApplyDecisionFieldSet()
.setUserId("a_user_id")
.setOrderId("a_order_id")
.setDecisionId("decision_id")
.setSource(DecisionSource.MANUAL_REVIEW)
.setAnalyst("analyst@example.com") .setDescription("description of decision applied")
);

To apply a decision to a session, create a request with userId, sessionId, and ApplyDecisionFieldSet.

ApplyDecisionRequestrequest = client.buildRequest(
newApplyDecisionFieldSet()
.setUserId("a_user_id")
.setSessionId("a_session_id")
.setDecisionId("decision_id")
.setSource(DecisionSource.MANUAL_REVIEW)
.setAnalyst("analyst@example.com")
.setDescription("description of decision applied")
);

To apply a decision to a piece of content, create a request with userId, contentId, and ApplyDecisionFieldSet.

ApplyDecisionRequestrequest = client.buildRequest(
newApplyDecisionFieldSet()
.setUserId("a_user_id")
.setContentId("a_content_id")
.setDecisionId("decision_id")
.setSource(DecisionSource.MANUAL_REVIEW)
.setAnalyst("analyst@example.com")
.setDescription("description of decision applied")
);

Get decisions

API Docs

To retrieve available decisions, build a request with a GetDecisionsFieldSet.

GetDecisionsRequestrequest = client.buildRequest(newGetDecisionsFieldSet()
.setAbuseTypes(ImmutableList.of(AbuseType.PAYMENT_ABUSE, AbuseType.CONTENT_ABUSE)));

Additionally, this field set supports filtering on results by entity and abuse type(s).

GetDecisionsRequestrequest = client.buildRequest(newGetDecisionsFieldSet())
.setEntityType(EntityType.ORDER)
.setAbuseTypes(ImmutableList.of(AbuseType.PAYMENT_ABUSE, AbuseType.CONTENT_ABUSE))

Pagination is also supported, with offset by index (from) and limit (limit). The default limit is to return up to 100 results. The default offset value from is 0.

GetDecisionsRequestrequest = client.buildRequest(newGetDecisionsFieldSet())
.setFrom(15)
.setLimit(10); 

A request will return a paginated response if the number of query results are greater than the set limit. In these cases, the response object will contain a url (nextRef) at which the next set of results may be retrieved. Build a new request from this nextRef, as follows:

GetDecisionsResponseresponse = request.send();
StringnextRef = response.getBody().getNextRef();
GetDecisionsRequestnextRequest = client.buildRequest(GetDecisionsFieldSet.fromNextRef(nextRef));

Decision Status API

API Docs

To query the Decision Status API, create a request with a DecisionStatusFieldSet.

DecisionStatusRequestrequest = client.buildRequest(newDecisionStatusFieldSet()
.setEntity(DecisionStatusFieldSet.ENTITY_ORDERS) // or ENTITY_USERS
.setEntityId("someid"));

To query the Decision Status API for a Session, create a request with a DecisionStatusFieldSet, including a user id.

DecisionStatusRequestrequest = client.buildRequest(newDecisionStatusFieldSet()
.setEntity(DecisionStatusFieldSet.ENTITY_SESSIONS)
.setUserId("a_user_id")
.setEntityId("a_session_id"));

To query the Decision Status API for Content, create a request with a DecisionStatusFieldSet, including a user id.

DecisionStatusRequestrequest = client.buildRequest(newDecisionStatusFieldSet()
.setEntity(DecisionStatusFieldSet.ENTITY_CONTENT)
.setUserId("a_user_id")
.setEntityId("a_content_id"));