--- title: "Begins the validation process for a phone number for association with the user's account." method: POST path: "/_matrix/client/v3/account/3pid/msisdn/requestToken" tags: ["Account management"] --- # Begins the validation process for a phone number for association with the user's account. `POST /_matrix/client/v3/account/3pid/msisdn/requestToken` ## Request - Base URL: `https://matrix.org` - URL: `https://matrix.org/_matrix/client/v3/account/3pid/msisdn/requestToken` - Auth: none declared - TypeScript: (a function with typed inputs; its response is checked against the schema) The homeserver must check that the given phone number is **not** already associated with an account on this homeserver. This API should be used to request validation tokens when adding a phone number to an account. This API's parameters and response are identical to that of the [`/register/msisdn/requestToken`](https://spec.matrix.org/v1.19/client-server-api/#post_matrixclientv3registermsisdnrequesttoken) endpoint. The homeserver should validate the phone number itself, either by sending a validation message itself or by using a service it has control over. ## Request body - object - `client_secret` string, required: A unique string generated by the client, and used to identify the validation attempt. It must be a string consisting of the characters `[0-9a-zA-Z.=_-]`. Its length must not exceed 255 characters and it must not be empty. - `country` string, required: The two-letter uppercase ISO-3166-1 alpha-2 country code that the number in `phone_number` should be parsed as if it were dialled from. - `next_link` string, uri: Optional. When the validation is completed, the identity server will redirect the user to this URL. This option is ignored when submitting 3PID validation information through a POST request. - `phone_number` string, required: The phone number to validate. - `send_attempt` integer, required: The server will only send an SMS if the `send_attempt` is a number greater than the most recent one which it has seen, scoped to that `country` + `phone_number` + `client_secret` triple. This is to avoid repeatedly sending the same SMS in the case of request retries between the POSTing user and the identity server. The client should increment this value if they desire a new SMS (e.g. a reminder) to be sent. - `id_access_token` string: An access token previously registered with the identity server. Servers can treat this as optional to distinguish between r0.5-compatible clients and this specification version. Required if an `id_server` is supplied. - `id_server` string: The hostname of the identity server to communicate with. May optionally include a port. This parameter is ignored when the homeserver handles 3PID verification. This parameter is deprecated with a plan to be removed in a future specification version for `/account/password` and `/register` requests. ## Response `200` An SMS message was sent to the given phone number. - object - `sid` string, required: The session ID. Session IDs are opaque strings that must consist entirely of the characters `[0-9a-zA-Z.=_-]`. Their length must not exceed 255 characters and they must not be empty. - `submit_url` string, uri: An optional field containing a URL where the client must submit the validation token, with identical request and response parameters and error codes to the Identity Service API's [`POST /validate/email/submitToken`](https://spec.matrix.org/v1.19/identity-service-api/#post_matrixidentityv2validateemailsubmittoken) and [`POST /validate/msisdn/submitToken`](https://spec.matrix.org/v1.19/identity-service-api/#post_matrixidentityv2validatemsisdnsubmittoken) endpoints (without the requirement for an access token). The homeserver must send this token to the user (if applicable), who should then be prompted to provide it to the client. If this field is not present, the client can assume that verification will happen without the client's involvement provided the homeserver advertises a sufficiently recent version in the [`GET /versions`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientversions) response (ie: r0.5.0). ## Other responses - `400`: The third-party identifier is already in use on the homeserver, or the request was invalid. Error codes that can be returned are: * `M_THREEPID_IN_USE`: The phone number supplied cannot be bound because is is already associated with a different Matrix ID. * `M_SERVER_NOT_TRUSTED`: The server does not trust/support the identity server * `M_THREEPID_MEDIUM_NOT_SUPPORTED`: The homeserver does not support adding phone numbers. * `M_INVALID_PARAM`: The phone number given was not valid. - `403`: The homeserver does not allow the third-party identifier as a contact option. --- [API](https://skmtc.dev/matrix/apis/matrix-client-server-api.md) - [All operations](https://skmtc.dev/matrix/apis/matrix-client-server-api/llms.txt) - [OpenAPI document](https://skmtc.dev/matrix/apis/matrix-client-server-api/revisions/c7fe4072c681?raw)