Developer Platform
View as Markdown Open in ChatGPT Open in Claude

Fix a blocked application

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} (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.

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

{
  "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 
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:

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.

Was this page helpful?