> ## Documentation Index
> Fetch the complete documentation index at: https://docs.manifestfinancial.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Account Connections

# Overview

The Account Connection object represents the relationship between your enterprise and a creator. It includes such details as the creator's name, how they've connected (Manifest or ACH), and what permissions they have granted you.

For a typical integration, you'll create one Account Connection for each creator in your system, and store the ID with your creator data. You can do this ahead of time, say during creator enrollment in your system, or right after a creator requests to be paid by Manifest. Either way, an Account Connection must be created before a [Connect Link](/platform/connect/links) can be generated or a [Connect Invite](/platform/connect/invites) can be sent.

***

# Methods

<Tabs>
  <Tab title="Create">
    <Card icon="square-plus" iconType="solid" color="#86B74B">
      **`POST`  /account-connection**<br />
      Create a new account connection under your enterprise.
    </Card>

    ## Body Parameters

    <ParamField body="first_name" type="string" required="true">
      Legal first name from your records.
    </ParamField>

    <ParamField body="last_name" type="string" required="true">
      Legal last name from your records.
    </ParamField>

    <ParamField body="external_id" type="string">
      Optional user identifier from your system. If set, Manifest will enforce uniqueness, e.g. attempts to create a second account connection for the same user will fail.

      This should be a stable value like a User ID, not something that might change like an email address or phone number. This value should not contain any sensitive information.
    </ParamField>

    <ParamField body="email" type="string" required="true">
      Email address from your records. See sandbox testing for more information about using emails in sandbox.
    </ParamField>

    <ParamField body="business_name" type="string">
      Legal business name of the creator from your records, if applicable.
    </ParamField>

    <ParamField body="display_name" type="string">
      Display name, visible to the creator. Examples: a band name, online persona, or shortened version of the business name.
    </ParamField>

    <ParamField body="requested_permissions" type="string[]" required="true">
      Array of permissions to request from the user during the *Connect* flow. See
      below for details.
    </ParamField>

    <ParamField body="verification_prompt" type="string" required="true">
      Text to prompt your users for their verification answer. Examples below.
    </ParamField>

    <ParamField body="verification_answer" type="string" required="true">
      Required answer to the verification prompt. Manifest will correct for case
      sensitivity and trim excess white space before comparing the user's entered
      value. Any special formatting requirements should either be avoided or
      included in the verification prompt itself.
    </ParamField>

    <ParamField body="legacy_payout_method" type="string">
      You can set a legacy payment method on new account connections. See below for
      available options and required fields.
    </ParamField>

    <ParamField body="user_data" type="object">
      User defined data that can be attached to the object. See the [User Data](/reference/user-data)
      page for details.
    </ParamField>

    ## Example

    <CodeGroup>
      ```json Request theme={null}
      // POST /account-connection
      {
          "first_name": "Paul",
          "last_name": "McCartney",
          "email": "paul@thebeatles.com",
          "display_name": "The Beatles",
          "requested_permissions": ["payment.credit"],
          "verification_prompt": "Please enter the last 4 digits of your tax ID.",
          "verification_answer": "1234"
      }
      ```

      ```json Response theme={null}
      {
          "id": "acon_XXXXX",
          "status": "created",
          "first_name": "Paul",
          "last_name": "McCartney",
          "email": "paul@thebeatles.com",
          "display_name": "The Beatles",
          "requested_permissions": ["payment.credit"],
          "verification_prompt": "Please enter the last 4 digits of your tax ID.",
          "user_data": {},
          "created_at": "2024-01-26T21:18:16.704Z",
          "updated_at": "2024-01-26T21:18:16.704Z"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Get">
    <Card icon="square-arrow-right" iconType="solid" color="#425BE0">
      **`GET`  /account-connection/:id**<br />
      Retrieve an account connection by its ID.
    </Card>

    ## Path Parameters

    <ParamField path="id" type="string" required="true">
      The ID of the account connection to retrieve.
    </ParamField>

    ## Example

    <CodeGroup>
      ```json Response theme={null}
      {
          "id": "acon_XXXXX",
          "status": "created",
          "type": "direct",
          "first_name": "Paul",
          "last_name": "McCartney",
          "email": "paul@thebeatles.com",
          "display_name": "The Beatles",
          "permissions": [{"name": "payment.credit"}],
          "requested_permissions": ["payment.credit"],
          "verification_prompt": "Please enter the last 4 digits of your tax ID.",
          "user_data": {},
          "created_at": "2024-01-26T21:18:16.704Z",
          "updated_at": "2024-01-26T21:18:16.704Z",
          "destination": "Manifest Account - Paul McCartney"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Get by External ID">
    <Card icon="square-arrow-right" iconType="solid" color="#425BE0">
      **`GET`  /account-connection/external/:external\_id**<br />
      Get details of one of your enterprise's account connections by your own user identifier. (Must set `external_id` during account connection creation to use this method.)
    </Card>

    ## Path Parameters

    <ParamField path="external_id" type="string" required="true">
      User identifier from your system.
    </ParamField>

    ## Example

    <CodeGroup>
      ```json Response theme={null}
      {
          "id": "acon_XXXXX",
          "external_id": "AB789",
          "status": "created",
          "type": "direct",
          "first_name": "Paul",
          "last_name": "McCartney",
          "email": "paul@thebeatles.com",
          "display_name": "The Beatles",
          "permissions": [{"name": "payment.credit"}],
          "requested_permissions": ["payment.credit"],
          "verification_prompt": "Please enter the last 4 digits of your tax ID.",
          "user_data": {},
          "created_at": "2024-01-26T21:18:16.704Z",
          "updated_at": "2024-01-26T21:18:16.704Z",
          "destination": "Manifest Account - Paul McCartney",
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Update">
    <Card icon="square-pen" iconType="solid" color="#F1E067">
      **`PUT`  /account-connection/:id**<br />
      Update data associated with one of your enterprise's connections.
    </Card>

    ## Path Parameters

    <ParamField path="id" type="string" required="true">
      The ID of the account connection to update.
    </ParamField>

    ## Body Parameters

    <ParamField body="status" type="string">
      Update to `deleted` to deactivate this account connection.
    </ParamField>

    <ParamField body="first_name" type="string">
      Legal first name as represented in your system.
    </ParamField>

    <ParamField body="last_name" type="string">
      Legal last name as represented in your system.
    </ParamField>

    <ParamField body="email" type="string">
      Email address from your records.
    </ParamField>

    <ParamField body="display_name" type="string">
      Display name, visible to the creator. Examples are a band name, an online persona, or shortened version of the business name.
    </ParamField>

    <ParamField body="business_name" type="string">
      Legal business name from your records.
    </ParamField>

    <ParamField body="requested_permissions" type="string[]">
      Array of permissions to request from the user during the *Connect* flow. See below for details.
    </ParamField>

    <ParamField body="verification_prompt" type="string">
      Text to prompt your users for their verification answer. Examples below.
    </ParamField>

    <ParamField body="verification_answer" type="string">
      Required answer to the verification prompt. Manifest will correct for case sensitivity and trim excess white space before comparing the user's entered value. Any special formatting requirements should either be avoided or included in the verification prompt itself.
    </ParamField>

    <ParamField body="legacy_payout_method" type="string">
      You can set a legacy payment method on new account connections. See below for available options and required fields.
    </ParamField>

    <ParamField body="user_data" type="object">
      User defined data that can be attached to the object. See the [User Data](/reference/user-data) page for details.
    </ParamField>

    ## Example

    <CodeGroup>
      ```json Request theme={null}
      // PUT /account-connection/acon_XXXXX
      {
          "first_name": "Linda",
          "email": "linda@gmail.com"
      }
      ```

      ```json Response theme={null}
      {
          "id": "acon_XXXXX",
          "status": "active",
          "type": "direct",
          "first_name": "Linda",
          "last_name": "McCartney",
          "email": "linda@gmail.com",
          "display_name": "The Beatles",
          "permissions": [{"name": "payment.credit"}],
          "requested_permissions": ["payment.credit"],
          "verification_prompt": "Please enter the last 4 digits of your tax ID.",
          "user_data": {},
          "created_at": "2024-11-12T20:22:49.075Z",
          "updated_at": "2024-11-12T20:22:49.075Z",
          "destination": "Paul McCartney - Manifest Debit (*1234)"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="List">
    <Card icon="square-list" iconType="solid" color="#BDE1CD">
      **`GET`  /account-connection**<br />
      List all connections associated with your enterprise.
    </Card>

    ## Query Parameters

    <ParamField query="page" type="integer">
      The page number to return. Default is 1.
    </ParamField>

    <ParamField query="page_size" type="integer">
      The number of items to return per page. Default is 10.
    </ParamField>

    ## Example

    <CodeGroup>
      ```json Response theme={null}
      {
          "data": [
              {
                  "id": "acon_XXXXX",
                  "status": "active",
                  "type": "direct",
                  "first_name": "Paul",
                  "last_name": "McCartney",
                  "email": "paul@thebeatles.com",
                  "display_name": "The Beatles",
                  "permissions": [{"name": "payment.credit"}],
                  "requested_permissions": ["payment.credit"],
                  "verification_prompt": "Please enter the last 4 digits of your tax ID.",
                  "user_data": {},
                  "created_at": "2024-11-12T20:22:49.075Z",
                  "updated_at": "2024-11-12T20:22:49.075Z"
              },
              {
                  "id": "acon_YYYYY",
                  "status": "created",
                  "first_name": "John",
                  "last_name": "Lennon",
                  "email": "john@thebeatles.com",
                  "display_name": "The Beatles",
                  "requested_permissions": ["payment.credit"],
                  "verification_prompt": "Please enter the last 4 digits of your tax ID.",
                  "user_data": {},
                  "created_at": "2024-11-12T20:22:49.075Z",
                  "updated_at": "2024-11-12T20:22:49.075Z"
              },
              {
                  "id": "acon_ZZZZZ",
                  "status": "created",
                  "first_name": "George",
                  "last_name": "Harrison",
                  "email": "george@thebeatles.com",
                  "display_name": "The Beatles",
                  "requested_permissions": ["payment.credit"],
                  "verification_prompt": "Please enter the last 4 digits of your tax ID.",
                  "user_data": {},
                  "created_at": "2024-11-12T20:22:49.075Z",
                  "updated_at": "2024-11-12T20:22:49.075Z"
              },
              {
                  "id": "acon_00000",
                  "status": "active",
                  "type": "direct",
                  "first_name": "Ringo",
                  "last_name": "Starr",
                  "email": "ringo@thebeatles.com",
                  "display_name": "The Beatles",
                  "permissions": [{"name": "payment.credit"}],
                  "requested_permissions": ["payment.credit"],
                  "verification_prompt": "Please enter the last 4 digits of your tax ID.",
                  "user_data": {},
                  "created_at": "2024-11-12T20:22:49.075Z",
                  "updated_at": "2024-11-12T20:22:49.075Z"
              }
          ],
          "pagination": {
              "page": 1,
              "page_size": 10,
              "total": 4
          }
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>

***

# Properties

<ParamField path="id" type="string">
  Identifier for this account connection.
</ParamField>

<ParamField path="type" type="string">
  Type of account connection. One of `direct`, `ach`, or `wallet`. This field will be populated once the creator has connected to your enterprise and selected a payout method.
</ParamField>

<ParamField path="status" type="string">
  Status of account connection. One of `created`, `pending`, `active`, or `deleted`. Only users can activate their connection (through the Connect flow).
</ParamField>

<ParamField path="requested_permissions" type="string[]">
  Array of permissions to request from the user during the Connect flow. Possible values:

  | Permission       | Description                                              |
  | ---------------- | -------------------------------------------------------- |
  | `payment.credit` | Deposit to creator accounts.                             |
  | `payment.debit`  | Debit creator accounts. (type `direct` connections only) |

  Only ask for permissions you need to use; asking for more than you need might cause users to opt-out of connecting to you.
</ParamField>

<ParamField path="permissions" type="object[]">
  List of permissions granted by the creator during the Connect flow. Each permission object includes a `name` and an optional `expires_at`.
</ParamField>

<ParamField path="first_name" type="string">
  Legal first name from your records.
</ParamField>

<ParamField path="last_name" type="string">
  Legal last name from your records.
</ParamField>

<ParamField path="external_id" type="string">
  Optional user identifier from your system. If set, Manifest will enforce uniqueness, e.g. attempts to create a second account connection for the same user will fail.

  This should be a stable value like a User ID, not something that might change like an email address or phone number. This value should not contain any sensitive information.
</ParamField>

<ParamField path="email" type="string">
  Email address from your records. Note, this does not need to match the user's Manifest account email address, this is just an email address you use to communicate with this user. See sandbox testing for more information about using emails in sandbox.
</ParamField>

<ParamField path="display_name" type="string">
  Display name, visible to the creator. Examples are a band name, an online persona, or shortened version of the business name.
</ParamField>

<ParamField path="business_name" type="string">
  Legal business name from your records.
</ParamField>

<ParamField path="verification_prompt" type="string">
  Text to prompt your users for their verification answer. Examples:

  * Please enter the last 4 digits of your tax ID.
  * Please enter your Triangle Artist ID.
  * Please enter the last 4 digits of the bank account number where you currently receive your Triangle payments.
</ParamField>

<ParamField path="verification_answer" type="string">
  Required answer to the verification prompt. Manifest will correct for case sensitivity and trim excess white space before comparing the user's entered value. Any special formatting requirements should either be avoided or included in the verification prompt itself.
</ParamField>

<ParamField path="legacy_payout_method" type="object">
  An optional object describing legacy payout method details that can be set on new account connections. Used to migrate a creator’s existing payout method to Manifest. Details:

  <Expandable title="properties">
    ```json theme={null}
        // Example ACH Object
        {
            "type": "ach",
            "name_on_account": "Paul McCartney",
            "account_number": "12341234",
            "routing_number": "111000025",
            "account_type": "checking",
            "first_name": "Paul",
            "last_name": "McCartney",
            "street_line_1": "123 Main St.",
            "city": "Austin",
            "state_abbreviation": "TX",
            "postal_code": "78704",
            "ssn": "111-99-1234"
        }
    ```

    **ACH Details**

    * All fields in the example object are required. (There's also an optional `street_line_2`.)
    * In addition to the bank account information, the collected personal info is used by Manifest for tax purposes.
    * `account_number` has a maximum length of 17 characters.
    * `routing_number` must be a valid 9-digit routing number.
    * `account_type` must be checking or savings.
    * `postal_code` must be 5 digits.
    * `ssn` must have 9 digits, and include dash formatting.
  </Expandable>
</ParamField>

<ParamField path="destination" type="string">
  A plaintext label of the current destination account, suitable for display. (Not included in list endpoints.)
</ParamField>

<ParamField path="user_data" type="object">
  User defined data that can be attached to the object. See the [User Data](/reference/user-data) page for details.
</ParamField>