DotsDocs
Users

Connect an Existing User to an App

Connect a user who already exists elsewhere in your organization to another App, so the same person can be paid from both without re-onboarding. Requires organization credentials. The user must belong to the calling organization and be active.

POST
/v2/users/connect

Connect a user who already exists elsewhere in your organization to another App, so the same person can be paid from both without re-onboarding.

Requires organization credentials. The user must belong to the calling organization and be active.

Authorization

api_key
headerAuthorizationBasic <token>

Request Body

application/json
  1. body
user_id*string

Id of the existing user to connect.

Formatuuid
app_id*string

Id of the App to connect the user to.

Formatuuid
first_name?string

Overrides the first name on the new connection.

Length1 <= length <= 50
last_name?string

Overrides the last name on the new connection.

Length1 <= length <= 50
email?string

Overrides the email on the new connection.

Formatemail
username?string
Length1 <= length <= 50
metadata?unknown

Metadata to store on the new connection.

Response Body

Created

application/json
  1. response
id?string
Formatuuid
first_name?string
last_name?string
email?string
Formatemail
phone_number?
verified?boolean

Whether the user and their app connection are active.

country?|

User's two-letter country code.

Formatiso3166
auto_payout_enabled?boolean

Whether automatic payouts are enabled for the user.

default_payout_method?rail
Value in"ach""rtp""paypal""venmo""visa""amazon""cash_app""intl_bank""intl_transfer""bank_transfer""airtm""payoneer""wire""invoice""crypto""push_to_card"
default_payout_method_details?
wallet?
status?string
Value in"verified""unverified""disabled""in_review""banned"
compliance?
metadata?||

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

payout_options_exclude_list?array<>

Payout rails hidden from this user. Stacks with app-level exclusions.

1099_adjustment?|

Current-year 1099 adjustment for the user, if one has been set. Only returned by the retrieve-a-user endpoint (GET /v2/users/{user_id}) when the application's configured filing type has a matching adjustment; omitted otherwise and never included in list responses.

Example Request
curl -X POST 'https://api.dots.dev/api/v2/users/connect' \  -H 'Content-Type: application/json' \  -d '{  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",  "app_id": "affd1d10-9538-4fc8-9e0b-4594a28c1335"}'
Example Response
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "first_name": "string",  "last_name": "string",  "email": "user@example.com",  "phone_number": {    "country_code": "string",    "phone_number": "string"  },  "verified": true,  "country": "string",  "auto_payout_enabled": true,  "default_payout_method": "ach",  "default_payout_method_details": {    "id": "string",    "platform": "ach",    "description": "string",    "mask": "string",    "email": "string",    "phone_number": "string",    "cash_tag": "string",    "country": "string",    "currency": "string",    "instant_ach_available": true,    "rtp_enabled": true,    "bank_verification_status": "verified",    "meta": null  },  "wallet": {    "amount": 0,    "withdrawable_amount": 0,    "credit_balance": 0  },  "status": "verified",  "compliance": {    "tax_id_collected": true,    "tax_id_verification": "not_required",    "address_collected": true,    "date_of_birth_collected": true,    "must_collect_1099": true,    "1099_collected": true,    "w8_ben_collected": true,    "must_collect_dac7": true,    "dac7_collected": true,    "dac7_vat_number_status": "pending",    "flagged": true,    "id_verified": true,    "has_criminal_activity": true,    "background_check": {      "status": "not_started",      "updated": "2019-08-24T14:15:22Z"    },    "w9": {      "entity_type": "individual",      "business_name": "string",      "tax_id_collected": true,      "address_collected": true    },    "flags": {      "ofac": true,      "ofac_status": "unflagged",      "payout_method": true,      "payout_method_cycle": true,      "name_mismatch": true    }  },  "metadata": "string",  "payout_options_exclude_list": [    "ach"  ],  "1099_adjustment": {    "year": 0,    "form": "1099-NEC",    "amount": 1  }}