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

# Upsert linked account

This API updates the details of an existing linked account or creates a new one if no account exists for the provided linked account ID.

## Request description

#### Body Parameters

<ParamField body="linked_account_id" type="string" required>
  Unique customer identification id. For Eg: [markwood@some\_email.com](mailto:markwood@some_email.com)
</ParamField>

<ParamField body="name" type="string">
  User name. for Eg: Mark Wood
</ParamField>

<ParamField body="your_app" type="object">
  An object containing the details of your application associated with your account.

  <Warning>
    Passing an empty `your_app` object without `auth_credentials` will throw an API Error.
  </Warning>

  <Tip>It is recommended to either do not pass your\_app object or pass it with auth\_credentials.</Tip>

  <Expandable title="properties">
    <ResponseField name="auth_credentials" type="object">
      API Credentials of your customers which will be used to make calls to your APIs.

      <Tip>
        These credentials can have any key name that you want to set for your own APIs like email, password, base-url etc.
      </Tip>

      <Expandable title="example properties" defaultOpen="true">
        <ResponseField name="x-api-key" type="string">
          Sample key name for credentials
        </ResponseField>

        <ResponseField name="base-url" type="string">
          Sample key name for credentials
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField body="udf" type="object">
  An object containing user-defined fields (if any) associated with the linked account.

  <Expandable title="example properties">
    <ResponseField name="sample_key_1" type="string">
      Example credentials
    </ResponseField>

    <ResponseField name="base-sample_key_2" type="string">
      Example credentials
    </ResponseField>
  </Expandable>
</ParamField>

## Response description

<Tabs>
  <Tab title="200">
    <ResponseField name="_id" type="string">
      index id of the record created
    </ResponseField>

    <ResponseField name="associated_org" type="string">
      Organization Id
    </ResponseField>

    <ResponseField name="account_id" type="string">
      Linked account id
    </ResponseField>

    <ResponseField name="environment" type="string">
      Environment in which the account was created
    </ResponseField>

    <ResponseField name="name" type="string">
      Name of the linked account
    </ResponseField>

    <ResponseField name="udf" type="array">
      Initial values passed while creating the linked account. User can pass any values of primitive datatypes.
    </ResponseField>

    <ResponseField name="createdAt" type="date">
      Creation time
    </ResponseField>

    <ResponseField name="updatedAt" type="date">
      \`Last update time
    </ResponseField>

    <ResponseField name="__v" type="integer" />
  </Tab>

  <Tab title="Error">
    <ResponseField name="status_code" type="integer">
      System generated status Code
    </ResponseField>

    <ResponseField name="http_error_type" type="string">
      System generated error type
    </ResponseField>

    <ResponseField name="error_code" type="string">
      Specific error code to identify the error
    </ResponseField>

    <ResponseField name="message" type="string">
      Error message
    </ResponseField>

    <ResponseField name="request_id" type="string">
      System generated request id
    </ResponseField>
  </Tab>
</Tabs>

<ResponseExample>
  ```JSON 200 theme={null}
  {
      "_id": "63cabcc596d0d10508a69bdf",
      "associated_org": "63c93da0b46b7243785a1e17",
      "account_id": "12345678",
      "environment": "test",
      "name": "Mark Wood",
      "udf": [
          {
              "key_name": "some_key1",
              "key_value": "Updated Value",
              "_id": "64d5d69bfb78da0950f5e18f",
              "updatedAt": "2023-08-11T06:35:07.574Z",
              "createdAt": "2023-08-11T06:35:07.574Z"
          },
          {
              "key_name": "some_key2",
              "key_value": "some data 2",
              "_id": "64d5d69bfb78da0950f5e190",
              "updatedAt": "2023-08-11T06:35:07.574Z",
              "createdAt": "2023-08-11T06:35:07.574Z"
          },
          {
              "key_name": "some_key3",
              "key_value": "some data 3",
              "_id": "64d5d69bfb78da0950f5e191",
              "updatedAt": "2023-08-11T06:35:07.574Z",
              "createdAt": "2023-08-11T06:35:07.574Z"
          }
      ],
      "createdAt": "2023-01-20T16:09:41.700Z",
      "updatedAt": "2023-08-11T06:35:07.574Z",
      "__v": 326
  }
  ```

  ```JSON 400 theme={null}
  {
      "status_code": 400,
      "http_error_type": "BAD_REQUEST",
      "error_code": "SERVER_ERROR",
      "message": "Duplicate Auth key_name not allowed",
      "request_id": "89bd1675-a826-46cb-9210-6cb2ae169f67"
  }
  ```

  ```JSON 401 theme={null}
  {
      "status_code": 401,
      "http_error_type": "UNAUTHORIZED",
      "error_code": "SERVER_ERROR",
      "message": "Invalid Credentials"
      "request_id": "89bd1675-a826-46cb-9210-6cb2ae169f67"
  }
  ```

  ```JSON 500 theme={null}
  {
      "status_code": 500,
      "http_error_type": "BAD_REQUEST",
      "error_code": "INTERNAL_SERVER_ERROR",
      "message": "A valid app_id is required",
      "request_id": "89bd1675-a826-46cb-9210-6cb2ae169f67"
  }
  ```
</ResponseExample>