---
title: "Record residency attestation"
method: POST
path: "/api/link/v1/attestations"
tags: ["Link Permissions"]
---

# Record residency attestation

`POST /api/link/v1/attestations`

Attest whether the user is a citizen or resident of their current
IP-derived jurisdiction.

## Headers

- `user-id` string, required

## Request body

- object — Attestation request body. Records the user's Restricted Individual answer and claimed jurisdiction, which must match the request's IP-derived location.
  - `country` string, required — ISO 3166-1 alpha-3 country code (e.g. `USA`). The route-facing codec stays a plain string so OpenAPI schema generation can represent it. The service enforces the alpha-3 shape and known-country membership before recording the attestation.
  - `subdivision` string — Bare ISO 3166-2 subdivision code (e.g. `NY`) of the jurisdiction the user is attesting for. Must match the request's IP-derived subdivision; omit only for country-level jurisdictions.
  - `isRestrictedIndividual` boolean, required — The user's answer to the "Restricted Individual" question for the jurisdiction.

## Response `200`

OK

- V1PostAttestationResponse — codec for the POST /api/link/v1/attestations response
  - `geoAttestation` ResolvedGeoAttestation, required — The user's resolved geo-attestation for the jurisdiction derived from their request IP. `country` is the ISO 3166-1 alpha-3 code resolved from the request's geolocation and is always present; `subdivision` is the bare ISO 3166-2 subdivision code (e.g. `NY`) and is omitted for country-level jurisdictions. `not_attested` covers both a user who has never attested for the jurisdiction and one whose latest attestation has expired — in both cases `attestedAt` and `expiresAt` are omitted, since no attestation is currently in force.
    - `country` string, required — ISO 3166-1 alpha-3 code of the request's IP-derived jurisdiction.
    - `subdivision` string — Bare ISO 3166-2 subdivision code (e.g. `NY`); omitted for country-level jurisdictions.
    - `attestationStatus` 'not_attested' | 'attested_unrestricted' | 'attested_restricted', required — codec for the resolved geo-attestation state of a jurisdiction
    - `attestedAt` string, date-time — When the winning attestation was recorded; omitted while `not_attested`.
    - `expiresAt` string, date-time — When the winning attestation stops being valid; omitted while `not_attested`.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `409` — Conflict
- `422` — Unprocessable Entity
- `500` — Internal Server Error

## Changes

- **2026-09-22** `d083f3244790` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/bitgo/apis/bitgo-api/changes/api/link/v1/attestations/post.md)

---

[API](https://skmtc.dev/bitgo/apis/bitgo-api.md) · [All operations](https://skmtc.dev/bitgo/apis/bitgo-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bitgo/apis/bitgo-api/revisions/d083f3244790?raw)