API Endpoints

Account Management

Create Account

POST /accounts

Create a new account for verification.

Request Body

request.json

JSON

{
"iban": "GB29NWBK60161331926819",
"name": "John Doe"
}

Response

success.json

Success Error

{
"id": "123e4567-e89b-12d3-a456-426614174000",
"iban": "GB29NWBK60161331926819",
"name": "John Doe",
"created_at": "2023-01-01T12:00:00Z",
"updated_at": "2023-01-01T12:00:00Z"
}

{
"error": "Invalid IBAN length",
"code": "VALIDATION_ERROR"
}

Verification

Submit Verification Request

POST /verify

Submit a new verification request.

Request Body

request.json

JSON

{
"name": "John Doe",
"iban": "GB29NWBK60161331926819"
}

Response

success.json

Success

{
"request_id": "123e4567-e89b-12d3-a456-426614174000",
"message": "Verification request submitted successfully"
}

Get Verification Result

GET /verify/{request_id}

Retrieve the result of a verification request.

Response

success.json

Success

{
"response_id": "123e4567-e89b-12d3-a456-426614174000",
"request_id": "123e4567-e89b-12d3-a456-426614174000",
"name_match_code": "EXACT",
"id_match_code": "MATCH",
"matched_name": "John Doe",
"response_timestamp": "2023-01-01T12:00:00Z",
"created_at": "2023-01-01T12:00:00Z"
}

Test Environment Endpoints

The following endpoints are provided for testing purposes only. They allow you to create and manage test accounts to validate your integration with the VoP API. These endpoints should not be used in production environments.

Create Test Account

POST /api/accounts

Creates a test account for API integration testing. This endpoint is not intended for production use.

Request Body

request.json

JSON

{
  "iban": "GB29NWBK60161331926819",
  "name": "John Doe"
}

Response

response.json

JSON

{
  "id": "acc_123456",
  "iban": "GB29NWBK60161331926819",
  "name": "John Doe",
  "created_at": "2024-12-11T17:25:53Z"
}

Examples

Terminal

$ cURL Python JavaScript Rust

curl -X POST https://localhost:8080/api/accounts \
-H "Content-Type: application/json" \
-d '{
  "iban": "GB29NWBK60161331926819",
  "name": "John Doe"
}'

import requests

def create_test_account():
  url = "https://localhost:8080/api/accounts"
  data = {
      "iban": "GB29NWBK60161331926819",
      "name": "John Doe"
  }
  response = requests.post(url, json=data)
  return response.json()

async function createTestAccount() {
  const response = await fetch('https://localhost:8080/api/accounts', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      iban: 'GB29NWBK60161331926819',
      name: 'John Doe'
    })
  });
  return await response.json();
}

async fn create_test_account(client: &Client) -> Result<Account, Error> {
  let account = Account {
      iban: "GB29NWBK60161331926819".to_string(),
      name: "John Doe".to_string(),
  };

  let response = client
      .post("https://localhost:8080/api/accounts")
      .json(&account)
      .send()
      .await?;

  Ok(response.json().await?)
}

Delete Test Account

DELETE /api/accounts/{account_id}

Removes a test account. Use this to clean up after your integration tests.

Response

response.json

JSON

{
  "status": "success",
  "message": "Test account deleted successfully"
}

Example (Python)

delete_account.py

Python

def delete_test_account(account_id):
  url = f"https://localhost:8080/api/accounts/{account_id}"
  response = requests.delete(url)
  return response.json()

Production Endpoints

Verify Account

POST /api/verify

This is the main production endpoint for verifying payee details.

Request Body

request.json

JSON

{
  "iban": "GB29NWBK60161331926819",
  "name": "John Doe"
}

Response

response.json

JSON

{
  "match": true,
  "confidence_score": 0.95,
  "verification_id": "vrf_123456",
  "verified_at": "2024-12-11T17:25:53Z"
}

Example (Python)

verify_account.py

Python

def verify_account(iban, name):
  url = "https://localhost:8080/api/verify"
  data = {
      "iban": iban,
      "name": name
  }
  response = requests.post(url, json=data)
  return response.json()

Important Notes

1. Test vs Production

   • Create and Delete account endpoints are for testing only
   • Use separate API keys for test and production environments
   • Test accounts are automatically cleared after 24 hours

2. Rate Limits

   • Test endpoints: 100 requests per hour
   • Production endpoints: Based on your service agreement

3. Best Practices

   • Always clean up test accounts after integration testing
   • Never use test accounts for real transactions
   • Use meaningful account holder names in test data

Error Responses

All endpoints follow the same error response format. See Error Handling for details.

error.json

JSON

{
  "error": {
      "code": "ERROR_CODE",
      "message": "Human readable error message"
  }
}

Base URL

production.txt

Production Sandbox

https://api.vop.com/v1

https://sandbox.api.vop.com/v1

Account Verification

Verify Single Account

POST /verify

Verify a single account name against provided details.

Request Body

request.json

JSON

{
"accountNumber": "12345678",
"sortCode": "123456",
"accountName": "John Doe"
}

Response

response.json

JSON

{
"match": "FULL",
"suggestedName": "John Doe",
"confidence": 100,
"status": "ACTIVE"
}

Batch Verification

POST /verify/batch

Verify multiple accounts in a single request.

Request Body

request.json

JSON

{
"accounts": [
  {
    "accountNumber": "12345678",
    "sortCode": "123456",
    "accountName": "John Doe"
  },
  {
    "accountNumber": "87654321",
    "sortCode": "654321",
    "accountName": "Jane Smith"
  }
]
}

Account Management

Check Account Status

GET /account/{accountId}/status

Check if an account is active and available for verification.

Account History

GET /account/{accountId}/history

Retrieve verification history for an account.

Get Account

Retrieves details of a specific account.

Endpoint: GET /api/accounts/{id}

Example Requests:

Terminal

$ cURL Python Rust C# Java JavaScript

curl https://localhost:8080/api/accounts/123e4567-e89b-12d3-a456-426614174000

import requests

account_id = "123e4567-e89b-12d3-a456-426614174000"
response = requests.get(f"https://localhost:8080/api/accounts/{account_id}")
print(response.json())

let account_id = "123e4567-e89b-12d3-a456-426614174000";
let response = client.get(format!("https://localhost:8080/api/accounts/{}", account_id))
  .send()
  .await?;
println!("{:#?}", response.json::<serde_json::Value>().await?);

var accountId = "123e4567-e89b-12d3-a456-426614174000";
var response = await client.GetAsync(
  $"https://localhost:8080/api/accounts/{accountId}");
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

String accountId = "123e4567-e89b-12d3-a456-426614174000";
HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create("https://localhost:8080/api/accounts/" + accountId))
  .GET()
  .build();

HttpResponse<String> response = client.send(request,
  HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

async function getAccount(accountId) {
  const response = await fetch('https://localhost:8080/api/accounts/' + accountId);
  return await response.json();
}

Success Response (200 OK):

response.json

JSON

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "iban": "DE89370400440532013000",
  "created_at": "2024-12-11T17:00:00Z",
  "updated_at": "2024-12-11T17:00:00Z"
}

Update Account

Updates an existing account’s details.

Endpoint: PUT /api/accounts/{id}

Request Body:

request.json

JSON

{
  "iban": "DE89370400440532013000"
}

Example Requests:

Terminal

$ cURL Python Rust C# Java

curl -X PUT https://localhost:8080/api/accounts/123e4567-e89b-12d3-a456-426614174000 \
-H "Content-Type: application/json" \
-d '{
  "iban": "DE89370400440532013000"
}'

account_id = "123e4567-e89b-12d3-a456-426614174000"
payload = {
  "iban": "DE89370400440532013000"
}
response = requests.put(
  f"https://localhost:8080/api/accounts/{account_id}",
  json=payload
)
print(response.json())

let account_id = "123e4567-e89b-12d3-a456-426614174000";
let response = client.put(format!("https://localhost:8080/api/accounts/{}", account_id))
  .json(&json!({
      "iban": "DE89370400440532013000"
  }))
  .send()
  .await?;
println!("{:#?}", response.json::<serde_json::Value>().await?);

var accountId = "123e4567-e89b-12d3-a456-426614174000";
var account = new { iban = "DE89370400440532013000" };
var content = new StringContent(
  JsonSerializer.Serialize(account),
  Encoding.UTF8,
  "application/json");

var response = await client.PutAsync(
  $"https://localhost:8080/api/accounts/{accountId}",
  content);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

String accountId = "123e4567-e89b-12d3-a456-426614174000";
String requestBody = "{"
  + "    \"iban\": \"DE89370400440532013000\""
  + "}";

HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create("https://localhost:8080/api/accounts/" + accountId))
  .header("Content-Type", "application/json")
  .PUT(HttpRequest.BodyPublishers.ofString(requestBody))
  .build();

HttpResponse<String> response = client.send(request,
  HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Success Response (200 OK):

response.json

JSON

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "iban": "DE89370400440532013000",
  "created_at": "2024-12-11T17:00:00Z",
  "updated_at": "2024-12-11T17:00:00Z"
}

Delete Account

Deletes an account from the system.

Endpoint: DELETE /api/accounts/{id}

Example Requests:

Terminal

$ cURL Python Rust C# Java

curl -X DELETE https://localhost:8080/api/accounts/123e4567-e89b-12d3-a456-426614174000

account_id = "123e4567-e89b-12d3-a456-426614174000"
response = requests.delete(f"https://localhost:8080/api/accounts/{account_id}")
print(response.status_code)  # Should be 204

let account_id = "123e4567-e89b-12d3-a456-426614174000";
let response = client.delete(format!("https://localhost:8080/api/accounts/{}", account_id))
  .send()
  .await?;
println!("Status: {}", response.status());

var accountId = "123e4567-e89b-12d3-a456-426614174000";
var response = await client.DeleteAsync(
  $"https://localhost:8080/api/accounts/{accountId}");
Console.WriteLine(response.StatusCode);  // Should be 204

String accountId = "123e4567-e89b-12d3-a456-426614174000";
HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create("https://localhost:8080/api/accounts/" + accountId))
  .DELETE()
  .build();

HttpResponse<String> response = client.send(request,
  HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());  // Should be 204

Success Response: 204 No Content

Webhooks

Register Webhook

POST /webhooks

Register a webhook for verification events.

Request Body

request.json

JSON

{
"url": "https://your-domain.com/webhook",
"events": ["verification.success", "verification.failure"],
"secret": "your_webhook_secret"
}

List Webhooks

GET /webhooks

List all registered webhooks.

Analytics

Usage Statistics

GET /analytics/usage

Get API usage statistics.

Match Rate Analytics

GET /analytics/match-rates

Get verification match rate statistics.

Verification

Submit Verification Request

Submits a new verification request.

Endpoint: POST /api/verify

Request Body:

request.json

JSON

{
  "name": "John Doe",
  "iban": "DE89370400440532013000"
}

Example Requests:

Terminal

$ cURL Python JavaScript Rust C# Java

curl -X POST https://localhost:8080/api/verify \
-H "Content-Type: application/json" \
-d '{
  "name": "John Doe",
  "iban": "DE89370400440532013000"
}'

import requests

payload = {
  "name": "John Doe",
  "iban": "DE89370400440532013000"
}
response = requests.post("https://localhost:8080/api/verify", json=payload)
print(response.json())

async function submitVerificationRequest() {
  const response = await fetch('https://localhost:8080/api/verify', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'John Doe',
      iban: 'DE89370400440532013000'
    })
  });
  return await response.json();
}

let response = client.post("https://localhost:8080/api/verify")
  .json(&json!({
      "name": "John Doe",
      "iban": "DE89370400440532013000"
  }))
  .send()
  .await?;
println!("{:#?}", response.json::<serde_json::Value>().await?);

var request = new
{
  name = "John Doe",
  iban = "DE89370400440532013000"
};
var content = new StringContent(
  JsonSerializer.Serialize(request),
  Encoding.UTF8,
  "application/json");

var response = await client.PostAsync(
  "https://localhost:8080/api/verify",
  content);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

String requestBody = "{"
  + "    \"name\": \"John Doe\","
  + "    \"iban\": \"DE89370400440532013000\""
  + "}";

HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create("https://localhost:8080/api/verify"))
  .header("Content-Type", "application/json")
  .POST(HttpRequest.BodyPublishers.ofString(requestBody))
  .build();

HttpResponse<String> response = client.send(request,
  HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Success Response (201 Created):

response.json

JSON

{
  "request_id": "123e4567-e89b-12d3-a456-426614174000",
  "message": "Verification request submitted successfully"
}

Get Verification Result

Retrieves the result of a verification request.

Endpoint: GET /api/verify/{request_id}

Example Requests:

Terminal

$ cURL Python JavaScript Rust C# Java

curl https://localhost:8080/api/verify/123e4567-e89b-12d3-a456-426614174000

import requests

request_id = "123e4567-e89b-12d3-a456-426614174000"
response = requests.get(f"https://localhost:8080/api/verify/{request_id}")
print(response.json())

async function getVerificationResult(requestId) {
  const response = await fetch('https://localhost:8080/api/verify/' + requestId);
  return await response.json();
}

let request_id = "123e4567-e89b-12d3-a456-426614174000";
let response = client.get(format!("https://localhost:8080/api/verify/{}", request_id))
  .send()
  .await?;
println!("{:#?}", response.json::<serde_json::Value>().await?);

var requestId = "123e4567-e89b-12d3-a456-426614174000";
var response = await client.GetAsync(
  $"https://localhost:8080/api/verify/{requestId}");
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

String requestId = "123e4567-e89b-12d3-a456-426614174000";
HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create("https://localhost:8080/api/verify/" + requestId))
  .GET()
  .build();

HttpResponse<String> response = client.send(request,
  HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Success Response (200 OK):

response.json

JSON

{
  "response_id": "987fcdeb-51a2-43fe-ba1e-2075d3c54321",
  "request_id": "123e4567-e89b-12d3-a456-426614174000",
  "name_match_code": "EXACT",
  "id_match_code": "EXACT",
  "matched_name": "John Doe",
  "response_timestamp": "2024-12-11T17:05:00Z",
  "created_at": "2024-12-11T17:05:00Z"
}

Error Responses

All endpoints may return these error responses:

error.json

JSON

{
"error": {
  "code": "ERROR_CODE",
  "message": "Human readable message",
  "details": {
    // Additional error details
  }
}
}

Common error codes:

• INVALID_REQUEST: Request validation failed
• ACCOUNT_NOT_FOUND: Account doesn’t exist
• RATE_LIMIT_EXCEEDED: Too many requests
• INTERNAL_ERROR: Server error

Next Steps

• Learn about Authentication
• Understand Error Handling
• Review API Best Practices