Arch Tasks API

openapi: 3.2.0
info:
  title: Arch Client Tasks API
  version: 0.1.0
  description: '# Arch Client API Documentation


    ## Getting Started


    To get started, you need to request credentials from us at api-support@arch.co.'
servers:
- url: /
host: arch.co
tags:
- name: Tasks
paths:
  /client-api/v0/tasks/{id}:
    get:
      summary: Get a task by ID
      security:
      - BearerAuth: []
      description: Get a task by ID.
      tags:
      - Tasks
      parameters:
      - name: id
        in: path
        description: The ID of the task to get.
        required: true
        schema:
          type: integer
      - name: includeWireInstructions
        in: query
        example: true
        description: Whether to include Wire Verification in the data. Please contact Arch to enable this parameter.
        schema:
          type: boolean
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '404':
          description: Task not found or caller not authorized to view task.
          content:
            text/plain:
              schema:
                type: string
      operationId: getClientApiV0TasksById
      x-operation-id-source: derived
  /client-api/v0/tasks/{id}/complete:
    post:
      summary: Complete a task by ID
      security:
      - BearerAuth: []
      description: Complete a task by ID.
      tags:
      - Tasks
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                completionDate:
                  type: string
                  format: date
                  description: The date this task will be marked as completed at. Should be in the "YYYY-MM-DD" format.
                  example: '2024-03-27'
      parameters:
      - name: id
        in: path
        description: The ID of the task to complete.
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                type: string
        '400':
          description: Malformed body or task already completed.
          content:
            text/plain:
              schema:
                type: string
        '404':
          description: Task not found or caller not authorized to complete task.
          content:
            text/plain:
              schema:
                type: string
        '500':
          description: Error completing task.
          content:
            text/plain:
              schema:
                type: string
      operationId: postClientApiV0TasksByIdComplete
      x-operation-id-source: derived
  /client-api/v0/tasks:
    get:
      summary: Get all tasks for the user
      security:
      - BearerAuth: []
      description: Get all tasks for the user.
      tags:
      - Tasks
      parameters:
      - name: limit
        in: query
        description: The number of activities to return
        schema:
          type: integer
          default: 25
          maximum: 1000
      - name: offset
        in: query
        description: The number of activities to skip before collecting results
        schema:
          type: integer
          default: 0
          minimum: 0
      - name: holdingIds
        in: query
        example: 1,2,3,4
        description: Filter the output for tasks related to holdings with ids in the provided argument
        schema:
          type: string
      - name: investingEntityIds
        in: query
        example: 1,2,3,4
        description: Filter the output for tasks related to investing entities with ids in the provided argument
        schema:
          type: string
      - name: issuingEntityIds
        in: query
        example: 1,2,3,4
        description: Filter the output for tasks related to issuing entities with ids in the provided argument
        schema:
          type: string
      - name: accountIds
        in: query
        example: 1,2,3,4
        description: Will filter the output to only include holdings relevant to one of the account ids in the provided argument
        schema:
          type: string
      - name: assignedToUsers
        in: query
        example: 1,2,3,4
        description: Filter the output for tasks with an assigned user with a matching id on one of the provided ids
        schema:
          type: string
      - name: completedByUsers
        in: query
        example: 1,2,3,4
        description: Filter the output for tasks completed by a user with a matching id on one of the provided ids
        schema:
          type: string
      - name: beforeDueDate
        in: query
        description: Filter the output for tasks with a due time before the queried date-time.
        example: '2024-05-22T21:15:55.306Z'
        schema:
          type: string
          format: date-time
      - name: afterDueDate
        in: query
        description: Filter the output for tasks with a due time after the queried date-time.
        example: '2024-05-22T21:15:55.306Z'
        schema:
          type: string
          format: date-time
      - name: beforeCompletionDate
        in: query
        description: Filter the output for tasks with a completion date before the queried date-time.
        example: '2024-05-22T21:15:55.306Z'
        schema:
          type: string
          format: date-time
      - name: afterCompletionDate
        in: query
        description: Filter the output for tasks with a completion date after the queried date-time.
        example: '2024-05-22T21:15:55.306Z'
        schema:
          type: string
          format: date-time
      - name: beforeCreationTime
        in: query
        description: Filter the output for tasks with a creation time before the queried date-time.
        example: '2024-05-22T21:15:55.306Z'
        schema:
          type: string
          format: date-time
      - name: afterCreationTime
        in: query
        description: Filter the output for tasks with a creation time after the queried date-time.
        example: '2024-05-22T21:15:55.306Z'
        schema:
          type: string
          format: date-time
      - name: isComplete
        in: query
        description: Filter the output for tasks that have a completion status matching the provided value
        example: true
        schema:
          type: boolean
      - name: includeWireInstructions
        in: query
        example: true
        description: Whether to include Wire Verification in the data. Please contact Arch to enable this parameter.
        schema:
          type: boolean
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskList'
      operationId: getClientApiV0Tasks
      x-operation-id-source: derived
  /client-api/v0/tasks/{userId}/assign:
    patch:
      summary: Assign one or more tasks to a user with userId
      security:
      - BearerAuth: []
      description: Assign one or more tasks to a user with userId.
      tags:
      - Tasks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - taskIds
              properties:
                taskIds:
                  type: array
                  description: An array of taskIds.
                  items:
                    type: integer
                  example:
                  - 1
                  - 2
                  - 3
      parameters:
      - name: userId
        in: path
        description: The ID of the user to be assigned the tasks.
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                type: string
        '403':
          description: Tasked user does not have permission to complete one or more of the provided tasks, or one or more of the provided tasks cannot be assigned by you.
          content:
            text/plain:
              schema:
                type: string
        '404':
          description: User not found or is inaccessible.
          content:
            text/plain:
              schema:
                type: string
        '500':
          description: Error completing task.
          content:
            text/plain:
              schema:
                type: string
      operationId: patchClientApiV0TasksByUserIdAssign
      x-operation-id-source: derived
  /client-api/v0/tasks/{id}/task-notes:
    patch:
      summary: Update the notes section of a task
      security:
      - BearerAuth: []
      description: Update the notes section (investorNotes) of a task by ID.
      tags:
      - Tasks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - taskNotes
              properties:
                taskNotes:
                  type: string
                  description: The updated notes for the task. Can be null or empty string to clear notes.
                  example: Updated task notes here
      parameters:
      - name: id
        in: path
        description: The ID of the task to update.
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          description: Malformed request body.
          content:
            text/plain:
              schema:
                type: string
        '404':
          description: Task not found or caller not authorized to update task.
          content:
            text/plain:
              schema:
                type: string
        '500':
          description: Error updating task.
          content:
            text/plain:
              schema:
                type: string
      operationId: patchClientApiV0TasksByIdTaskNotes
      x-operation-id-source: derived
  /client-api/v0/tasks/{id}/comments:
    get:
      summary: Get all user comments for a task
      security:
      - BearerAuth: []
      description: Get all user comments for a task. Employee comments are excluded. Requires CommentsRead permission.
      tags:
      - Tasks
      parameters:
      - name: id
        in: path
        description: The ID of the task to get comments for.
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Comment'
        '400':
          description: Invalid task ID
          content:
            text/plain:
              schema:
                type: string
        '403':
          description: Forbidden - CommentsRead permission required
          content:
            text/plain:
              schema:
                type: string
        '404':
          description: Task not found or caller not authorized to view task.
          content:
            text/plain:
              schema:
                type: string
      operationId: getClientApiV0TasksByIdComments
      x-operation-id-source: derived
components:
  schemas:
    CurrencyCode:
      type: string
      example: USD
      default: USD
      description: The currency code for the financial value. Defaults to "USD" if not provided.
    TaskList:
      type: object
      required:
      - kind
      - selfUrl
      - contents
      properties:
        kind:
          type: string
          description: page
          example: page
        selfUrl:
          type: string
          description: The relative URL for accessing this resource via the Arch Client API
          example: /tasks?limit=10&offset=0
        contents:
          type: array
          items:
            $ref: '#/components/schemas/Task'
          description: List of tasks
        prev:
          type: string
          description: The relative URL for the previous page of tasks
          example: /tasks?limit=10&offset=0
        next:
          type: string
          description: The relative URL for the next page of tasks
          example: /tasks?limit=10&offset=10
    Comment:
      type: object
      required:
      - id
      - author
      - creationTime
      - updateTime
      - message
      properties:
        id:
          type: integer
          description: The comment ID
          example: 12345
        author:
          type: object
          description: Comment author information
          required:
          - id
          - name
          - url
          properties:
            id:
              type: integer
              description: User ID
              example: 2766
            name:
              type: string
              description: User's full name
              example: John Smith
            url:
              type: string
              description: URL to user resource
              example: /users/2766
        creationTime:
          type: string
          format: date-time
          description: When the comment was created
          example: '2024-03-11T14:13:29.000Z'
        updateTime:
          type: string
          format: date-time
          description: When the comment was last updated
          example: '2024-03-11T14:13:29.000Z'
        message:
          type: string
          description: The comment text
          example: This needs to be reviewed
        parentCommentId:
          type:
          - integer
          - 'null'
          description: Parent comment ID for threaded comments, or null for top-level comments
          example: 12340
    FinancialValue:
      type: object
      properties:
        quantity:
          type: integer
          format: int64
          description: The quantity of the financial value
          example: 100000
        currencyCode:
          $ref: '#/components/schemas/CurrencyCode'
        dollars:
          type: integer
          format: int64
          description: The financial value in dollars
      example:
        quantity: 100000
        currencyCode: USD
        dollars: 100000
    ActivityRef:
      type: object
      required:
      - id
      - url
      - filesUrl
      properties:
        id:
          type: string
          description: The ID of the referenced activity
          example: 112
        url:
          type: string
          description: A relative url to the referenced activity
          example: /activities/112
        filesUrl:
          type: string
          description: A relative url to the files attached to the referenced activity. The activity may not have files attached.
          example: /activities/112/files
    Task:
      type: object
      required:
      - id
      properties:
        id:
          type: string
          description: The task ID.
          example: 9007
          readOnly: true
        dueDate:
          type: string
          format: date
          example: '2023-07-14'
          description: The due date of the task.
        completionDate:
          deprecated: true
          type: string
          format: date
          example: '2024-04-02'
          description: The date the task was completed (in UTC). For specific completion time, use 'completionTime'.
        completionTime:
          type: string
          format: date-time
          example: '2024-03-11T14:13:29.000Z'
          description: The time the task was completed.
        completed:
          type: boolean
          example: true
          description: Whether the task is completed.
        creationTime:
          type: string
          format: date-time
          example: '2024-03-11T14:13:29.000Z'
          description: The time the task was created.
        investorNotes:
          type: string
          example: This is a note
          description: The note from the investor.
        holdingUrl:
          type: string
          example: /holdings/16
          description: The URL of the holding this Task is associated with.
        investingEntityUrl:
          type: string
          example: /investing-entities/3
          description: The URL of the investing entity this Task is associated with.
        activityRef:
          $ref: '#/components/schemas/ActivityRef'
        activityUrl:
          type: string
          example: /activities/767801
          description: The URL of the activity this Task is sourced from.
        accountUrl:
          type: string
          example: /accounts/56
          description: The URL of the account this Task is sourced from.
        completedByUserUrl:
          type: string
          example: /users/2766
          description: The URL of the user who completed the task.
        assignedToUserUrl:
          type: string
          example: /users/2766
          description: The URL of the user who the task is assigned to.
        value:
          $ref: '#/components/schemas/FinancialValue'
        wireVerification:
          type: object
          properties:
            currentWireExtraction:
              type: object
              properties:
                id:
                  type: integer
                  example: 198
                  description: The ID of Wire Extraction
                sourceActivityId:
                  type: integer
                  example: 812464
                  description: The ID of source actviity
                specifiedCompletionTime:
                  type: string
                  format: date-time
                  example: '2025-06-01T00:00:00.000Z'
                  description: Date and time of specified completion
                wireInstructions:
                  type: object
                  description: Current wire instructions
                  properties:
                    id:
                      type: integer
                      example: 2503
                      description: The ID of the wire instruction
                    bankName:
                      type: string
                      example: Arch Corpo Bank
                      description: The name of the bank
                    bankAddress:
                      type: string
                      example: 1048 Broadway New York, NY 10003 USA
                      description: The address of the bank
                    accountName:
                      type: string
                      example: Tiger Global PIP
                      description: The name of the account
                    accountNumber:
                      type: string
                      example: 9984671534
                      description: The number of the account
                    abaNumber:
                      type: string
                      example: 890033223
                      description: The ABA (or routing) number
                    reference:
                      type: string
                      example: Arch Family Foundation
                      description: The reference of wire
                    bic:
                      type: string
                      example: ABGGE
                      description: The Bank Identifier Code
                    iban:
                      type: string
                      example: DE89370400440532013000
                      description: The Internation Bank Account Number
                    sortCode:
                      type: string
                      example: 123456
                      description: The Sort Code
                    contactName:
                      type: string
                      example: John Smith
                      description: The name of the contact
                    contactNumber:
                      type: string
                      example: 123-456-7890
                      description: The phone number of the contact
            changedFields:
              type: array
              description: an array of changed fields between the current and previous iterations of wire instructions
              items:
                type: string
              example:
              - bankName
              - bankAddress
          description: Current wire instructions and changed fields between the current and previous iterations of wire instructions - requires includeWireInstructions flag to be true. Wire Data is a premium feature that will return null if the Client is not subscribed to Wire Instruction Data Extraction.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT