---
title: "Connect an account (hosted authentication)"
method: POST
path: "/api/v1/hosted/accounts/link"
tags: ["Accounts"]
---

# Connect an account (hosted authentication)

`POST /api/v1/hosted/accounts/link`

Create a url which redirect to Unipile's hosted authentication to connect or reconnect an account.

## Request body

- union
  - object
    - `expiresOn` string, required — An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ). ⚠️ All links expire upon daily restart, regardless of their stated expiration date. A new link must be generated each time a user clicks on your app to connect.
    - `name` string — This field will be sent back to you in the notify_url to help match the added account with your user.
    - `success_redirect_url` unknown
    - `failure_redirect_url` unknown
    - `bypass_success_screen` boolean — Whether to bypass the hosted auth success screen before accessing the success_redirect_url.
    - `notify_url` unknown
    - `disabled_features` string[] — An array of features that should be disabled in this account. Accepted values : linkedin_recruiter | linkedin_sales_navigator | linkedin_organizations_mailboxes.
    - `disabled_options` string[] — An array of options that should be disabled in hosted auth interface. Accepted values : proxy | autoproxy | cookie_auth | credentials_auth | qrcode_auth | pairing_code_auth | sync_limit | language. `qrcode_auth` and `pairing_code_auth` are currently supported for WhatsApp only.
    - `proxy` object
      - `protocol` 'https' | 'http' | 'socks5'
      - `port` number, required
      - `host` string, required
      - `username` string — Optional username for proxy’s authentication.
      - `password` string — Optional password for proxy’s authentication.
    - `api_url` unknown, required
    - `sync_limit` object
      - `MAILING` 'NO_HISTORY_SYNC'
      - `MESSAGING` object — Set a sync limit either for chats, messages or both. Chats limit will apply to each inbox, whereas messages limit will apply to each chat. No value will not apply any limit (default behaviour). Providers partial support.
        - `chats` union — Either a UTC Datetime to start sync from, or a quantity of data.
          - string — An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ). ⚠️ All links expire upon daily restart, regardless of their stated expiration date. A new link must be generated each time a user clicks on your app to connect.
          - number — The quantity of data that should be synced from data history. 0 will not sync history.
        - `messages` union — Either a UTC Datetime to start sync from, or a quantity of data.
          - string — An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ). ⚠️ All links expire upon daily restart, regardless of their stated expiration date. A new link must be generated each time a user clicks on your app to connect.
          - number — The quantity of data that should be synced from data history. 0 will not sync history.
    - `google_scopes` string, googleScopes — Optional comma-separated list of scopes to use for GOOGLE_OAUTH accounts
    - `microsoft_scopes` string, microsoftScopes — Optional comma-separated list of scopes to use for OUTLOOK accounts
    - `type` 'create', required — A litteral value to choose between a connection or a reconnection.
    - `providers` union, required — The providers for whom you want to propose to connect an account.
      - '*' — Data type: string
      - '*:MAILING' — Data type: string
      - '*:MESSAGING' — Data type: string
      - '*:CALENDAR' — Data type: string
      - string[] — Data type: Array of strings. Accepted values: LINKEDIN | WHATSAPP | INSTAGRAM | MESSENGER | TELEGRAM | GOOGLE | OUTLOOK | MAIL | TWITTER
  - object
    - `expiresOn` string, required — An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ). ⚠️ All links expire upon daily restart, regardless of their stated expiration date. A new link must be generated each time a user clicks on your app to connect.
    - `name` string — This field will be sent back to you in the notify_url to help match the added account with your user.
    - `success_redirect_url` unknown
    - `failure_redirect_url` unknown
    - `bypass_success_screen` boolean — Whether to bypass the hosted auth success screen before accessing the success_redirect_url.
    - `notify_url` unknown
    - `disabled_features` string[] — An array of features that should be disabled in this account. Accepted values : linkedin_recruiter | linkedin_sales_navigator | linkedin_organizations_mailboxes.
    - `disabled_options` string[] — An array of options that should be disabled in hosted auth interface. Accepted values : proxy | autoproxy | cookie_auth | credentials_auth | qrcode_auth | pairing_code_auth | sync_limit | language. `qrcode_auth` and `pairing_code_auth` are currently supported for WhatsApp only.
    - `proxy` object
      - `protocol` 'https' | 'http' | 'socks5'
      - `port` number, required
      - `host` string, required
      - `username` string — Optional username for proxy’s authentication.
      - `password` string — Optional password for proxy’s authentication.
    - `api_url` unknown, required
    - `sync_limit` object
      - `MAILING` 'NO_HISTORY_SYNC'
      - `MESSAGING` object — Set a sync limit either for chats, messages or both. Chats limit will apply to each inbox, whereas messages limit will apply to each chat. No value will not apply any limit (default behaviour). Providers partial support.
        - `chats` union — Either a UTC Datetime to start sync from, or a quantity of data.
          - string — An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ). ⚠️ All links expire upon daily restart, regardless of their stated expiration date. A new link must be generated each time a user clicks on your app to connect.
          - number — The quantity of data that should be synced from data history. 0 will not sync history.
        - `messages` union — Either a UTC Datetime to start sync from, or a quantity of data.
          - string — An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ). ⚠️ All links expire upon daily restart, regardless of their stated expiration date. A new link must be generated each time a user clicks on your app to connect.
          - number — The quantity of data that should be synced from data history. 0 will not sync history.
    - `google_scopes` string, googleScopes — Optional comma-separated list of scopes to use for GOOGLE_OAUTH accounts
    - `microsoft_scopes` string, microsoftScopes — Optional comma-separated list of scopes to use for OUTLOOK accounts
    - `type` 'reconnect', required — A litteral value to choose between a connection or a reconnection.
    - `reconnect_account` string, required — The id of the account to reconnect.

## Response `200`

OK. Request succeeded.

- object
  - `object` 'HostedAuthUrl', required
  - `url` string, required — A url redirecting to Unipile's hosted authentication for account connection or reconnection.

## Other responses

- `400` — ## Bad Request ### Invalid parameters - Type: "errors/invalid_parameters" One or more request parameters are invalid or missing. ### Missing parameters - Type: "errors/missing_parameters" One or more request parameters are missing. ### Invalid parameters - Type: "errors/invalid_request" One or a combination of request parameters are invalid. ### Malformed request - Type: "errors/malformed_request" The given request has been rejected by the provider. ### Content too large - Type: "errors/content_too_large" The request payload or filter query is too large and has been rejected by the provider. ### Too many characters - Type: "errors/too_many_characters" The provided content exceeds the character limit. ### Unescaped characters - Type: "errors/unescaped_characters" The request path contains unescaped characters. ### Limit too high - Type: "errors/limit_too_high" Provider cannot accept such high pagination limit. See API reference for details. ### Invalid action - Type: "errors/invalid_action" This action is invalid. ### Invalid label - Type: "errors/invalid_label" This label is invalid.
- `401` — ## Unauthorized ### Missing credentials - Type: "errors/missing_credentials" Some credentials are necessary to perform the request. ### Multiple sessions - Type: "errors/multiple_sessions" LinkedIn limits the use of multiple sessions on certain Recruiter accounts. This error restricts access to this route only, but causing a popup to appear in the user's browser, prompting them to choose a session, which can disconnect the current account. To avoid this error, use the cookie connection method. ### Wrong account - Type: "errors/wrong_account" The provided credentials do not match the correct account. ### Invalid credentials - Type: "errors/invalid_credentials" The provided credentials are invalid. ### Invalid proxy credentials - Type: "errors/invalid_proxy_credentials" The provided proxy credentials are invalid. ### Invalid IMAP configuration - Type: "errors/invalid_imap_configuration" The provided IMAP configuration is invalid. ### Invalid SMTP configuration - Type: "errors/invalid_smtp_configuration" The provided SMTP configuration is invalid. ### Invalid checkpoint solution - Type: "errors/invalid_checkpoint_solution" The checkpoint resolution did not pass successfully. Please retry. ### Checkpoint error - Type: "errors/checkpoint_error" The checkpoint does not appear to be resolvable. Please try again and contact support if the problem persists. ### Expired credentials - Type: "errors/expired_credentials" Invalid credentials. Please check your username and password and try again. ### Expired link - Type: "errors/expired_link" This link has expired. Please return to the application and generate a new one. ### Insufficient privileges - Type: "errors/insufficient_privileges" This resource seems to be out of your scopes. ### Disconnected account - Type: "errors/disconnected_account" The account appears to be disconnected from the provider service. ### Disconnected feature - Type: "errors/disconnected_feature" The service you're trying to reach appears to be disconnected.
- `500` — ## Internal Server Error ### Unexpected error - Type: "errors/unexpected_error" Something went wrong. {{moreDetails}} ### Provider error - Type: "errors/provider_error" The provider is experiencing operational problems. Please try again later. ### Authentication intent error - Type: "errors/authentication_intent_error" The current authentication intent was killed after failure. Please start the process again from the beginning.
- `503` — ## Service Unavailable ### No client session - Type: "errors/no_client_session" No client session is currently running. ### No channel - Type: "errors/no_channel" No channel to client session. ### Handler missing - Type: "errors/no_handler" Handler missing for that request. ### Network down - Type: "errors/network_down" Network is down on server side. Please wait a moment and retry. ### Service unavailable - Type: "errors/service_unavailable" Please try again later.
- `504` — ## Gateway Timeout ### Request timed out - Type: "errors/request_timeout" Request Timeout. Please try again, and if the issue persists, contact support.

---

[API](https://skmtc.net/unipile/apis/unipile-api-reference.md) · [All operations](https://skmtc.net/unipile/apis/unipile-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/unipile/unipile-api-reference/revisions/3483a34061f6/schema)