> This page is for BaaS.

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

# Request a hosted PIN reset

POST https://tenant.api.corpx.com/v1/accounts/{accountId}/security/pin/reset-request
Content-Type: application/json

Deprecated on 2026-10-07. Use `POST /v1/people/pin/reset-request`. This
alias keeps the same body and the same response and opens a reset for
the person. The rate limit is per person, shared with the new route.

Returns a CorpX page URL. The operator opens it, completes the facial
check for the CPF on the request and, if the check is approved, chooses
the new PIN on that same page. The integrator never sees or chooses the
PIN. The body does not accept it.

Requires scope `pin.manage` and an existing PIN for that person,
including a PIN invalidated by DELETE. With no PIN, the response is
**409** `pin_reset_not_enrolled`. When hosted reset is not enabled for
the tenant, the response is **403** `feature_disabled`.

Optional `displayMessage` is one line of plain text, at most 240
characters, without HTML, Markdown or links. The page shows that text
as-is. The link expires in 30 minutes. Five requests per operator per
hour; a new request expires earlier open links for the same operator.


Reference: https://docs.api.corpx.com/baas/referencia/security/request-account-transaction-pin-reset

## Authentication

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

## Request

### Path parameters

- `accountId` (string, required) — Account identifier.

### Headers

- `X-Tenant-Id` (string, required) — Tenant context used for authorization and routing.
- `Idempotency-Key` (string, optional) — Optional client-generated idempotency token (recommended for safe retries).

### Body (application/json)

This endpoint expects an object.

- `actingDocument` (string, required) — CPF of the operator whose PIN will be reset.
- `displayMessage` (string, optional) — Optional plain text shown on the CorpX page.

## Response

### 200

Link for the operator. The token is in the URL fragment.

- `resetId` (string, optional)
- `resetUrl` (string, optional) — Open this URL in the operator's browser. The credential is the fragment, not a query parameter.
- `expiresAt` (datetime, optional)

## Errors

### 400 Bad Request Error

`invalid_document`, `invalid_display_message` or `invalid_body` (the body must not include the new PIN).

- `errorCode` (string, required) — Stable machine-readable code. See `ErrorCode` for the known values.
- `message` (string, required) — Human-readable explanation (pt-BR). Presentation only; may change.
- `docs` (string, optional) — Link to this code in the public error catalogue.
- `requestId` (string, optional) — Gateway request id. Quote it when contacting support.
- `details` (map from string to any, optional) — Optional machine-readable context for the specific `errorCode` (for example `kind` on `identity_verification_monthly_limit_exceeded`, `maxBytes` on `payload_too_large`, `attemptsRemaining` on `facetec_attempts_exhausted`). Keys are documented per operation; absent when the code carries no extra context.
- `partner` (ErrorResponsePartner, optional) — Raw error from the settlement bank, when the failure came from it. Diagnostic only.

### 403 Forbidden Error

`feature_disabled` when hosted PIN reset is not enabled for the tenant.

- `errorCode` (string, required) — Stable machine-readable code. See `ErrorCode` for the known values.
- `message` (string, required) — Human-readable explanation (pt-BR). Presentation only; may change.
- `docs` (string, optional) — Link to this code in the public error catalogue.
- `requestId` (string, optional) — Gateway request id. Quote it when contacting support.
- `details` (map from string to any, optional) — Optional machine-readable context for the specific `errorCode` (for example `kind` on `identity_verification_monthly_limit_exceeded`, `maxBytes` on `payload_too_large`, `attemptsRemaining` on `facetec_attempts_exhausted`). Keys are documented per operation; absent when the code carries no extra context.
- `partner` (ErrorResponsePartner, optional) — Raw error from the settlement bank, when the failure came from it. Diagnostic only.

### 409 Conflict Error

`pin_reset_not_enrolled` when this operator has no PIN yet.

- `errorCode` (string, required) — Stable machine-readable code. See `ErrorCode` for the known values.
- `message` (string, required) — Human-readable explanation (pt-BR). Presentation only; may change.
- `docs` (string, optional) — Link to this code in the public error catalogue.
- `requestId` (string, optional) — Gateway request id. Quote it when contacting support.
- `details` (map from string to any, optional) — Optional machine-readable context for the specific `errorCode` (for example `kind` on `identity_verification_monthly_limit_exceeded`, `maxBytes` on `payload_too_large`, `attemptsRemaining` on `facetec_attempts_exhausted`). Keys are documented per operation; absent when the code carries no extra context.
- `partner` (ErrorResponsePartner, optional) — Raw error from the settlement bank, when the failure came from it. Diagnostic only.

### 429 Too Many Requests Error

`pin_reset_rate_limited`. See `Retry-After`.

- `errorCode` (string, required) — Stable machine-readable code. See `ErrorCode` for the known values.
- `message` (string, required) — Human-readable explanation (pt-BR). Presentation only; may change.
- `docs` (string, optional) — Link to this code in the public error catalogue.
- `requestId` (string, optional) — Gateway request id. Quote it when contacting support.
- `details` (map from string to any, optional) — Optional machine-readable context for the specific `errorCode` (for example `kind` on `identity_verification_monthly_limit_exceeded`, `maxBytes` on `payload_too_large`, `attemptsRemaining` on `facetec_attempts_exhausted`). Keys are documented per operation; absent when the code carries no extra context.
- `partner` (ErrorResponsePartner, optional) — Raw error from the settlement bank, when the failure came from it. Diagnostic only.

## Types

### ErrorResponsePartner

Raw error from the settlement bank, when the failure came from it. Diagnostic only.

- `code` (string, optional)
- `message` (string, optional)
- `field` (string, optional) — Field the partner pointed at, when any.

## Examples

**Request**

```json
{
  "actingDocument": "52998224725",
  "displayMessage": "Confirme seu rosto para escolher um PIN novo."
}
```

**Response**

```json
{
  "resetId": "pinrst_8c1f6a2e-4d3b-4b9a-9f0e-1a2b3c4d5e6f",
  "resetUrl": "https://tenant.api.corpx.com/v1/security/pin-reset#example",
  "expiresAt": "2026-09-27T18:00:00Z"
}
```

**SDK Code**

```python Security_requestAccountTransactionPinReset_example
import requests

url = "https://tenant.api.corpx.com/v1/accounts/accountId/security/pin/reset-request"

payload = {
    "actingDocument": "52998224725",
    "displayMessage": "Confirme seu rosto para escolher um PIN novo."
}
headers = {
    "X-Tenant-Id": "X-Tenant-Id",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Security_requestAccountTransactionPinReset_example
const url = 'https://tenant.api.corpx.com/v1/accounts/accountId/security/pin/reset-request';
const options = {
  method: 'POST',
  headers: {
    'X-Tenant-Id': 'X-Tenant-Id',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"actingDocument":"52998224725","displayMessage":"Confirme seu rosto para escolher um PIN novo."}'
};

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

```go Security_requestAccountTransactionPinReset_example
package main

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

func main() {

	url := "https://tenant.api.corpx.com/v1/accounts/accountId/security/pin/reset-request"

	payload := strings.NewReader("{\n  \"actingDocument\": \"52998224725\",\n  \"displayMessage\": \"Confirme seu rosto para escolher um PIN novo.\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Tenant-Id", "X-Tenant-Id")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

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

}
```

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

url = URI("https://tenant.api.corpx.com/v1/accounts/accountId/security/pin/reset-request")

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

request = Net::HTTP::Post.new(url)
request["X-Tenant-Id"] = 'X-Tenant-Id'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"actingDocument\": \"52998224725\",\n  \"displayMessage\": \"Confirme seu rosto para escolher um PIN novo.\"\n}"

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

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

HttpResponse<String> response = Unirest.post("https://tenant.api.corpx.com/v1/accounts/accountId/security/pin/reset-request")
  .header("X-Tenant-Id", "X-Tenant-Id")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"actingDocument\": \"52998224725\",\n  \"displayMessage\": \"Confirme seu rosto para escolher um PIN novo.\"\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://tenant.api.corpx.com/v1/accounts/accountId/security/pin/reset-request', [
  'body' => '{
  "actingDocument": "52998224725",
  "displayMessage": "Confirme seu rosto para escolher um PIN novo."
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
    'X-Tenant-Id' => 'X-Tenant-Id',
  ],
]);

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

```csharp Security_requestAccountTransactionPinReset_example
using RestSharp;

var client = new RestClient("https://tenant.api.corpx.com/v1/accounts/accountId/security/pin/reset-request");
var request = new RestRequest(Method.POST);
request.AddHeader("X-Tenant-Id", "X-Tenant-Id");
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"actingDocument\": \"52998224725\",\n  \"displayMessage\": \"Confirme seu rosto para escolher um PIN novo.\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Security_requestAccountTransactionPinReset_example
import Foundation

let headers = [
  "X-Tenant-Id": "X-Tenant-Id",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "actingDocument": "52998224725",
  "displayMessage": "Confirme seu rosto para escolher um PIN novo."
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://tenant.api.corpx.com/v1/accounts/accountId/security/pin/reset-request")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

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()
```