> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.thepennyinc.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.thepennyinc.com/_mcp/server.

# Delete a user

DELETE https://sandbox.api.thepennyinc.com/access/users/{user_id}

Deprovision a business user from the identity provider and soft-delete their Penny user record.

Required permissions: `user:delete`.

Reference: https://docs.thepennyinc.com/banking/api-reference/access/users/delete

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Servers

- `https://sandbox.api.thepennyinc.com` (Sandbox — safe for testing, no real money movement., default)
- `https://live.api.thepennyinc.com` (Live — real businesses, real money movement.)

## Request

### Path parameters

- `user_id` (string, required) — The ID of the user.

### Headers

- `X-Penny-As-Business` (string, optional, nullable) — Act on behalf of another business that has granted you access. Requires the `business:act_as` permission.

## Response

### 200

The deleted user record.

- `access_users_delete_Response_200`
  - BusinessUser: BusinessUser
  - CardholderUser: CardholderUser

## Errors

### 400 Bad Request Error

The request was malformed: a required field is missing or a value has the wrong type or format.

- `type` (string, required) — The name of the exception that was raised.
- `message` (string, required) — A human-readable description of the error.
- `details` (map from string to any, optional, nullable) — Structured context about the error, if any.
- `trace_id` (string, optional, nullable) — Identifier for correlating this error with server-side logs.
- `errors` (list of map from string to any, optional, nullable) — Sub-errors that contributed to this failure, if any.

### 401 Unauthorized Error

Authentication failed.

- `type` (string, required) — The name of the exception that was raised.
- `message` (string, required) — A human-readable description of the error.
- `details` (map from string to any, optional, nullable) — Structured context about the error, if any.
- `trace_id` (string, optional, nullable) — Identifier for correlating this error with server-side logs.
- `errors` (list of map from string to any, optional, nullable) — Sub-errors that contributed to this failure, if any.

### 403 Forbidden Error

The caller does not have permission to perform this action.

- `type` (string, required) — The name of the exception that was raised.
- `message` (string, required) — A human-readable description of the error.
- `details` (map from string to any, optional, nullable) — Structured context about the error, if any.
- `trace_id` (string, optional, nullable) — Identifier for correlating this error with server-side logs.
- `errors` (list of map from string to any, optional, nullable) — Sub-errors that contributed to this failure, if any.

### 404 Not Found Error

The user was not found.

- `type` (string, required) — The name of the exception that was raised.
- `message` (string, required) — A human-readable description of the error.
- `details` (map from string to any, optional, nullable) — Structured context about the error, if any.
- `trace_id` (string, optional, nullable) — Identifier for correlating this error with server-side logs.
- `errors` (list of map from string to any, optional, nullable) — Sub-errors that contributed to this failure, if any.

### 422 Unprocessable Entity Error

The request was well-formed but could not be processed because it breaks a business rule.

- `type` (string, required) — The name of the exception that was raised.
- `message` (string, required) — A human-readable description of the error.
- `details` (map from string to any, optional, nullable) — Structured context about the error, if any.
- `trace_id` (string, optional, nullable) — Identifier for correlating this error with server-side logs.
- `errors` (list of map from string to any, optional, nullable) — Sub-errors that contributed to this failure, if any.

### 429 Too Many Requests Error

Too many requests; retry after the Retry-After header.

- `type` (string, required) — The name of the exception that was raised.
- `message` (string, required) — A human-readable description of the error.
- `details` (map from string to any, optional, nullable) — Structured context about the error, if any.
- `trace_id` (string, optional, nullable) — Identifier for correlating this error with server-side logs.
- `errors` (list of map from string to any, optional, nullable) — Sub-errors that contributed to this failure, if any.

### 500 Internal Server Error

An unexpected error occurred.

- `type` (string, required) — The name of the exception that was raised.
- `message` (string, required) — A human-readable description of the error.
- `details` (map from string to any, optional, nullable) — Structured context about the error, if any.
- `trace_id` (string, optional, nullable) — Identifier for correlating this error with server-side logs.
- `errors` (list of map from string to any, optional, nullable) — Sub-errors that contributed to this failure, if any.

## Types

### BusinessUser

A business user, as shown to clients through the client-facing API.

- `user_id` (string, required) — Penny's unique identifier for this user.
- `version` (integer, required) — A number that increases each time this user's details change. Use it to confirm you are looking at the latest information.
- `version_time` (datetime, required) — The date and time this user's details were last changed.
- `created_time` (datetime, required) — The date and time this user was created.
- `status` (enum, required) — The user's current lifecycle status: 'active', 'deactivated' (cannot sign in), 'suspended' (restricted, typically pending review), or 'deleted'.
  - Allowed values: `active`, `deactivated`, `suspended`, `deleted`
- `active` (boolean, required) — Whether this user's account is currently active.
- `business_id` (string, required) — The business this user belongs to.
- `given_name` (string, required) — The user's given (first) name. Shown as a masked placeholder unless the request explicitly asks to reveal personal information.
- `family_name` (string, required) — The user's family (last) name. Shown as a masked placeholder unless the request explicitly asks to reveal personal information.
- `email` (string, required) — The user's primary email address. Shown as a masked placeholder unless the request explicitly asks to reveal personal information.
- `nickname` (string, optional, nullable) — The user's preferred nickname, if they have set one. Shown as a masked placeholder unless the request explicitly asks to reveal personal information.
- `phone` (string, optional, nullable) — The user's phone number, if one is on file. Shown as a masked placeholder unless the request explicitly asks to reveal personal information.
- `address` (AddressResponse, optional, nullable) — The user's physical address, if one is on file. Street lines and postal code are masked unless the request explicitly asks to reveal personal information; city, state or province, and country remain visible.
- `roles` (list of RolePointerResponse, optional, nullable) — The roles assigned to this user, if any.
- `type` (enum, optional, default: business) — Discriminates the variant of a user account.
  - Allowed values: `business`, `cardholder`
- `permissions` (list of PermissionResponse, optional, nullable) — Permissions granted directly to this user, in addition to any granted through its roles.

### CardholderUser

A cardholder user, as shown to clients through the client-facing API.

- `user_id` (string, required) — Penny's unique identifier for this user.
- `version` (integer, required) — A number that increases each time this user's details change. Use it to confirm you are looking at the latest information.
- `version_time` (datetime, required) — The date and time this user's details were last changed.
- `created_time` (datetime, required) — The date and time this user was created.
- `status` (enum, required) — The user's current lifecycle status: 'active', 'deactivated' (cannot sign in), 'suspended' (restricted, typically pending review), or 'deleted'.
  - Allowed values: `active`, `deactivated`, `suspended`, `deleted`
- `active` (boolean, required) — Whether this user's account is currently active.
- `business_id` (string, required) — The business this user belongs to.
- `given_name` (string, required) — The user's given (first) name. Shown as a masked placeholder unless the request explicitly asks to reveal personal information.
- `family_name` (string, required) — The user's family (last) name. Shown as a masked placeholder unless the request explicitly asks to reveal personal information.
- `email` (string, required) — The user's primary email address. Shown as a masked placeholder unless the request explicitly asks to reveal personal information.
- `cardholder_id` (string, required) — The cardholder record this user is linked to. Access through this user is scoped to that cardholder's own cards and transaction history.
- `nickname` (string, optional, nullable) — The user's preferred nickname, if they have set one. Shown as a masked placeholder unless the request explicitly asks to reveal personal information.
- `phone` (string, optional, nullable) — The user's phone number, if one is on file. Shown as a masked placeholder unless the request explicitly asks to reveal personal information.
- `address` (AddressResponse, optional, nullable) — The user's physical address, if one is on file. Street lines and postal code are masked unless the request explicitly asks to reveal personal information; city, state or province, and country remain visible.
- `roles` (list of RolePointerResponse, optional, nullable) — The roles assigned to this user, if any.
- `type` (enum, optional, default: cardholder) — Discriminates the variant of a user account.
  - Allowed values: `business`, `cardholder`
- `permissions` (list of PermissionResponse, optional, nullable) — Permissions granted directly to this user, in addition to any granted through its roles.

### AddressResponse

External API representation of a physical address. Country is normalized to ISO 3166-1 alpha-2. State/province is normalized to its subdivision code where applicable.

- `line_1` (string, required) — Primary address line.
- `city` (string, required) — City or locality.
- `zip_code` (string, required) — Postal or ZIP code.
- `country` (string, required) — Country in ISO 3166-1 alpha-2 format.
- `line_2` (string, optional, nullable) — Secondary address line.
- `state_or_province` (string, optional, nullable) — State or province code (if applicable).

### RolePointerResponse

A reference to a role assigned to a user or application.

- `role_id` (string, required) — The assigned role's ID: `role_…` for custom roles, `global_role_…` for preset roles.
- `role_type` (enum, required) — Whether this is a custom role owned by your business (`business`) or a preset role Penny provides for every business (`global`).
  - Allowed values: `business`, `global`

### PermissionResponse

A permission specifying the resource and action a user or application can access.

- `resource` (enum, required) — The resource type this permission applies to.
  - Allowed values: `business`, `sub_business`, `business_entity`, `business_defaults`, `user`, `role`, `permission`, `application`, `verification`, `account`, `ledger`, `transaction`, `card`, `cardholder`, `card_product`, `bin`, `spend_control`, `simulation`, `fee`, `program`, `task`, `notification_endpoint`, `notification_event`, `notification_decision_exchange`, `*`
- `action` (enum, required) — The action permitted on the resource.
  - Allowed values: `read`, `list`, `create`, `update`, `delete`, `execute`, `act_as`, `reveal`, `*`

## Examples

**Response**

```json
{
  "active": true,
  "address": {
    "city": "New York",
    "country": "US",
    "line_1": "123 Main Street",
    "line_2": "Suite 200",
    "state_or_province": "NY",
    "zip_code": "10001"
  },
  "business_id": "business_01937b95-484e-75af-8c68-484e5afc68d3",
  "created_time": "2024-01-15T10:30:00Z",
  "email": "jordan.rivera@acme.example",
  "family_name": "Rivera",
  "given_name": "Jordan",
  "nickname": "Jo",
  "permissions": [
    {
      "action": "read",
      "resource": "account"
    }
  ],
  "phone": "+15551234567",
  "roles": [
    {
      "role_id": "role_019372e1-5661-79e1-83cf-56619e13cfc9",
      "role_type": "business"
    }
  ],
  "status": "active",
  "type": "business",
  "user_id": "user_0193757b-7a66-769d-83d4-7a6669d3d498",
  "version": 1,
  "version_time": "2024-01-15T10:30:00Z"
}
```

**SDK Code**

```python
import requests

url = "https://sandbox.api.thepennyinc.com/access/users/user_id"

headers = {
    "X-Penny-As-Business": "business_01a083e2-82ed-7a5c-9d1e-3b6f0c2a4d71",
    "Authorization": "Bearer <token>"
}

response = requests.delete(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://sandbox.api.thepennyinc.com/access/users/user_id';
const options = {
  method: 'DELETE',
  headers: {
    'X-Penny-As-Business': 'business_01a083e2-82ed-7a5c-9d1e-3b6f0c2a4d71',
    Authorization: 'Bearer <token>'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox.api.thepennyinc.com/access/users/user_id"

	req, _ := http.NewRequest("DELETE", url, nil)

	req.Header.Add("X-Penny-As-Business", "business_01a083e2-82ed-7a5c-9d1e-3b6f0c2a4d71")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://sandbox.api.thepennyinc.com/access/users/user_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)
request["X-Penny-As-Business"] = 'business_01a083e2-82ed-7a5c-9d1e-3b6f0c2a4d71'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.delete("https://sandbox.api.thepennyinc.com/access/users/user_id")
  .header("X-Penny-As-Business", "business_01a083e2-82ed-7a5c-9d1e-3b6f0c2a4d71")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('DELETE', 'https://sandbox.api.thepennyinc.com/access/users/user_id', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'X-Penny-As-Business' => 'business_01a083e2-82ed-7a5c-9d1e-3b6f0c2a4d71',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://sandbox.api.thepennyinc.com/access/users/user_id");
var request = new RestRequest(Method.DELETE);
request.AddHeader("X-Penny-As-Business", "business_01a083e2-82ed-7a5c-9d1e-3b6f0c2a4d71");
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "X-Penny-As-Business": "business_01a083e2-82ed-7a5c-9d1e-3b6f0c2a4d71",
  "Authorization": "Bearer <token>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://sandbox.api.thepennyinc.com/access/users/user_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "DELETE"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```