---
title: "Create account"
method: POST
path: "/v1/connect/{project_id}/accounts"
---

# Create account

`POST /v1/connect/{project_id}/accounts`

Connect a new account for an external user in the project

## Headers

- `x-pd-environment` 'development' | 'production', required — The environment in which the server client is running

## Request body

- CreateAccountOpts — Request object for creating an account
  - `app_slug` string, required — The app slug for the account
  - `cfmap_json` string, required — JSON string containing the custom fields mapping
  - `connect_token` string, required — The connect token for authentication
  - `name` string — Optional name for the account
  - `account_id` string — An existing account ID to reconnect. When provided, the account's credentials are updated instead of creating a new account. Must belong to the same external user and project environment as the connect token, and match the app identified by app_slug.

## Response `200`

account created

- Account — End user account data, returned from the API.
  - `id` string, required — The unique ID of the account.
  - `name` string, nullable — The custom name of the account if set.
  - `external_id` string — The external ID associated with the account.
  - `healthy` boolean — Indicates if the account is healthy. Pipedream will periodically retry token refresh and test requests for unhealthy accounts
  - `dead` boolean, nullable — Indicates if the account is no longer active
  - `app` App — Response object for a Pipedream app's metadata
    - `id` string, nullable — ID of the app. Only applies for OAuth apps.
    - `name_slug` string, required — The name slug of the target app (see https://pipedream.com/docs/connect/quickstart#find-your-apps-name-slug)
    - `name` string, required — The human-readable name of the app
    - `auth_type` 'keys' | 'oauth' | 'none', nullable — The authentication type used by the app
    - `description` string, nullable — A short description of the app
    - `img_src` string, required — The URL to the app's logo
    - `custom_fields_json` string, nullable, required — A JSON string representing the custom fields for the app
    - `categories` string[], required — Categories associated with the app
    - `featured_weight` number, required — A rough directional ordering of app popularity, subject to changes by Pipedream
    - `scope_profiles` object[], required — Named subsets of the app's OAuth scopes that may be requested when users connect their accounts (via the `oauth_scope_profile` parameter). Empty for apps that don't define any.
      - `name` 'read_only' | 'read_write' | 'admin', required — The profile name. Pass this back as `oauth_scope_profile` when starting the OAuth flow for this app.
      - `scopes` string[], required — The actual OAuth scopes of the upstream API that the user will be asked to authorize when this profile is selected.
  - `created_at` string, date-time — The date and time the account was created, an ISO 8601 formatted string
  - `updated_at` string, date-time — The date and time the account was last updated, an ISO 8601 formatted string
  - `authorized_scopes` string[] — The OAuth scopes effectively granted to this account. Empty for non-OAuth apps.
  - `credentials` object, nullable — The credentials associated with the account, if the `include_credentials` parameter was set to true in the request (only applicable for BYOA apps). In addition to the well-known OAuth fields listed below, this object may contain app-specific custom fields (e.g. `base_url`).
    - `oauth_client_id` string — The OAuth client ID for the app, if applicable
    - `oauth_access_token` string — The OAuth access token
    - `oauth_refresh_token` string — The OAuth refresh token
    - `oauth_uid` string — The unique OAuth user identifier
    - `oauth_signer_uri` string — The OAuth signer URI, if the app uses a custom OAuth signer
  - `expires_at` string, date-time — The date and time the account's credentials expiration, an ISO 8601 formatted string
  - `error` string, nullable — The error message if the account is unhealthy or dead, null otherwise
  - `last_refreshed_at` string, date-time, nullable — The date and time the account was last refreshed, an ISO 8601 formatted string
  - `next_refresh_at` string, date-time, nullable — The date and time the account will next be refreshed, an ISO 8601 formatted string

## Other responses

- `429` — too many requests

---

[API](https://skmtc.net/pipedream/apis/pipedream-rest-api.md) · [All operations](https://skmtc.net/pipedream/apis/pipedream-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pipedream/pipedream-rest-api/versions/c25dbf225c49/schema)