Skip to content
BTC Direct

This endpoint links a partner identifier to the authenticated user, after the user has logged in and consented (the widget calls this once consent is given). The identifier is only ever linked to the authenticated user, never to a user supplied in the request body. The raw identifier is forwarded to genesis, which owns hashing, storage and the partner webhook.

POST
/api/v2/user/link-identifier

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”
object
identifier
required

The user identifier to link to the authenticated user. In the unified-checkout flow, pass the value as received in the checkout URL, unchanged.

string
nullable >= 36 characters <= 1024 characters
Example
c6fefe8d7ac0f4113876d634e8d15f65947f1b62d4859fffcd2464d2be58b2d8

Responses

Section titled “ Responses ”

204

Section titled “204 ”

User identifier linked successfully.

400

Section titled “400 ”

A list of possible errors for this endpoint.

object
code
required
string
Allowed values: ER053 ER102 ER700 ER701 ER702 ER703 ER704 ER705 ER706 ER707 ER708 ER709 ER800 ER801 ER802 ER803 ER805 ER806 ER999
message
required
string
solution
required
string
Example
{
  "errors": {
    "ER053": {
      "code": "ER053",
      "message": "Missing identifier.",
      "solution": "Provide a valid identifier."
    },
    "ER102": {
      "code": "ER102",
      "message": "User identifier length out of bounds.",
      "solution": "Provide a user identifier with a minimum of 36 characters and a maximum of 255."
    },
    "ER700": {
      "code": "ER700",
      "message": "User authorization token not found.",
      "solution": "Provide a user authorization token."
    },
    "ER701": {
      "code": "ER701",
      "message": "User authorization token has expired.",
      "solution": "Request a new authorization token, or refresh the token."
    },
    "ER702": {
      "code": "ER702",
      "message": "User authorization token is invalid.",
      "solution": "Provide a valid user authorization token."
    },
    "ER703": {
      "code": "ER703",
      "message": "User identifier does not belong to the user in the user authorization token.",
      "solution": "Provide a valid user identifier, or remove the user identifier header."
    },
    "ER704": {
      "code": "ER704",
      "message": "No user identifier found in headers.",
      "solution": "Provide a valid user identifier, or use the user/password authentication mechanism to request a user token and send that."
    },
    "ER705": {
      "code": "ER705",
      "message": "User identifier is not linked to a user.",
      "solution": "Provide a valid user identifier, link this user identifier to a user account, or use the user/password authentication mechanism."
    },
    "ER706": {
      "code": "ER706",
      "message": "User identifier is invalid.",
      "solution": "Provide a valid user identifier, a unique identifier string for the user account that is not already in use."
    },
    "ER707": {
      "code": "ER707",
      "message": "User identifier is invalid.",
      "solution": "Please provide an identifier, consisting of 36 - 255 characters, numeric or alphanumeric only."
    },
    "ER708": {
      "code": "ER708",
      "message": "There is a pending document for this side.",
      "solution": "Wait for the pending document to be reviewed."
    },
    "ER709": {
      "code": "ER709",
      "message": "User not found, or user has been deleted.",
      "solution": "Provide a valid user identifier."
    },
    "ER800": {
      "code": "ER800",
      "message": "Authorization token is invalid.",
      "solution": "Provide a valid authorization token."
    },
    "ER801": {
      "code": "ER801",
      "message": "Authorization token has expired.",
      "solution": "Request a new authorization token."
    },
    "ER802": {
      "code": "ER802",
      "message": "Authorization token not found.",
      "solution": "Provide an authorization token."
    },
    "ER803": {
      "code": "ER803",
      "message": "Multiple authorization methods used.",
      "solution": "Use exactly one authorization method."
    },
    "ER805": {
      "code": "ER805",
      "message": "API key is invalid.",
      "solution": "Provide a valid API key."
    },
    "ER806": {
      "code": "ER806",
      "message": "API key not found.",
      "solution": "Provide an API key."
    },
    "ER999": {
      "code": "ER999",
      "message": "A general error has occurred. Please contact our support team.",
      "solution": "Contact our support team."
    }
  }
}