---
title: "Create blocks by reference"
method: POST
path: "/blocks/block_by_ref"
tags: ["Block"]
---

# Create blocks by reference

`POST /blocks/block_by_ref`

## Request

- Base URL: `https://api.gocardless.com`
- URL: `https://api.gocardless.com/blocks/block_by_ref`
- Auth: HTTP bearer

Creates new blocks for a given reference. By default blocks will be active.
Returns 201 if at least one block was created. Returns 200 if there were no new
blocks created.

## Headers

- `GoCardless-Version` string, required

## Request body

- object
  - `blocks` object
    - `reference_type` 'customer' | 'mandate': Type of entity we will seek to get the associated emails and bank accounts to create blocks from. This can currently be one of 'customer' or 'mandate'.
    - `reference_value` string: This field is a reference to the entity you wish to block based on its emails and bank accounts. This may be the ID of a customer or a mandate. This means in order to block by reference the entity must have already been created as a resource.
    - `reason_type` 'identity_fraud' | 'no_intent_to_pay' | 'unfair_chargeback' | 'other': The reason you wish to block this payer, can currently be one of 'identity_fraud', 'no_intent_to_pay', 'unfair_chargeback'. If the reason isn't captured by one of the above then 'other' can be selected but you must provide a reason description.
    - `reason_description` string, nullable: This field is required if the reason_type is other. It should be a description of the reason for why you wish to block this payer and why it does not align with the given reason_types. This is intended to help us improve our knowledge of types of fraud.
    - `active` boolean, nullable: Shows if the block is active or disabled. Only active blocks will be used when deciding if a mandate should be blocked.

## Response `201`

Resource created successfully

- BlockMultiResourceResponse
  - `blocks` Block[]
    - `id` string: Unique identifier, beginning with "BLC".
    - `block_type` 'email' | 'email_domain' | 'bank_account' | 'bank_name': Type of entity we will seek to match against when blocking the mandate. This can currently be one of 'email', 'email_domain', 'bank_account', or 'bank_name'.
    - `reason_type` 'identity_fraud' | 'no_intent_to_pay' | 'unfair_chargeback' | 'other': The reason you wish to block this payer, can currently be one of 'identity_fraud', 'no_intent_to_pay', 'unfair_chargeback'. If the reason isn't captured by one of the above then 'other' can be selected but you must provide a reason description.
    - `reason_description` string, nullable: This field is required if the reason_type is other. It should be a description of the reason for why you wish to block this payer and why it does not align with the given reason_types. This is intended to help us improve our knowledge of types of fraud.
    - `resource_reference` string: This field is a reference to the value you wish to block. This may be the raw value (in the case of emails or email domains) or the ID of the resource (in the case of bank accounts and bank names). This means in order to block a specific bank account (even if you wish to block generically by name) it must already have been created as a resource.
    - `active` boolean, nullable: Shows if the block is active or disabled. Only active blocks will be used when deciding if a mandate should be blocked.
    - `created_at` string, date-time: Fixed [timestamp](https://docs.gocardless.com/docs/api-reference/data-conventions#dates-and-times), recording when this resource was created.
    - `updated_at` string, date-time: Fixed [timestamp](https://docs.gocardless.com/docs/api-reference/data-conventions#dates-and-times), recording when this resource was updated.
  - `meta` BlockPaginationMeta: Cursor pagination information
    - `limit` integer, required
    - `cursors` object, required
      - `before` string, nullable, required: Cursor pointing to the end of the desired set.
      - `after` string, nullable, required: Cursor pointing to the start of the desired set.

## Other responses

- `400`: Bad Request
- `401`: Unauthorised
- `404`: Not found
- `422`: Validation Error
- `500`: Internal Error

---

[API](https://skmtc.dev/gocardless/apis/gocardless-api.md) - [All operations](https://skmtc.dev/gocardless/apis/gocardless-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gocardless/apis/gocardless-api/revisions/4dd3dae45364?raw)