> This page is for Internet banking (beta).

> 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 for a person

POST https://client.api.corpx.com/v1/people/pin/reset-request
Content-Type: application/json

Returns a CorpX page URL. The person opens it, completes the facial
check and, if it is approved, chooses the new PIN on that page. The
body does not accept the PIN. Requires scope `pin.manage`, the
`pin_hosted_reset` feature and an existing PIN — a PIN invalidated by
DELETE still counts. Five requests per person per hour, across
accounts. The per-account alias counts toward the same limit.


Reference: https://docs.api.corpx.com/ib/referencia/people/request-person-transaction-pin-reset

## Authentication

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

## Request

### Headers

- `X-Tenant-Id` (string, required) — Tenant context used for authorization and routing.
- `X-Acting-Document` (string, required) — CPF of the person, 11 digits.
- `Idempotency-Key` (string, optional) — Optional client-generated idempotency token (recommended for safe retries).
- `X-Request-Timestamp` (string, required) — Unix seconds. Required on the signed host; tolerance is 300s either way (`403 request_timestamp_skew`).
- `X-Content-SHA256` (string, required) — Lowercase hex SHA-256 of the body. An empty body hashes the empty string, so the header is always present. Mismatch returns `400 body_hash_mismatch`.
- `X-Request-Signature` (string, required) — Detached JWS (`<protected>..<signature>`, ES256 or PS256) over `METHOD\nPATH?QUERY\nTIMESTAMP\nIDEMPOTENCY_KEY_OR_EMPTY\nX_CONTENT_SHA256`.

### Body (application/json)

This endpoint expects an object.

- `displayMessage` (string, optional)

## Response

### 200

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

- `resetId` (string, optional)
- `resetUrl` (string, optional)
- `expiresAt` (datetime, optional)

## Errors

### 403 Forbidden Error

`feature_disabled` when hosted PIN reset is not enabled.

- `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 person 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
{
  "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-10-07T18:30:00Z"
}
```

**SDK Code**

```python People_requestPersonTransactionPinReset_example
import requests

url = "https://client.api.corpx.com/v1/people/pin/reset-request"

payload = { "displayMessage": "Confirme seu rosto para escolher um PIN novo." }
headers = {
    "X-Acting-Document": "X-Acting-Document",
    "X-Content-SHA256": "X-Content-SHA256",
    "X-Request-Signature": "X-Request-Signature",
    "X-Request-Timestamp": "X-Request-Timestamp",
    "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 People_requestPersonTransactionPinReset_example
const url = 'https://client.api.corpx.com/v1/people/pin/reset-request';
const options = {
  method: 'POST',
  headers: {
    'X-Acting-Document': 'X-Acting-Document',
    'X-Content-SHA256': 'X-Content-SHA256',
    'X-Request-Signature': 'X-Request-Signature',
    'X-Request-Timestamp': 'X-Request-Timestamp',
    'X-Tenant-Id': 'X-Tenant-Id',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"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 People_requestPersonTransactionPinReset_example
package main

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

func main() {

	url := "https://client.api.corpx.com/v1/people/pin/reset-request"

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

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

	req.Header.Add("X-Acting-Document", "X-Acting-Document")
	req.Header.Add("X-Content-SHA256", "X-Content-SHA256")
	req.Header.Add("X-Request-Signature", "X-Request-Signature")
	req.Header.Add("X-Request-Timestamp", "X-Request-Timestamp")
	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 People_requestPersonTransactionPinReset_example
require 'uri'
require 'net/http'

url = URI("https://client.api.corpx.com/v1/people/pin/reset-request")

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

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

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

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

HttpResponse<String> response = Unirest.post("https://client.api.corpx.com/v1/people/pin/reset-request")
  .header("X-Acting-Document", "X-Acting-Document")
  .header("X-Content-SHA256", "X-Content-SHA256")
  .header("X-Request-Signature", "X-Request-Signature")
  .header("X-Request-Timestamp", "X-Request-Timestamp")
  .header("X-Tenant-Id", "X-Tenant-Id")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"displayMessage\": \"Confirme seu rosto para escolher um PIN novo.\"\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://client.api.corpx.com/v1/people/pin/reset-request', [
  'body' => '{
  "displayMessage": "Confirme seu rosto para escolher um PIN novo."
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
    'X-Acting-Document' => 'X-Acting-Document',
    'X-Content-SHA256' => 'X-Content-SHA256',
    'X-Request-Signature' => 'X-Request-Signature',
    'X-Request-Timestamp' => 'X-Request-Timestamp',
    'X-Tenant-Id' => 'X-Tenant-Id',
  ],
]);

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

```csharp People_requestPersonTransactionPinReset_example
using RestSharp;

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

```swift People_requestPersonTransactionPinReset_example
import Foundation

let headers = [
  "X-Acting-Document": "X-Acting-Document",
  "X-Content-SHA256": "X-Content-SHA256",
  "X-Request-Signature": "X-Request-Signature",
  "X-Request-Timestamp": "X-Request-Timestamp",
  "X-Tenant-Id": "X-Tenant-Id",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = ["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://client.api.corpx.com/v1/people/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()
```