---
title: "Automate submitting referrals"
url: "https://docs.adyen.com/risk-management/automate-submitting-referrals"
source_url: "https://docs.adyen.com/risk-management/automate-submitting-referrals.md"
canonical: "https://docs.adyen.com/risk-management/automate-submitting-referrals"
last_modified: "2020-09-08T22:03:00+02:00"
language: "en"
---

# Automate submitting referrals

[View source](/risk-management/automate-submitting-referrals.md)

You can use our [Referrals API](/risk-management/automate-submitting-referrals/referrals-api-reference) to automate uploading lists of referrals and referral details to [block and trust lists](/risk-management/configure-standard-risk-rules/referral-rules).

By default, block and trust lists are maintained per company account. This means you can provide a setting once and apply it to all merchant accounts under the company account. You can upload referrals using a merchant or a company `accountCode`, but the referral will be applied on the company account.

Using the Referrals API, you can upload referral details such as:

* Email addresses
* IP addresses
* Billing addresses
* Details connected to a payment (PSP) reference

You cannot upload [custom lists](/risk-management/configure-manual-risk/configure-custom-risk-rules#create-custom-list-comparison) using the Referrals API.

For each request with referral details, you can set the `action` to:

* **block** - Block payments associated with this referral detail.
* **trust** - Allow payments associated with this referral detail.
* **delete** - Remove these referral details from your account.

If the request contains referral values that are not valid, the referral will be skipped. Wildcards are not allowed when uploading using the Referrals API, but can be submitted through your [Customer Area](https://ca-test.adyen.com/).

## Requirements

### Required roles

To make requests using the Referrals API, your [API credential](/development-resources/api-credentials) needs the following roles:

* API referral lists management

To check if you have this role:

1. Log in to your [Customer Area](https://ca-test.adyen.com/).
2. Go to **Developers** > **API Credentials**.
3. Select the webservice that you want to use to make the request.
4. Under **Permissions** > **Roles**, search for **API referral lists management**.

If you do not have this role, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other).

### Enable block and trust lists and configure risk scores

To make sure that the referrals trigger:

* Enable the block and trust lists that you want to use in your risk profile configuration.
* Configure a risk score for **block**, and (if applicable) **trust** in case a payment contains a property that matches an item in the list.

## Add email address referrals

The following example demonstrates how to add items to the email address block list: **johnsmith\@example.com** and **jsmith\_example.com**.

In this case, **johnsmith\@example.com** is added and **jsmith\_example.com** is skipped because the input is not valid.

A referral can be skipped if it is already present in the list, or if the input is not valid. You can see which referrals are skipped in the `skippedReferrals` section of the response.

Submit this request to the <https://ca-test.adyen.com/ca/services/ReferralCAService/uploadReferralsStructured> endpoint. For more details, see [Referrals API reference](/risk-management/automate-submitting-referrals/referrals-api-reference).

### Example request to block email addresses

```json
{
   "accountCode":"YOUR_COMPANY_ACCOUNT",
   "referralType":"shopperemail",
   "action":"block",
   "referrals":[
      {
         "referralContainer":{
            "referral":"johnsmith@example.com"
         }
      },
      {
         "referralContainer":{
            "referral":"jsmith_example.com"
         }
      }
   ],
   "reason":"Test behavior"
}
```

### Response

```json
{
   "referralServiceResult":{
      "success":true
   },
   "skippedReferrals":[
      "jsmith_example.com"
   ]
}
```

## Add IP address referrals

The following example demonstrates how to how to add items to the IP address block list: **10.0.0.1/24** and **8.8.8.1/30**.

In this case, **10.0.0.1/24** is added and **8.8.8.1/30** is skipped.

A referral can be skipped if it is already present in the list, or if the input is not valid. You can see which referrals are skipped in the `skippedReferrals` section of the response.

Submit this request to the <https://ca-test.adyen.com/ca/services/ReferralCAService/uploadReferralsStructured> endpoint. For more details, see [Referrals API reference](/risk-management/automate-submitting-referrals/referrals-api-reference).

### Example request to block IP addresses

```json
{
   "accountCode":"YOUR_COMPANY_ACCOUNT",
   "referralType":"shopperip",
   "action":"block",
   "referrals":[
      {
         "referralContainer":{
            "referral":"10.0.0.1\/24"
         }
      },
      {
         "referralContainer":{
            "referral":"8.8.8.1\/30"
         }
      }
   ],
   "reason":"Test behavior"
}
```

### Response

```json
{
   "referralServiceResult":{
      "success":true
   },
   "skippedReferrals":[
      "8.8.8.1\/30"
   ]
}
```

## Add shopper address referrals

The following example demonstrates how to add items to the shopper address block list.

In this case, the first address is added to the block list, and the second address is skipped because the `countryCode` input is not valid.

A referral can be skipped if it is already present in the list, or if the input is not valid. You can see which referrals are skipped in the `skippedReferrals` section of the response.

Submit this request to the <https://ca-test.adyen.com/ca/services/ReferralCAService/uploadReferralsStructured> endpoint. For more details, see [Referrals API reference](/risk-management/automate-submitting-referrals/referrals-api-reference).

### Example request to block shopper addresses

```json
{
   "accountCode":"YOUR_COMPANY_ACCOUNT",
   "referralType":"shopperaddress",
   "action":"block",
   "addressReferrals":[
      {
         "shopperAddress":{
            "street":"Main St",
            "houseNumberOrName":"2",
            "city":"Amsterdam",
            "postalCode":"1000AA",
            "stateOrProvince":"Noord-Holland",
            "countryCode":"NL"
         }
      },
      {
         "shopperAddress":{
            "street":"West lane",
            "houseNumberOrName":"2",
            "city":"London",
            "postalCode":"1100AB",
            "stateOrProvince":"England",
            "countryCode":"UK"
         }
      }
   ],
   "reason":"Test behavior"
}
```

### Response

```json
{
   "referralServiceResult":{
      "success":true
   },
   "skippedReferrals":[
      "West lane,2,London,1100AB,England,UK"
   ]
}
```

## Add referrals based on the payment reference

The following example demonstrates how to add some of the payment details to the respective block lists based on the payment's `pspReference`. In the example below, the card number and shopper email should be blocked for the payment with `pspReference` equal to **9900000000000001**, and the shopper IP should be blocked for the `pspReference` equal to **9900000000000002**.

You can see which referrals are skipped in the `skippedReferrals` section of the response. In this case, the first `pspReference` is skipped. (**9900000000000001,\[cardnumber,shopperemail]**).

A referral can be skipped if it is already present in the list. The API request fails if the payment detail is not present in the payment with the provided `pspReference`.

Submit this request to the <https://ca-test.adyen.com/ca/services/ReferralCAService/uploadReferralsStructured> endpoint. For more details, see [Referrals API reference](/risk-management/automate-submitting-referrals/referrals-api-reference).

### Example request to block payment details

```json
{
   "accountCode":"YOUR_COMPANY_ACCOUNT",
   "referralType":"paymentreference",
   "action":"block",
   "paymentReferenceReferrals":[
      {
         "paymentReferenceReferral":{
            "pspReference":"9900000000000001",
            "referralTypes":[
               "cardnumber",
               "shopperemail"
            ]
         }
      },
      {
         "paymentReferenceReferral":{
            "pspReference":"9900000000000002",
            "referralTypes":[
               "shopperip"
            ]
         }
      }
   ]
}
```

### Response

```json
{
   "referralServiceResult":{
      "success":true
   },
   "skippedReferrals":[
      "9900000000000001,[cardnumber,shopperemail]"
   ]
}
```
