---
title: "Fix a blocked application"
description: "Send the documents or data a bank asked for with PATCH /v2/accounts/applications/{application_id}, or send the customer to the bank's link."
---
**API version:** v2.

When the bank needs more documents or data, the account stays `pending` with `requires_user_action: true`, and the application is `blocked`. Read what the application asks for, then send all of it in one call.

**A money example.** Ada's 1,200.00 USD cannot arrive until her account is active. The bank asks for a newer proof of address. You upload one PDF with PATCH. The application goes back to `processing`, the bank approves it, and her client can pay.

## Read what is asked

Read the application with [`GET /v2/accounts/applications/{application_id}`](/api-reference/accounts-v2/get-v2-accounts-applications-application-id) (the id is on the account). To find every blocked application of a customer, use `GET /v2/accounts/applications?customer_id=<id>&status=blocked`. Status values are lower case, and a typo returns an empty list.

```bash title="Read the application"
curl --request GET \
     --url https://api.gravv.xyz/v2/accounts/applications/5e7a9c1b-2d4f-4a6b-8c0d-e1f2a3b4c5d6 \
     --header 'Api-Key: <API_KEY>'
```

```json title="Blocked application"
{
  "data": {
    "application_id": "5e7a9c1b-2d4f-4a6b-8c0d-e1f2a3b4c5d6",
    "customer_id": "0b6f3c1e-2a4d-4c8e-9f10-7d2a6b5e4c33",
    "customer_type": "individual",
    "registration_type": "individual",
    "status": "blocked",
    "parties": [{"role": "primary", "status": "declared", "first_name": "Ada", "last_name": "Okafor"}],
    "status_reason": "awaiting_customer_document",
    "required_documents": ["proof_of_address"],
    "requires_user_action": true,
    "created_at": "2026-10-13T09:12:44.512031Z",
    "updated_at": "2026-10-13T09:20:02.118734Z"
  },
  "error": null
}
```

Read `status_reason`, `required_documents`, `required_fields` and `required_action_url`. Do not parse `status_message`, and do not use the older `provisioning` object.

## Send what is asked

| `status_reason` | What to do |
| :-- | :-- |
| `awaiting_customer_document` | PATCH every type in `required_documents`, in one call |
| `awaiting_customer_data` | PATCH every field in `required_fields`, in `metadata` (or `customer` for a change to the customer record) |
| `tos_pending`, `kyc_pending` | Send the customer to `required_action_url`. Nothing to PATCH |

```bash title="Upload the requested document"
curl --request PATCH \
     --url https://api.gravv.xyz/v2/accounts/applications/5e7a9c1b-2d4f-4a6b-8c0d-e1f2a3b4c5d6 \
     --header 'Api-Key: <API_KEY>' \
     --header 'Content-Type: application/json' \
     --data '
{
  "documents": [
    {
      "document_type": "proof_of_address",
      "issuing_country": "GB",
      "filename": "council-tax-2026.pdf",
      "content": "<base64 of the document>"
    }
  ]
}
'
```

To send missing data instead:

```bash title="Send the requested field"
curl --request PATCH \
     --url https://api.gravv.xyz/v2/accounts/applications/5e7a9c1b-2d4f-4a6b-8c0d-e1f2a3b4c5d6 \
     --header 'Api-Key: <API_KEY>' \
     --header 'Content-Type: application/json' \
     --data '
{
  "metadata": {
    "tax_id_number": "123456789"
  }
}
'
```

- PATCH takes no `Idempotency-Key`. After a timeout, read the application before you send again.
- Documents need `filename` here (create does not). Identity documents also need `number` and `expiration_date`.
- Each document is at most 2 MB. In sandbox, keep the files in one request under 500 KB in total. Sandbox refuses requests from about 600 KB with a 413.
- On a business application, an identity document names its person with `party_id`, from `parties[].id` on the application.
- The response is the application. Its status is `processing` when you have sent everything the application asked for. Otherwise it stays `blocked`. The response carries no `status_reason` or `required_*` fields, so read the application again.

Then wait for `applications.accounts.completed`, or read the account until `status` is `active`.

## Errors

| Response | Why | Fix |
| :-- | :-- | :-- |
| 400 `application is not editable` | The application is `processing`, `approved` or `rejected` | PATCH only a `blocked` application (or `manual_review`, for documents) |
| 400 `Tax ID Number was not requested for this application` | You sent something the bank did not ask for | Send only `required_fields` and `required_documents` |
| 400 `document type "articles_of_incorporation" was not requested for this application` | The same, for a document | The same |
| 400 `missing document filename` | No `filename` | Add it |
| 400 `missing document issuing country` | No `issuing_country` | Add it |
| 400 `Party ID is required for a business party document` | A business identity document without `party_id` | Add it |
| 400 `Type is no longer accepted; send Document Type …` | An old document key | Use `document_type` and `document_type_side` |
| 400 `invalid request payload: unknown field "tos_accepted"` | There is no terms field | Send the customer to `required_action_url` |
| 400 `request body must be a JSON object, …` | An array or `null` body | Send an object |
| 404 `Resource not found` | Wrong id, or another environment | Check the id and the key |
| Still `blocked` after the PATCH | You sent only part of what the application asked for | Read the application again and send the rest in one call |
| No response for 7 days to a customer block | The block expires. After three expiries, Gravv reviews the application | Act on each block within 7 days |

## Webhooks

`applications.accounts.blocked` carries `metadata.block_reason`, `metadata.action_url` and `metadata.additional_requirements` (`fields[]`, `documents[]`). Gravv then sends `applications.accounts.completed` or `applications.accounts.failed`.