All requests to the /v2/users/* endpoints must include both the client_id and api_key as detailed in the Authentication document.

Create and verify a user to your application.

​
Creating/Connecting Users

The process of creating a user or connecting an existing user to your application is the same and requires the same steps as listed below.

Creating users happens through the /v2/users/create endpoint. Once hit, a dots user will be created if one does not exist based on phone number. This user must then be verified through a one-time code sent over text-message. This code can be requested through the /v2/users/send_verification_token endpoint and then verified through the /v2/users/verify_user endpoint.

​
Method

Call the create endpoint

> curl https://pls.senddotssandbox.com/v2/users/create \
  -X POST \
  -H "Authorization: Basic <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
        "email": "test@senddots.com",
        "country_code": "1",
        "phone_number": "1234567890",
        "first_name": "Bob",
        "last_name": "Loblaw",
        "username": <Optional>
      }'

> response = {
    "success": true,
    "action": "verify",
    "verification_id": "143c7e1c-2295-42c0-9fc9-23756ac26250"
  }
Parameters
NameTypeRequiredDescription
emailstring✔️User’s email address
country_codestring✔️User’s phone number country code without the plus sign (‘1’ for the US)
phone_numberstring✔️User’s phone number as a string containing only digits
first_namestring✔️User’s first name as a string
last_namestring✔️User’s last name as a string
usernamestringUser’s username on your platform. If the username is taken or left blank a random username will be generated

​
2. Request a verification token by calling the send_verification_token endpoint

> curl https://pls.senddotssandbox.com/v2/users/send_verification_token \
  -X POST \
  -H "Authorization: Basic <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
        "verification_id": "143c7e1c-2295-42c0-9fc9-23756ac26250"
      }'

> response = {
    "success": true
  }
Parameters
NameTypeRequiredDescription
verification_idstring✔️User’s verification id from the previous call

​
3. Submit the verification token by calling the verify_user endpoint

curl https://pls.senddotssandbox.com/v2/users/verify_user \
  -X POST \
  -H "Authorization: Basic <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
        "verification_id": "143c7e1c-2295-42c0-9fc9-23756ac26250",
        "verification_token": "123456"
      }'

response = {
    "success": true,
    "user": {
      "id": "ee5498cb-a126-495c-8933-d46918c55593"
    }
  }
Parameters
NameTypeRequiredDescription
verification_idstring✔️User’s dots id from the previous call
verification_tokenstring✔️Verification token sent to the user’s phone number