POST

Record residency attestation

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

Header Params

user-id string required

User id of the user making the request.

at least 1 characters

Body Params

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 code of the jurisdiction the user is attesting for. Must match the request's IP-derived country.
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.

at least 1 characters
isRestrictedIndividual boolean required

The user's answer to the "Restricted Individual" question for the jurisdiction.

Responses

200

Response Body

object

codec for the POST /api/link/v1/attestations response

geoAttestation object 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.
geoAttestation object
- country string required
  
  ISO 3166-1 alpha-3 code of the request's IP-derived jurisdiction.
  
  at least 1 characters
- subdivision string
  
  Bare ISO 3166-2 subdivision code (e.g. NY); omitted for country-level jurisdictions.
- attestationStatus string enum required
  
  The resolved attestation state for the jurisdiction.
  
  not_attestedattested_unrestrictedattested_restricted
- 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.

400

Bad Request

No response body

401

Unauthorized

Response Body

object

Standard structured error response payload for Link API v1 error responses. Contains an error name and human-readable error message.

errorName string required
error string required

403

Forbidden

Response Body

object

Standard structured error response payload for Link API v1 error responses. Contains an error name and human-readable error message.

errorName string required
error string required

409

Conflict

Response Body

object

Codec for the 409 response returned when the attested jurisdiction does not match the request's IP-derived one. Carries the current resolved geo-attestation so the UI can re-prompt the user for the jurisdiction they are actually in.

errorName string required
error string required
geoAttestation object 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.
geoAttestation object
- country string required
  
  ISO 3166-1 alpha-3 code of the request's IP-derived jurisdiction.
  
  at least 1 characters
- subdivision string
  
  Bare ISO 3166-2 subdivision code (e.g. NY); omitted for country-level jurisdictions.
- attestationStatus string enum required
  
  The resolved attestation state for the jurisdiction.
  
  not_attestedattested_unrestrictedattested_restricted
- 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.

422

Unprocessable Entity

Response Body

object

Standard structured error response payload for Link API v1 error responses. Contains an error name and human-readable error message.

errorName string required
error string required

500

Internal Server Error

Response Body

object

Standard structured error response payload for Link API v1 error responses. Contains an error name and human-readable error message.

errorName string required
error string required

curl -X POST \ --url 'https://app.bitgo-test.com/api/link/v1/attestations' \ --header 'accept: application/json' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'user-id: string' \ --header 'content-type: application/json' \ --data '{,"country":"string","subdivision":"string","isRestrictedIndividual":true}'

const url = 'https://app.bitgo-test.com/api/link/v1/attestations'; const options = { method: 'POST', headers: {accept: 'application/json', 'Authorization': 'Bearer YOUR_ACCESS_TOKEN', 'user-id': 'string', 'content-type': 'application/json'}, body: JSON.stringify({,"country":"string","subdivision":"string","isRestrictedIndividual":true}) }; fetch(url, options) .then(res => res.json()) .then(json => console.log(json)) .catch(err => console.error(err));

require 'uri' require 'net/http' url = URI("https://app.bitgo-test.com/api/link/v1/attestations") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["accept"] = 'application/json' request["Authorization"] = 'Bearer YOUR_ACCESS_TOKEN' request["user-id"] = 'string' request["content-type"] = 'application/json' request.body = '{,"country":"string","subdivision":"string","isRestrictedIndividual":true}' response = http.request(request) puts response.read_body

<?php require_once('vendor/autoload.php'); $client = new \GuzzleHttp\Client(); $response = $client->request('POST', 'https://app.bitgo-test.com/api/link/v1/attestations', [ 'headers' => [ 'accept' => 'application/json', 'Authorization' => 'Bearer YOUR_ACCESS_TOKEN', 'user-id' => 'string', 'content-type' => 'application/json', ], 'body' => '{,"country":"string","subdivision":"string","isRestrictedIndividual":true}', ]); echo $response->getBody();

import requests url = "https://app.bitgo-test.com/api/link/v1/attestations" payload = {,"country":"string","subdivision":"string","isRestrictedIndividual":true} headers = { "accept": "application/json", "Authorization": "Bearer YOUR_ACCESS_TOKEN", "user-id": "string", "content-type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.text)

{ "errorName": "string", "error": "string", "geoAttestation": { "country": "string", "subdivision": "string", "attestationStatus": "not_attested", "attestedAt": "string", "expiresAt": "string" } }