---
title: "Referrals API reference"
url: "https://docs.adyen.com/risk-management/automate-submitting-referrals/referrals-api-reference"
source_url: "https://docs.adyen.com/risk-management/automate-submitting-referrals/referrals-api-reference.md"
canonical: "https://docs.adyen.com/risk-management/automate-submitting-referrals/referrals-api-reference"
last_modified: "2020-08-25T14:03:00+02:00"
language: "en"
---

# Referrals API reference

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

To communicate with our API, you submit HTTP requests to applicable endpoints.

These endpoints differ for test and live accounts, and also depend on the data format (SOAP, JSON, or FORM) you use to submit data to the Adyen payments platform.

This document lists all endpoints available for you to integrate with the test platform and run QA checks.

Requests to the Referrals API are rate limited to 10 referrals per request, and 10 requests per minute.

## Endpoints

### SOAP

For the SOAP messaging protocol, all test payment requests must be posted to the following endpoint:

* <https://ca-test.adyen.com/ca/services/ReferralCAService>

The data schema for corresponding SOAP objects is available at:

* <https://ca-test.adyen.com/ca/services/ReferralCAService?wsdl>

### JSON and FORM

This is an overview of the test URL endpoints to communicate with our API using JSON or FORM (key-value parameters passed in an HTTP POST URL).

|      |                                                                                     |
| ---- | ----------------------------------------------------------------------------------- |
| POST | <https://ca-test.adyen.com/ca/services/ReferralCAService/uploadReferralsStructured> |

After you are ready to go live, you should switch to either generic or custom live endpoints. For more information, refer to [Live endpoints](/development-resources/live-endpoints).

## Create upload referrals request

Upload one or more items to a block or trust list, or delete items from a list.

For the request to be successful:

* Make sure that the referral values match the `referralType` in the request.
* You can upload one type of referral per request, and one type of action (**block**, **trust** or **delete**).
* Depending on the type of referral you upload, include the correct object to specify the referral details: `referralContainer`, `addressReferrals`, or `paymentReferenceReferrals`.

For example requests, see [Automate submitting referrals](/risk-management/automate-submitting-referrals).

| Field                       | Type                                                           | Required                                                                                    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| --------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |   |
| `accountCode`               | String                                                         | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The name of the company account for which you want to upload referrals.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `action`                    | String                                                         | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The action type. Possible values:- block
- trust
- delete                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `addressReferrals`          | Array of [shopperAddress](#shopperaddress)                     |                                                                                             | Required when you want to manage a shopper address referral list. This field replaces `referralContainer`, and must be used in combination with the referral type **shopperaddress**. Use this object to add addresses to the referral list.                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `paymentReferenceReferrals` | Array of [paymentReferenceReferral](#paymentreferencereferral) |                                                                                             | Required when you want to upload referrals connected to a payment reference. This field replaces `referralContainer`, and must be used in combination with the referral type **paymentreference**. Use this object to extract a set of specified referral types from the payment based on the provided PSP reference.                                                                                                                                                                                                                                                                                                                                                 |
| `reason`                    | String                                                         | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Reason of the request. For the referral type `paymentreference`, the `reason` field is automatically generated to include the PSP reference, and you cannot specify a free-text reason.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `referralType`              | String                                                         | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The type of a referral included in the request. Possible values:- cardnumber
- emaildomain
- ibannumber
- ipcountry
- issuerreference
- issuingcountry
- paymentreference When you use this referral type, you must include [paymentReferenceReferral](#paymentreferencereferral) details in the request.
- persistentcookie
- phonenumber
- pmowner This is the shopper name referral list.
- shopperaddress When you use this referral type, you must include [shopperAddress](#shopperaddress) details in the request.
- shopperemail
- shopperip
- shopperreference
- txvariantshopperreference This is the PayPal Payer ID referral list.
- socialsecuritynumber |
| `referrals`                 | Array of [referralContainer](#referralcontainer)               | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A container object for the referral type you want to upload. Not applicable for `addressReferrals` or `paymentReferenceReferrals`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

## referralContainer object

Use this object to specify which items to upload to a block or trust list, or remove items from a list.

For the request to be successful:

* Use the `referralContainer` object.
* Make sure that the referral items that you submit match the `referralType` in the request.
* You can upload one type of referral per request, and one type of action (**block**, **trust** or **delete**).

For example requests, see [Add email address referrals](/risk-management/automate-submitting-referrals#block-referral-emails) and [Add IP address referrals](/risk-management/automate-submitting-referrals#block-referral-ip-addresses).

| Field      | Type   | Required                                                                                    | Description                                                                                                                                                                                                           |
| ---------- | ------ | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `referral` | String | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The value for the referral item that you want to upload. Must match the `referralType`. Examples:- `johnsmith@example.com` (for referrals of type **shopperemail**)
- `8.8.8.8` (for referrals of type **shopperip**) |

## paymentReferenceReferrals object

Use this object to specify which referrals to upload to or remove from the applicable block and trust list based on a provided PSP reference of a payment.

For the request to be successful:

* Use the `paymentReferenceReferrals` object instead of `referralContainer`.
* Make sure that the referral types that you specify are present in the payment.

For an example request, see [Add referrals based on the payment reference](/risk-management/automate-submitting-referrals#block-referrals-by-the-payment-reference).

| Field           | Type            | Required                                                                                    | Description                                                                                                                                                                                                                                                                                                                                             |
| --------------- | --------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pspReference`  | String          | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The PSP reference of the payment for which you want to upload referrals.                                                                                                                                                                                                                                                                                |
| `referralTypes` | Array of String | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The referral types that you want to upload to the applicable block and trust list. The payment property must be included in the payment. If the payment does not include the property, the request will fail. Possible values:- cardnumber
- ibannumber
- pmowner This is the shopper name referral list.
- shopperemail
- shopperip
- shopperreference |

## shopperAddress object

Use this object to specify one or more shopper addresses to upload to the shopper address block or trust list, or remove addresses from the list.

For the request to be successful:

* Use the `addressReferrals` object instead of `referralContainer`.

For an example request, see [Add shopper address referrals](/risk-management/automate-submitting-referrals#block-referral-addresses).

| Field               | Type   | Required                                                                                    | Description                                                                                                                                               |
| ------------------- | ------ | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `street`            | String | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The name of the street.                                                                                                                                   |
| `houseNumberOrName` | String | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The number or name of the house.                                                                                                                          |
| `city`              | String | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The name of the city.                                                                                                                                     |
| `postalCode`        | String | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A maximum of five digits for an address in the US, or a maximum of ten characters for an address in all other countries/regions.                          |
| `countryCode`       | String | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The country code. Format: the two-letter [ISO-3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code. Exception: **QZ** (Kosovo). |
| `stateOrProvince`   | String |                                                                                             | Required for the US and Canada. The two-character ISO 3166-2 state or province code. For example, **CA** in the US or **ON** in Canada.                   |
