openapi: 3.0.0
info:
  title: Arch Client Accounts User Roles API
  version: 0.1.0
  description: "# Arch Client API Documentation\n\n## Getting Started\n\nTo get started, you need to request credentials from us at [api-support@arch.co](mailto:api-support@arch.co).\n\nWe'll send you a secret link with the following information\n- a Client ID\n- a Client Secret\n\n<table>\n\n<tr>\n<td>\n\n### Authentication\n\nTo authenticate, you'll need to make a POST request to the\n[`/client-api/auth/token`](#/Authentication/post_client_api_v0_auth_token) endpoint. Include your Client ID and Client Secret\nin the appropriate fields in the request body.\n\nUsing [curl](https://curl.se/), that request might look like this:\n\n**You should store and reuse this token for as long as it's valid.**\n\nYou can find the expiration time by decoding the [JWT](https://jwt.io/introduction), and checking the `exp` field, which is the expiration time represented as seconds since the Unix Epoch.\n\n</td>\n<td>\n\n```\nCLIENT_ID='<your client id>'\nCLIENT_SECRET='<your client secret>'\ncurl \\ \n  -X 'POST' \\\n  -H 'accept: application/json' \\\n  -H 'Content-Type: application/json' \\\n  -d \"{ \\\n    \\\"clientId\\\": \\\"$CLIENT_ID\\\", \\\n    \\\"clientSecret\\\": \\\"$CLIENT_SECRET\\\" \\\n  }\" \\\n  'https://arch.co/client-api/v0/auth/token'\n```\n\n</td>\n</tr>\n\n</table>\n\n\n<table>\n<tr>\n\n<td>\n\n### Querying\n\nOnce you have an access token, you can query the API as described below. The\nauthorization header should include your Access Token, prefixed by the word\n\"Bearer\". (e.g. `authorization: Bearer tokendata...`)\n\nHere's an example with curl.\n</td>\n\n<td>\n\n```\nACCESS_TOKEN='<access token from the previous step>'\ncurl -X 'GET' \\\n  'https://arch.co/client-api/v0/holdings' \\\n  -H 'accept: application/json' \\\n  -H \"authorization: Bearer $ACCESS_TOKEN\"\n```\n\n</td>\n\n</tr>\n</table>\n\n<table>\n<tr>\n<td>\n\n### Rate Limit\n\nThe Arch Client API is rate limited, measured in requests per minute. If you hit this limit, you will get an error 429 - Too Many Requests.\nTo address this, consider spacing out your requests.\n\nTo check your API user's rate limit status, view the response headers on an API request. The headers are as follows:\n\n* #### RateLimit-Policy\n  The max number of requests allowed over a specified window of time. Format: [number of requests];w=[window of time in seconds]\n\n* #### RateLimit-Limit\n  The max number of requests allowed over the current window of time. Format: [number of requests]\n\n* #### RateLimit-Remaining\n  The remaining number of requests that the user is allowed to make over the current window of time. Format: [number of requests]\n\n* #### RateLimit-Reset\n  The number of seconds remaining until the window of time resets. Format: [number of seconds]\n\n</tr>\n</td>\n</table>\n\n## Pages\n\nMany Arch objects can be returned in lists called Pages. By default, a Page\ncontains up to 25 objects. Some endpoints allow the user to increase the\nnumber of requested objects up to 1000.\n\n## Concepts\n\n<table>\n\n<tr>\n<td>\n\n### Users\nAn individual's personal access to Arch.\n\n### Accounts\nRepresents a collection of investments, which users are assigned to.\n\n### Holdings\n\nHoldings are investments, or any other piece of property (real estate, real assets, bank accounts, etc.). Each holding represents a\nrelationship between an Investing Entity and an Issuing Entity, where the\nInvesting Entity has invested in one of the Offerings that the Issuing Entity\noffers.\n\n  * #### Edge Cases\n    Sometimes, a holding may not directly represent one of your investments. For example, there might be a holding that contains tax documents related to a charitable contribution. Holdings aren't always direct investments as well, it's not uncommon to see a holding representing a Fund -> Fund investment.\n\n### Investing Entities\n\nThese are the entities that own holdings. Arch receives and processes investments on behalf of the Investing Entity.\n\n</td>\n<td>\n<img src=\"../static/images/user.png\" />\n</td>\n</tr>\n\n\n<tr>\n\n</tr>\n\n\n\n<tr>\n<td>\n\n### Issuing Entities\n\nThese are the entities that issue holdings, which you are investing in. They issue documents and updates that Arch receives and processes. Typically, an issuing entity is PE fund, Hedge Fund, etc. We also consider banks to be issuing entities who issue bank account holdings.\n\n  * #### Insights\n    Insights are third party data about issuing entites powered by our partner <a href=\"https://www.preqin.com\">Preqin</a>. Insights are accessible through the corresponding issuing entity.\n### Offerings\n\nThese represent the different investing opportunities that an Issuing Entity offers. For example, Uber might offer both a Seed round, and a later Series A round of investments. That would be a singular issuing entity (Uber), with two separate offerings (Seed, Series A).\n\n</td>\n<td>\n  <img src=\"../static/images/issuing.png\" />\n</td>\n</tr>\n\n<tr>\n\n<td>\n\n### Activities\n\nArch processes many types of documents and updates to your investments.\nCollectively, these updates are known as an \"Activity.\" Examples of activities\ninclude events like:\n- Account Statement Received\n- Capital Call Requested/Paid\n- Distribution Notice/Paid\n- Investor Letter\n\nWe process these activities and extract various finanicial facts about your activities. Examples of these finanical facts are:\n\n- Total Value (Capital Account)\n- Total Contribution\n- Total Distribution\n\n### Cash Flows\n\nThese represent money flowing into or out of your investments. For example, capital calls or distributions. One cash flow can be related to one or more activities.\nOne cashflow can also be related to one or more \"allocations.\" \n\nEach cash flow is also linked to one or more \"allocations,\" which represent the specific movement of money. An allocation has a specific type and describes an event initiated by the LP or GP. Each allocation has a direction: -1 (indicating cash flowing into the investment), 1 (indicating cash flowing out), or infrequently, 0 (no cash movement). The sum of the products of each allocation times its direction equals the total cash flow between the LP and the investment. These allocations can impact an investment's total value, contribution, remaining commitment, and distribution.\n\nTypes of allocations include:\n\n- Capital Calls\n- Expenses\n- Cash Distributions\n- Expenses\n\n#### Point in Time Valuation vs. Estimated Value\n\nPoint in time valuation and estimated value report the value of an investment at different times. Point in time valuation returns the value of an investment exactly as reported on the most recent statement, while estimated value starts with the most recent statement value and adjusts according to the capital calls that have occurred since the date of the most recent statement.\n\n### Tasks\n\nA specific investment related action that the user must complete. For example, confirming a new investment or verifying wire instructions.\n\n</td>\n<td>\n  <img src=\"../static/images/cashflow.png\" />\n</td>\n\n</tr>\n</table>\n\n<table>\n\n<td>\n\n### Lookthroughs\n\n**Premium Feature:** Arch can track and display the <u title=\"An SOI returns a list of your investments, including metrics such as number of shares, fair value, and liquidity.\">schedule of investments (SOI)</u> for any holdings you\nown. This allows you to \"look through\" the holdings you own to the\ninvestments that your holding made. This can make it easier to track your\n\"true\" exposure.\n\n### User Roles\n\nYou grant access to accounts, investing entities, and holdings with user roles. Each role grants a specific set of permissions.\n\n**Available role types for POST and DELETE requests:**\n- Full Access\n- Tax Only\n- Restricted Tax Only\n- View Only\n- File Only\n- Informed Tax Only\n- View Only with Task Completion\n- Restricted Investor\n- Investment Team\n\n**Note:** GET requests may return additional universal and custom role types beyond those listed above, depending on your Arch configuration.\n\nFor more information about permissions associated with roles, please refer to [Arch Permissions by User Type](https://intercom.help/archhelp/en/articles/8975969-arch-permissions-by-user-type).\n\n## Standards\n\n### Time Zone\n\nDates and times are in UTC unless otherwise specified.\n\n</td>\n\n</table>\n"
servers:
- url: /
host: arch.co
tags:
- name: User Roles
paths:
  /client-api/v0/user-roles:
    get:
      operationId: get-list-user-roles
      summary: Get a paginated list of user roles
      parameters:
      - name: limit
        in: query
        description: The number of user roles to return
        schema:
          type: integer
          default: 25
          maximum: 1000
      - name: offset
        in: query
        description: The number of user roles to skip before collecting results
        schema:
          type: integer
          default: 0
          minimum: 0
      - name: accountIds
        in: query
        description: Only include roles on one of the account ids provided. Applies only to roles where `objectType` is `account`.
        example: 1,2,3,4
        schema:
          type: array
          items:
            type: integer
      - name: investingEntityIds
        in: query
        description: Only include roles on one of the investing entity ids provided. Applies only to roles where `objectType` is `investingEntity`.
        example: 10,12,13,14
        schema:
          type: array
          items:
            type: integer
      - name: userIds
        in: query
        description: Only include roles on one of the user ids provided.
        example: 1,2,3,4
        schema:
          type: array
          items:
            type: integer
      - name: objectType
        in: query
        description: 'Which type of object to include. Allowed values: `account` or `investingEntity`.


          **This field defaults to `account` for backwards compatibility.** Callers that want

          investing-entity or holding roles must provide this parameter.

          '
        example: investingEntity
        schema:
          type: array
          items:
            type: string
            enum:
            - account
            - investingEntity
      - name: roleType
        in: query
        description: 'Filter results to only include roles matching the specified portal name.

          Spaces and special characters must be URL-encoded.


          Example values (as they appear in the database):

          - `Tax Only` (in URL: `?roleType=Tax%20Only`)

          - `Full Access` (in URL: `?roleType=Full%20Access`)

          '
        example: Tax%20Only
        schema:
          type: string
      security:
      - BearerAuth: []
      description: 'Returns a paginated list of **direct** user roles. Only shows roles

        explicitly granted on accounts, investing entities, or holdings.

        Access inherited via parent folders is not expanded into this list.


        Each returned role identifies its target via a single `objectRef` (an `AccountRef`,

        `InvestingEntityRef`, or `HoldingRef`) along with an `objectType` discriminator. The

        legacy `accountId` and `userUrl` fields are still populated where applicable but are

        deprecated; new integrations should read `objectRef` and `userRef` instead.

        '
      tags:
      - User Roles
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserRoleList'
        '403':
          description: No permission to view access to some accounts
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                    example: No permission to view access to some accounts
        '500':
          description: Internal server error.
    post:
      summary: Create new user roles
      security:
      - BearerAuth: []
      tags:
      - User Roles
      requestBody:
        required: true
        description: A list of new user roles to create.
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/RequestUserRole'
      responses:
        '200':
          description: Success
        '400':
          description: Missing required fields
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
        '403':
          description: No permission to invite to some accounts
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                    example: No permission to invite to some accounts
        '409':
          description: Some user roles already exist
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                    example: Some user roles already exist
        '500':
          description: Internal server error.
    delete:
      summary: Remove user roles
      security:
      - BearerAuth: []
      tags:
      - User Roles
      requestBody:
        required: true
        description: A list of user roles to remove.
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/RequestUserRole'
      responses:
        '200':
          description: Success
        '400':
          description: Missing required fields
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
        '403':
          description: No access to some accounts
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                    example: No access to some accounts
        '409':
          description: Some user roles don't exist yet
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                    example: Some user roles don't exist yet
        '500':
          description: Internal server error.
components:
  schemas:
    HoldingRef:
      type: object
      required:
      - kind
      - id
      - url
      properties:
        kind:
          type: string
          enum:
          - holding-ref
        id:
          type: number
          description: The ID of the referenced holding
          example: 112
        url:
          type: string
          description: A relative url to the referenced holding
          example: /holdings/112
        name:
          type: string
          description: The name of the referenced holding
          example: Holding 112
    RequestUserRole:
      type: object
      required:
      - accountId
      - userId
      - roleType
      properties:
        accountId:
          type: integer
          example: 56
        userId:
          type: integer
          example: 15
        roleType:
          $ref: '#/components/schemas/RoleType'
          example: Tax Only
    ResponseUserRole:
      type: object
      required:
      - kind
      - objectRef
      - userRef
      - roleType
      properties:
        kind:
          type: string
          enum:
          - user-role
        objectRef:
          description: 'Reference to the object this role applies to. The concrete ref can be an `AccountRef`,

            an `InvestingEntityRef`, or a `HoldingRef`. The `kind` field on the ref can be used

            as a discriminator.

            '
          oneOf:
          - $ref: '#/components/schemas/AccountRef'
          - $ref: '#/components/schemas/InvestingEntityRef'
          - $ref: '#/components/schemas/HoldingRef'
          discriminator:
            propertyName: kind
            mapping:
              account-ref: '#/components/schemas/AccountRef'
              investing-entity-ref: '#/components/schemas/InvestingEntityRef'
              holding-ref: '#/components/schemas/HoldingRef'
        accountId:
          type: integer
          deprecated: true
          description: '**Deprecated.** Use `objectRef.id` instead. Only populated for

            account roles; omitted for investing-entity and holding roles.

            Retained for backwards compatibility.

            '
          example: 56
        userRef:
          $ref: '#/components/schemas/UserRef'
        userUrl:
          type: string
          deprecated: true
          description: '**Deprecated.** Use `userRef.url` instead. Retained for backwards compatibility.

            '
          example: /users/15
        roleType:
          type: string
          description: 'The role type. May include additional universal and custom role types beyond those

            available for POST and DELETE requests, depending on your Arch configuration.

            '
          example: Tax Only
    AccountRef:
      type: object
      required:
      - kind
      - id
      - url
      properties:
        kind:
          type: string
          enum:
          - account-ref
        id:
          type: number
          description: The ID of the referenced account
          example: 56
        url:
          type: string
          description: A relative url to the referenced account
          example: /account/56
        name:
          type: string
          description: The name of the referenced account
          example: Account 56
    UserRef:
      type: object
      required:
      - kind
      - id
      - url
      properties:
        kind:
          type: string
          enum:
          - user-ref
        id:
          type: integer
          description: The ID of the referenced user
          example: 15
        url:
          type: string
          description: A relative url to the referenced user
          example: /users/15
        name:
          type: string
          description: The display name of the referenced user
          example: John Smith
    UserRoleList:
      type: object
      required:
      - kind
      - selfUrl
      - contents
      properties:
        kind:
          type: string
          description: page
        selfUrl:
          type: string
          description: The relative URL for accessing this resource via the Arch Client API
          example: /user-roles
        contents:
          type: array
          items:
            $ref: '#/components/schemas/ResponseUserRole'
        prev:
          type: string
          description: The relative URL for the previous page of user roles
          example: null
        next:
          type: string
          description: The relative URL for the next page of user roles
          example: /user-roles?offset=25
    InvestingEntityRef:
      type: object
      required:
      - kind
      - id
      - url
      properties:
        kind:
          type: string
          enum:
          - investing-entity-ref
        id:
          type: number
          description: The ID of the referenced investing entity
          example: 711
        url:
          type: string
          description: A relative url to the referenced investing entity
          example: /investing-entities/711
        name:
          type: string
          description: The name of the referenced investing entity
          example: Investing Entity 711
    RoleType:
      type: string
      example: Tax Only
      enum:
      - Full Access
      - Tax Only
      - Restricted Tax Only
      - View Only
      - File Only
      - Informed Tax Only
      - View Only with Task Completion
      - Restricted Investor
      - Investment Team
      description: 'The type of role. Only the values listed below are accepted.

        '
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT