openapi: 3.0.0
info:
title: Arch Client Accounts Holdings 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: Holdings
description: Read holding data and push new investments.
paths:
/client-api/v0/holdings:
get:
summary: Get a paginated list of holdings
parameters:
- name: limit
in: query
description: The number of holdings to return
schema:
type: integer
default: 25
maximum: 1000
- name: offset
in: query
description: The number of holdings to skip before collecting results
schema:
type: integer
default: 0
minimum: 0
- name: includeMetrics
in: query
description: Include financial metrics (IRR, TVPI, and DPI) in the response
required: false
schema:
type: boolean
- name: includeOwnership
in: query
description: Include ownership info. Will cause an error if holding is not set up for lookthrough extraction. Provides the ownership percentage of the fund, and the issuing entity to query to access the underlying portfolio companies.
required: false
schema:
type: boolean
- name: includeTransferInfo
in: query
description: Include transfer relationships (transferInfo) for each holding in the response. When omitted or false, the transferInfo field is not returned.
required: false
schema:
type: boolean
- name: includeBlackDiamondInfo
in: query
description: Include Black Diamond info in the response
required: false
schema:
type: boolean
- name: includeCustomFields
in: query
description: Set this to true to receive custom fields associated with the holding.
schema:
type: boolean
- name: includeAddeparInfo
in: query
description: Include Addepar info in the response
required: false
schema:
type: boolean
- name: includeArchwayInfo
in: query
description: Include Archway info in the response
required: false
schema:
type: boolean
- name: includeBurgissInfo
in: query
description: Include Burgiss info in the response
required: false
schema:
type: boolean
- name: includeTamaracInfo
in: query
description: Include Tamarac info in the response
required: false
schema:
type: boolean
- name: includeOrionInfo
in: query
description: Include Orion info in the response
required: false
schema:
type: boolean
- name: investingEntityIds
in: query
description: Will filter the output to only include holdings relevant to one of the investing entity ids in the provided argument
example: 1,2,3,4
schema:
type: string
- name: issuingEntityIds
in: query
description: Will filter the output to only include holdings relevant to one of the issuing entity ids in the provided argument
example: 1,2,3,4
schema:
type: string
- name: accountIds
in: query
description: Will filter the output to only include holdings relevant to one of the account ids in the provided argument
example: 1,2,3,4
schema:
type: string
- name: name
in: query
description: Filter the output for holding names that include the search term.
schema:
type: string
- name: beforeEndDate
in: query
description: Filter the output for holdings with an end date before the queried date.
example: '2024-05-22T21:15:55.306Z'
schema:
type: string
format: date-time
- name: afterEndDate
in: query
description: Filter the output for holdings with an end date after the queried date.
example: '2024-05-22T21:15:55.306Z'
schema:
type: string
format: date-time
- name: beforeStartDate
in: query
example: '2024-05-22T21:15:55.306Z'
description: Filter the output for holdings with a start date before the queried date.
schema:
type: string
format: date-time
- name: afterStartDate
in: query
example: '2024-05-22T21:15:55.306Z'
description: Filter the output for holdings with a start date after the queried date.
schema:
type: string
format: date-time
- name: includeTax
in: query
description: Controls whether tax placeholder holdings are included in the results. Use "Only" to return only tax placeholder holdings, "Include" to include them along with regular holdings, or "Exclude" to exclude them entirely. Defaults to Exclude.
required: false
schema:
type: string
enum:
- Only
- Include
- Exclude
default: Exclude
- name: valueAsOfDate
in: query
description: Return financial values as of this date (YYYY-MM-DD). When omitted, the latest values are returned.
required: false
schema:
type: string
format: date-time
example: 2024-12-31T00:00Z
- name: valueCalculationMethod
in: query
description: Controls how financial values are calculated. "statementsOnly" pulls the value directly from the latest statement before the "as of" date; "includeCashFlows" (the default) uses that account statement, plus/minus and subsequent cash flows up to the "as of" date.
required: false
schema:
type: string
enum:
- includeCashFlows
- statementsOnly
default: includeCashFlows
security:
- BearerAuth: []
description: Return a paginated list of holdings
tags:
- Holdings
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/HoldingList'
'500':
description: Internal server error.
post:
summary: Add a new holding to Arch
security:
- BearerAuth: []
description: Creates a new holding and returns the URL, if successful. Financial values are assumed to be in dollars
tags:
- Holdings
requestBody:
description: Details of the new holding to create.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NewHolding'
responses:
'201':
description: Created
headers:
Location:
schema:
type: string
description: URL of the new holding
'500':
description: Internal server error.
/client-api/v0/holdings/{id}:
get:
summary: Get data for a specific holding
security:
- BearerAuth: []
description: Returns the data for a specific holding, if the user has access through the access token.
tags:
- Holdings
parameters:
- name: id
in: path
description: A specific holding to query
required: true
schema:
type: integer
- name: includeOwnership
in: query
description: Include ownership info. Will cause an error if holding is not set up for lookthrough extraction. Provides the ownership percentage of the fund, and the issuing entity to query to access the underlying portfolio companies.
required: false
schema:
type: boolean
- name: includeTransferInfo
in: query
description: Include transfer relationships (transferInfo) for each holding in the response. When omitted or false, the transferInfo field is not returned.
required: false
schema:
type: boolean
- name: includeMetrics
in: query
description: Include financial metrics in the response
required: false
schema:
type: boolean
- name: includeBlackDiamondInfo
in: query
description: Include Black Diamond info in the response
required: false
schema:
type: boolean
- name: includeCustomFields
in: query
description: Set this to true to receive custom fields associated with the holding.
schema:
type: boolean
- name: includeAddeparInfo
in: query
description: Include Addepar info in the response
required: false
schema:
type: boolean
- name: includeArchwayInfo
in: query
description: Include Archway info in the response
required: false
schema:
type: boolean
- name: includeBurgissInfo
in: query
description: Include Burgiss info in the response
required: false
schema:
type: boolean
- name: includeTamaracInfo
in: query
description: Include Tamarac info in the response
required: false
schema:
type: boolean
- name: includeOrionInfo
in: query
description: Include Orion info in the response
required: false
schema:
type: boolean
- name: includeTax
in: query
description: Controls whether tax placeholder holdings are included in the results. Use "Only" to return only tax placeholder holdings, "Include" to include them along with regular holdings, or "Exclude" to exclude them entirely. Defaults to Exclude.
required: false
schema:
type: string
enum:
- Only
- Include
- Exclude
default: Exclude
- name: valueAsOfDate
in: query
description: Return historical financial values as of this date (YYYY-MM-DD). When omitted, latest values are returned.
required: false
schema:
type: string
format: date-time
example: 2024-12-31T00:00Z
- name: valueCalculationMethod
in: query
description: Controls how financial values are calculated. "includeCashFlows" uses account statements and cash flows; "statementsOnly" pulls the value directly from the latest statement before the "as of" date. Defaults to "includeCashFlows".
required: false
schema:
type: string
enum:
- includeCashFlows
- statementsOnly
default: includeCashFlows
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Holding'
'404':
description: Holding id not found or is inaccessible to the user
'500':
description: Internal server error.
/client-api/v0/holdings/fund:
post:
operationId: create-funds-holding
summary: Add a new funds or real estate holding to Arch
security:
- BearerAuth: []
description: 'Creates a new funds or real estate holding (direct ownership) and returns the holding. Financial values should be provided in USD (currently the only supported currency). Values can be negative. No defaults are applied - values are stored exactly as provided. Note: offeringInfo should be null for Real Estate - Direct Ownership.
'
tags:
- Holdings
requestBody:
description: Details of the new funds holding to create
required: true
content:
application/json:
schema:
type: object
required:
- investmentInfo
properties:
investmentInfo:
type: object
required:
- investmentType
- investingEntityId
- entityInput
- investmentSettings
properties:
investmentType:
$ref: '#/components/schemas/InvestmentTypeEnum'
investingEntityId:
type: integer
minimum: 1
example: 56
entityInput:
description: 'Specify the firm and issuing entity by name (inputMethod: "byName") or by Offering Id (inputMethod: "byId"). When using byName, Arch will match against existing offerings; if found, that offering is reused, otherwise a new one is created.
**Important:** When using byId with an existing offering, offering-level fields (taxDocumentInfo, marketInfo) cannot be provided and will throw a validation error. When using byName and it matches an existing offering, any provided offering-level fields will be silently ignored. Investment-specific fields (like feeInfo) can always be set.
(Disclaimer: Offering Ids are subject to change after investment creation, up to date Offering Ids can be obtained from the `/offerings` endpoint)
'
oneOf:
- type: object
required:
- inputMethod
- firmName
- issuingEntityName
properties:
inputMethod:
type: string
enum:
- byName
firmName:
type: string
maxLength: 255
example: Sequoia Capital
issuingEntityName:
type: string
maxLength: 255
example: Example Fund LP
additionalProperties: false
- type: object
required:
- inputMethod
- offeringId
properties:
inputMethod:
type: string
enum:
- byId
offeringId:
type: integer
minimum: 1
example: 8412
additionalProperties: false
investmentSettings:
type: object
required:
- linkingMethod
properties:
enableLookthrough:
type: boolean
description: Whether to enable lookthroughs for this holding
default: false
example: false
linkingMethod:
$ref: '#/components/schemas/LinkingMethodEnum'
notes:
type: string
example: Invested in Series B round
financials:
type: object
description: 'Financial values for the holding. If provided with valueAsOfDate, a "Value Provided by Investor" activity will be created with these values. Validation rules: valueAsOfDate is required if any financial values are provided, and at least one financial value is required if valueAsOfDate is provided. If no financials are provided, only an "Investment Added to Arch" activity is created.
'
properties:
valueAsOfDate:
type: string
format: date
description: 'Required if any financial values are provided. Cannot be provided without at least one financial value.
'
example: '2024-03-15'
capitalAccount:
allOf:
- $ref: '#/components/schemas/NewFinancialValue'
- description: Total value of the holding.
initialCommitment:
allOf:
- $ref: '#/components/schemas/NewFinancialValue'
- description: Total commitment to the holding.
totalContribution:
allOf:
- $ref: '#/components/schemas/NewFinancialValue'
- type: object
properties:
quantity:
minimum: 0
description: Total contributions made towards the commitment. Must be non-negative.
outstandingCommitment:
allOf:
- $ref: '#/components/schemas/NewFinancialValue'
- description: Total contributions required to meet the commitment.
totalDistributions:
allOf:
- $ref: '#/components/schemas/NewFinancialValue'
- description: Total distributions made from the holding.
recallableDistributions:
allOf:
- $ref: '#/components/schemas/NewFinancialValue'
- description: Total distributions that can be recalled.
customFields:
type: object
additionalProperties:
type: object
required:
- value
properties:
value:
oneOf:
- type: string
- type: number
- type: boolean
example:
'707':
value: Technology
'709':
value: 123.45
addeparInfo:
type: object
description: 'Addepar integration information. If you provide addeparInfo without an accountId, the API
will verify that an Addepar account mapping exists for the investing entity''s account. If no
mapping exists, a 400 error will be returned - please contact Arch to set up the account mapping.
'
properties:
accountId:
type: integer
minimum: 1
example: 123456
ownerEntityId:
type: integer
minimum: 1
example: 789012
ownedEntityId:
type: integer
minimum: 1
example: 345678
additionalProperties: false
contactInfo:
type: object
required:
- email
properties:
firstName:
type: string
maxLength: 255
example: John
lastName:
type: string
maxLength: 255
example: Smith
email:
type: string
format: email
maxLength: 255
example: john.smith@example.com
additionalProperties: false
transferInfo:
$ref: '#/components/schemas/TransferInfoInput'
offeringInfo:
type: object
description: "Offering information including tax documents and fee details.\n\n\n**IMPORTANT:**\n1. offeringInfo should be null for Real Estate - Direct Ownership.\n2. When using byId with an existing offering, taxDocumentInfo cannot be provided and will throw a validation error.\n When using byName and it matches an existing offering, taxDocumentInfo will be silently ignored.\n Investment-specific fields like feeInfo can always be set\n"
properties:
taxDocumentInfo:
type: object
description: Optional. If provided, both taxDocumentType and taxDocumentStartYear are required.
required:
- taxDocumentType
- taxDocumentStartYear
properties:
taxDocumentType:
$ref: '#/components/schemas/TaxDocumentTypeEnum'
taxDocumentStartYear:
type: integer
minimum: 1900
maximum: 2100
example: 2024
feeInfo:
type: object
properties:
managementFee:
type: number
minimum: 0
maximum: 100
example: 2
carryFee:
type: number
minimum: 0
maximum: 100
example: 20
returnExpectation:
type: number
minimum: 0
maximum: 100
example: 15
example:
investmentInfo:
investmentType: Fund (Partnership Equity)
investingEntityId: 56
entityInput:
inputMethod: byName
firmName: Sequoia Capital
issuingEntityName: Sequoia Fund XIV
investmentSettings:
enableLookthrough: true
linkingMethod: LOA
notes: Committed in Q1 2024
financials:
valueAsOfDate: '2024-01-15'
initialCommitment:
quantity: 5000000
contactInfo:
firstName: John
lastName: Smith
email: john.smith@sequoia.com
offeringInfo:
taxDocumentInfo:
taxDocumentType: K-1
taxDocumentStartYear: 2024
feeInfo:
managementFee: 2
carryFee: 20
returnExpectation: 25
responses:
'200':
description: Holding created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Holding'
'400':
description: Bad Request
content:
application/json:
schema:
type: object
required:
- message
properties:
message:
type: string
example: 'Missing required field: email'
'500':
description: Internal Server Error
/client-api/v0/holdings/company:
post:
operationId: create-company-holding
summary: Add a new company holding to Arch
security:
- BearerAuth: []
description: 'Creates a new company holding (direct equity, SAFE, convertible note, etc.) and returns the holding. Financial values should be provided in USD (currently the only supported currency). Values can be negative. No defaults are applied - values are stored exactly as provided. Note: sharesInfo
# --- truncated at 32 KB (99 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/arch/refs/heads/main/openapi/arch-holdings-api-openapi.yml