Signifyd API Documentation

Welcome to the Signifyd API. These docs will show you how to authenticate, make requests and view your data that the API will process and create.

The Signifyd API provides a REST interface for creating cases for your orders. Each request you make to the API must be an authenticated call using Basic Authentication. Currently all response to and from the API will be in JSON.

You will be provided with an API token that you can use to make authenticated calls. Be responsible with your key, for it gives full access to your account and data we collect and process.

API Endpoint

https://api.signifyd.com
Summary of Resource URL Patterns
/v2/cases
/v2/cases/{CASE_ID}
/v2/cases/{CASE_ID}/entries
/v2/cases/{CASE_ID}/analysis
/v2/cases/{CASE_ID}/notes
-----
/v2/orders/{ORDER_ID}/case
/v2/orders/{ORDER_ID}/case/entries
/v2/orders/{ORDER_ID}/case/analysis
/v2/orders/{ORDER_ID}/case/notes

Authentication

You authenticate to the Signifyd API by providing your API key in the request. You can find your API key in your account page.

Authentication to the API occurs via HTTP Basic Auth. Provide your API key as the basic auth username. You do not need to provide a password, but you do need to append a colon ":" on the end of your -u token that you make the request with. Do not forget this otherwise your request will return a 401.

Be sure all API calls to Signifyd are made over HTTPS. Otherwise they will fail.

Example Request
$ curl https://api.signifyd.com/v2/cases \ -u JlkfkjOLIFDKJlaksgjjer09389cvn:

curl uses the -u flag to pass basic auth credentials (adding a colon after your API key will prevent it from asking you for a password). A sample test API key has been provided in all the examples on the page, so you can test out any example right away.

Errors

Signifyd uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, a charge failed, etc.), and codes in the 5xx range indicate an error with Signifyd's servers.

Not all errors map cleanly onto HTTP response codes, however. When a request is valid but does not complete successfully, we return a 402 error code.

HTTP Status Code Summary
  • 200 OK - Everything worked as expected.
  • 201 CREATED - The resource requested was successfully created.
  • 400 Bad Request - Often missing a required parameter.
  • 401 Unauthorized - No valid API key provided.
  • 402 Request Failed - Parameters were valid but request failed.
  • 404 Not Found - The requested item doesn't exist.
  • 500, 502, 503, 504 Server errors - something went wrong on Signifyd's end.

Creating a new case

To investigate a transaction, you create a new case object with a new case request.

Arguments

The create case request is organized in a way that allows Signifyd to understand the various actors involved in the transaction. Technically, all fields are optional and you can create a case with as much or as little data as you have. However, we have labeled certain fields as recommended if we believe they are necessary to provide an accurate score.

Read the description of each field carefully. More data is better for scoring, but it is always better to leave a field blank than fill it in with data that does not quite fit the definition.

purchase
object

All items intrinsic to the purchase event itself

browserIPAddressrecommended
string

The IP Address of the browser that was used to make the purchase. This is the IP Address that was used to connect to you site and make the purchase. Do not worry if you think is a proxy address -- Signifyd will figure that out.

orderIdrecommended
string

A string uniquely identifying this order.

createdAtrecommended
string

yyyy-MM-dd'T'HH:mm:ssZ

The date and time when the order was placed.

paymentGateway
string

The gateway that processed the transaction.

currency
string

The currency of the order.

avsResponseCode
string

The response code from the address verification system (AVS)

cvvResponseCode
string

The response code from the card verification value check

orderChannel
string

WEB, PHONE

The method used by the buyer to place the order.

receivedBy
string

If the order was was taken by a customer service or sales agent, his or her name.

totalPricerecommended
double

The total price of the order, including shipping price and taxes.

products
array

The products purchased in the transaction.

itemId
string

" Your unique identifier for the product. This is a string because of hexadecimal identifiers.

itemName
string

The name of the product.

itemUrl
string

The url to the product's page.

itemImage
string

The url to an image of the product.

itemQuantity
int

The number of the items purchased.

itemPrice
int

The price paid for each item (not the aggregate).

itemWeight
int

The weight of each item in grams.

shipments
array

The shipment details for the transaction.

shipper
string

The name of the shipper.

shippingMethod
string

The type of the shipment method used.

shippingPrice
double

The shipping price charged to the customer.

trackingNumber
string

The tracking number for the shipment.

recipient
object

All items related to person or organization receiving the items purchased.

fullNamerecommended
string

The full name of the person receiving the goods. If this item is being shipped, then this field is the person it is being shipping to. Don't assume this name is the same as card.cardHolderName. Only put a value here if the name will actually appear on the shipping label. If this item is digital, then this field will likely be blank.

confirmationEmailrecommended
string

When this purchase was completed, you likely sent a confirmation email or you will be sending a confirmation email to someone once you approve the order. This is the email address to which that confirmation email will be sent.

confirmationPhone
string

The phone number that would call if there was something wrong with this order or the phone number that was supplied with the shipping information.

organization
string

If provided by the buyer, the name of the recipient's company or organization.

deliveryAddressrecommended
object

The address to which the order will be delivered.

streetAddress
string

The street number and street name.

unit
string

The unit or apartment number.

city
string

The city name.

provinceCode
string

The code or abbreviation for the province.

postalCode
string

The postal code.

countryCode
string

The two-letter ISO-3166 country code. If left blank, we will assume US.

latitude
double

The latitude of the address.

longitude
double

The longitude of the address.

card
object

All data related to card and card holder.

cardHolderNamerecommended
string

The full name of the credit card that was charged.

binrecommended
integer

The first six digits of the credit card, the bank identification number, which uniquely identifies the issuer.

last4
string

The last four digits of the card number.

expiryMonth
integer

MM representation of the expiration month of the card.

expiryYear
integer

yyyy representation of the expiration year of the card.

hash
string

A string uniquely identifying this card (do not send the card number itself).

billingAddressrecommended
object

The billing address for the card.

streetAddress
string

The street number and street name.

unit
string

The unit or apartment number.

city
string

The city name.

provinceCode
string

The code or abbreviation for the province.

postalCode
string

The postal code.

countryCode
string

The two-letter ISO-3166 country code. If left blank, we will assume US.

latitude
double

The latitude of the address.

longitude
double

The longitude of the address.

userAccount
object

Commonly, a customer must create an account before placing an order. These data values are details from that account. You should only fill these values in if the customer has an account into which they can login. Leave them blank if this was a one-time transaction with no account.

emailAddressrecommended
string

The primary email address associated with the account.

username
string

The username associated with the account. Please supply this even if it is the same as the email address.

phone
string

The phone number association with the account.

createdDaterecommended
string

yyyy-MM-dd'T'HH:mm:ssZ

The date when the account was created.

accountNumber
string

Your unique identifier for the account.

lastOrderId
string

The unique identifier for the last order placed by this account, prior to the current order.

aggregateOrderCount
integer

The total count of orders placed by this account since it was created.

aggregateOrderDollars
double

The total amount spent by this account since it was created.

lastUpdateDaterecommended
string

yyyy-MM-dd'T'HH:mm:ssZ

The last time a change was made to this account other than an order being placed. Examples include changing email addresses or adding a new credit card.

seller
object

All data related to the merchant that sold the product. If this information is not supplied, we will assume you are the seller.

name
string

The business name of the seller.

domain
string

The domain of the seller.

shipFromAddress
object

The location from which the seller shipped the order.

streetAddress
string

The street number and street name.

unit
string

The unit or apartment number.

city
string

The city name.

provinceCode
string

The code or abbreviation for the province.

postalCode
string

The postal code.

countryCode
string

The two-letter ISO-3166 country code. If left blank, we will assume US.

latitude
double

The latitude of the address.

longitude
double

The longitude of the address.

corporateAddress
object

The corporate headquarters of the seller.

streetAddress
string

The street number and street name.

unit
string

The unit or apartment number.

city
string

The city name.

provinceCode
string

The code or abbreviation for the province.

postalCode
string

The postal code.

countryCode
string

The two-letter ISO-3166 country code. If left blank, we will assume US.

latitude
double

The latitude of the address.

longitude
double

The longitude of the address.

Definition
POST https://api.signifyd.com/v2/cases
Example Request
$ curl https://api.signifyd.com/v2/cases \ -u JlkfkjOLIFDKJlaksgjjer09389cvn: \ -d {POST BODY} \ -H "Content-type: application/json"








Post Body
{ "purchase": { "browserIpAddress": "192.168.1.1", "orderId": "4fj58as", "createdAt": "2013-01-18T17:54:31-05:00", "paymentGateway": "stripe", "currency": "USD", "avsResponseCode": "Y", "cvvResponseCode": "M", "orderChannel" : "PHONE", "receivedBy" : "John Doe", "totalPrice": 74.99, "products": [ { "itemId": "1", "itemName": "Sparkly sandals", "itemUrl": "http://mydomain.com/sparkly-sandals", "itemImage": "http://mydomain.com/images/sparkly-sandals.jpeg", "itemQuantity": 1, "itemPrice": 49.99, "itemWeight": 5 }, { "itemId": "2", "itemName": "Summer tank top", "itemUrl": "http://mydomain.com/summer-tank", "itemImage": "http://mydomain.com/images/summer-tank.jpeg", "itemQuantity": 1, "itemPrice": 19.99, "itemWeight": 2 } ], "shipments": [ { "shipper": "UPS", "shippingMethod": "ground", "shippingPrice": 10.0, "trackingNumber": "3A4U569H1572924642" }, { "shipper": "USPS", "shippingMethod": "international", "shippingPrice": 20.0, "trackingNumber": "9201120200855113889012" } ] }, "recipient": { "fullName": "Bob Smith", "confirmationEmail": "bob@gmail.com", "confirmationPhone": "5047130000", "organization": "Signifyd", "deliveryAddress": { "streetAddress": "123 State Street", "unit": "2A", "city": "Chicago", "provinceCode": "IL", "postalCode": "60622", "countryCode": "US", "latitude": 41.92, "longitude": -87.65 } }, "card": { "cardHolderName": "Robert Smith", "bin": 407441, "last4": "1234", "expiryMonth": 12, "expiryYear": 2015, "hash": "sdfvbkel456hj", "billingAddress": { "streetAddress": null, "unit": "2A", "city": "Chicago", "provinceCode": "IL", "postalCode": "60622", "countryCode": "US", "latitude": 41.92, "longitude": -87.65 } }, "userAccount": { "email": "bob@gmail.com", "username": "bobbo", "phone": "5555551212", "createdDate": "2013-01-18T17:54:31-05:00", "accountNumber": "54321", "lastOrderId": "4321", "aggregateOrderCount": 40, "aggregateOrderDollars": 5000, "lastUpdateDate": "2013-01-18T17:54:31-05:00" }, "seller": { "name": "Amazon", "domain": "amazon.com", "shipFromAddress": { "streetAddress": "1850 Mercer Rd", "unit": null, "city": "Lexington", "provinceCode": "KY", "postalCode": "40511", "countryCode": "US", "latitude": 38.07, "longitude": -84.53 }, "corporateAddress": { "streetAddress": "410 Terry Ave", "unit": "3L", "city": "Seattle", "provinceCode": "WA", "postalCode": "98109", "countryCode": "US", "latitude": 47.60, "longitude": -122.33 } } }

Retrieving a case

Individual cases can be retrieved either by the Signifyd CASE_ID, which was issued upon creation of the case and will always be a positive integer, or by the merchant provided ORDER_ID, the format of which is determined by the merchant. For the example at right we have chosen an ORDER_ID with a mix of both numbers and letters.







Response Attributes

The example retrieved case at right illustrates a typical retrieved case. Definitions below are for fields that will be provided on every case. There may be additional fields returned as well, but these additional fields are not part of the api's contract.

caseId
integer

The Signifyd CASE_ID assigned to this case.

uuid
string

A universally unique id assigned to the case.

orderId
string

The ORDER_ID provided upon case creation.

orderDate
date

yyyy-MM-dd'T'HH:mm:ssZ

The date and time when the order was placed.

orderAmount
double

The total price of the order, including shipping price and taxes.

status
enum (OPEN, PROCESSING, FLAGGED, DISMISSED, HELD)

The current status of the case. OPEN, PROCESSING AND HELD are considered active cases. FLAGGED and DISMISSED cases are considered resolved resolved.

createdAt
date

yyyy-MM-dd'T'HH:mm:ssZ

The date and time when the case was created.

updatedAt
date

yyyy-MM-dd'T'HH:mm:ssZ

The date and time when the case was last updated.

score
double (0.0 - 1000.0)

The key Signifyd metric about the case. Lower values indicate more risk.

headline
string

The headline (aka name) assigned to the case.

URL Pattern - Get by CASE_ID
GET https://api.signifyd.com/v2/cases/{CASE_ID}
Example Request
$ curl https://api.signifyd.com/v2/cases/44 \ -u JlkfkjOLIFDKJlaksgjjer09389cvn: \ -H "Accept: application/json"
URL Pattern - Get by ORDER_ID
GET https://api.signifyd.com/v2/orders/{ORDER_ID}/case
Example Request
$ curl https://api.signifyd.com/v2/orders/4fj58as/case \ -u JlkfkjOLIFDKJlaksgjjer09389cvn: \ -H "Accept: application/json"
Example Response
{ "caseId": 44, "uuid": "d69435f5-4cfb-498b-9a70-18ffb078d06d", "orderId": "4fj58as", "orderDate": "2013-01-18T16:54:31-0600", "orderAmount": 74.99, "status": "OPEN", "createdAt": "2013-09-16T15:10:52-0500", "updatedAt": "2013-09-16T15:10:53-0500", "score": 339.2342233604418, "headline": "Robert Smith" }

Retrieving case entries

In addition to the core case fields, you can retrieve the case's entries, which include information such as the billing address, ip geo-location, and linked social profiles. Retrieval follows the same URL resource pattern as Case retrieval. Simply append /entries to case URL.









Response Attributes

Entries are separated into accounts, organizations , phones, people , networkLocations, and physicalLocations. The groups share five summary fields. In addition to the summary fields, there is an additional details object field which will vary based on the entry type.

uuid
string

A universally unique id for the entry.

entityName
string

A name for the entity generated by Signifyd from the case data.

role
string

The entry's role in the case.

seeder
boolean

True if this data was provided at case creation. False if this data was obtained by Signifyd from an external datasource.

seederUuid
string

The universally unique id for the original piece of data that allowed us to create this entry. For example, if we have an Ip Address and an Ip Geo-location, they will both have the same seederUuid because they were both sourced from the original ip string.

details
object

Additional data about the entity. Varied by the entity type.

Request By Signifyd CASE_ID
GET https://api.signifyd.com/v2/cases/{CASE_ID}/entries
Example Request
$ curl https://api.signifyd.com/v2/cases/44 \ -u JlkfkjOLIFDKJlaksgjjer09389cvn: \ -H "Accept: application/json"
Example Request - By ORDER_ID
GET https://api.signifyd.com/v2/orders/{ORDER_ID}/case/entries
Example Request
$ curl https://api.signifyd.com/v2/orders/4fj58as/case/entries \ -u JlkfkjOLIFDKJlaksgjjer09389cvn: \ -H "Accept: application/json"
Example Response
{ "accounts": [ { "uuid": "b78ab284-3d60-4400-a2bf-5822ca709e71", "entityName": "robertsmith@example.com", "role": "accountEmail", "seeder": true, "seederUuid": "80bff65c-fc7b-4b13-9874-6262cf63a5e1", "details": { "username": "robertsmith", "emailAddress": "robertsmith@example.com", "dateCreated": null, "accountType": "email" } } ], "organizations": [ { "details": { "employeesExact": 40000 }, "entityName": "Comcast Cable", "uuid": "fa728e50-9d44-40aa-adee-cc58c739a6b7", "role": "asnCarrier", "seeder": false, "seederUuid": "4f5d1021-fbe4-44c9-8ac3-438a057c150b" } ], "phones": [ { "details": { "phoneType": "MOBILE", "phoneNumber": "+1 555-555-1212" }, "entityName": "+1 555-555-1212", "uuid": "cc3a52c3-3966-4624-b8f3-80bd6f1b4793", "role": "confirmationPhone", "seeder": true, "seederUuid": "1173671e-cd26-4e3d-84bd-e6e710cf9414" } ], "people": [ { "details": { "familyName": "Smith", "givenName": "Robert", "middleName": null, "age": null }, "entityName": "Robert Smith", "uuid": "ec7b59a7-0043-423e-b015-a6c76a7d9b34", "role": "cardHolder", "seeder": true, "seederUuid": "188e7b48-42e4-4c6b-a824-2d0d3d69e379" } ], "networkLocations": [ { "details": { "anonymizerStatus": null, "ipAddress": "127.0.0.1", "asn": 7922, "connectionType": null, "ipRoutingType": null }, "entityName": "127.0.0.1", "uuid": "8aa4ef3c-f78d-49c2-9762-bb90765914d3", "role": "purchaseIP", "seeder": true, "seederUuid": "4f5d1021-fbe4-44c9-8ac3-438a057c150b" }, { "details": { "tld": "NET", "firstSubdomain": "comcast", "countryTld": null, "genericTld": "NET" }, "entityName": "comcast.net", "uuid": "4cc40dc1-8fcc-4835-8697-85b02de6ea50", "role": "ipDomain", "seeder": false, "seederUuid": "80bff65c-fc7b-4b13-9874-6262cf63a5e1" } ], "physicalLocations": [ { "details": { "cityName": "Fremont", "regionName": "Fremont", "regionAlpha": null, "countryShortName": "United States", "countryFullName": "United States of America", "countryIsoCode": "US", "continentName": "North America", "continentCode": "NA", "latitude": 37.5155, "longitude": -121.8962 }, "entityName": "Fremont, US", "uuid": "209008a8-8c22-46ab-96e1-f8401bfff7de", "role": "ipGeo", "seeder": false, "seederUuid": "4f5d1021-fbe4-44c9-8ac3-438a057c150b" } ] }

Webhooks

Webhooks are messages sent by Signifyd via HTTP POST to a url you configure on your settings page in the Notifications section. Webhook messages are sent when certain events occur in the life of an investigation. Currently the Case Creation, Case Rescore and Case Review events can trigger a webhook.

A webhook topic header is included with each webhook POST message for each event type.




Test Webhook

Once a webhook is configured, a test POST can be sent by selecting the Test button next to the desired webhook. The test webhook message is sent with an HMAC SHA256 verification header (see Webhook Verification below). The header value is the Base64 encoded output of the HMAC SHA256 encoding of the test webhook JSON body, using the secret key ABCDE. A 'cases/test' topic header is also sent with the test POST.

































Webhook Verification

To allow a client to verify a webhook message has in fact come from Signifyd, an 'HTTP_X_SIGNIFYD_HMAC_SHA256' header is included in each webhook POST message. The contents of this header is the Base64 encoded output of the HMAC SHA256 encoding of the JSON body of the message, using the team's API key as the encrption key. To verify the authenticity of the webook message, you should calculate this value yourself and verify it equals the value contained in the header.

See this example code snippet for an idea of how to compute the value in Java.







WEBHOOK TOPIC HEADER VALUES
HTTP_X_SIGNIFYD_WEBHOOK_TOPIC: cases/creation HTTP_X_SIGNIFYD_WEBHOOK_TOPIC: cases/rescore HTTP_X_SIGNIFYD_WEBHOOK_TOPIC: cases/review
HMAC SHA256 Header for Test Webhook (Key: ABCDE)
HTTP_X_SIGNIFYD_HMAC_SHA256: sdGXFLSPZi5hTt8ZCVR9FeNMrsfmOblEIkpV2cCVLxM==
TOPIC HEADER FOR TEST WEBHOOK
HTTP_X_SIGNIFYD_WEBHOOK_TOPIC: cases/test
Webhook Test Post
{ "analysisUrl": "https://signifyd.com/v2/cases/1/analysis", "entriesUrl": "https://signifyd.com/v2/cases/1/entries", "notesUrl": "https://signifyd.com/v2/cases/1/notes", "orderUrl": "https://signifyd.com/v2/cases/1/order", "status": "DISMISSED", "uuid": "709b9107-eda0-4cdd-bdac-a82f51a8a3f3", "headline": "John Smith", "reviewDisposition": null, "associatedTeam": { "teamName": "anyTeam", "teamId": 26, "getAutoDismiss": true, "getTeamDismissalDays": 2 }, "orderId": "19418", "orderDate": "2013-06-17T06:20:47-0700", "orderAmount": 365.99, "createdAt": "2013-11-05T14:23:26-0800", "updatedAt": "2013-11-05T14:23:26-0800", "adjustedScore": 262.6666666666667, "investigationId": 1, "score": 262.6666666666667, "caseId": 1 }
EXAMPLE HMAC SHA256 Header
HTTP_X_SIGNIFYD_HMAC_SHA256: TD71z9/chMS8WhruVGZWzVBCQ0xBN+S+7S6tEPf5AEc=

Get in Touch

Contact us with any questions, and we'll respond within 24 hours.

×

Login

Enter your login info:

×