Client Portal

Publish files to the Client Portal and notify contacts in a single API call. As a pre-step, you can generate reports, upload files, or associate a file to a portfolio via API, or do this manually in Addepar.

Overview


Base route	`/v1/portal/publish_files`
Produces	JSON
Pagination	Yes
OAuth scopes	`FILES_WRITE` and `PUBLISH_FILE`

📘
Access requirements

Portal: Share client files

Files: Create, edit, delete

Resource attributes

The Publish to Portal API returns a resource object containing the file ID and status in a successful POST response.

Attribute	Description
`file_id`	Integer -- The ID of the file associated with contacts. Example: `37`
`publish_status`	String -- Indicates if the file was published to the Portal. Returns `"success"` when the file is shared with all listed contacts without issue. Returns `"fail"` if the file fails to share with one or more contacts. Example: `"success"`
`notify_status`	String -- Indicates if the contact was notified via email. Returns `"success"` when all contacts are notified without issue, or when you chose to skip notification. Returns `"fail"` if one or more contacts could not be notified. Example: `"success"`
`error`	Array -- A list of objects representing errors arising during publishing or notifying. Each object contains `code` (String -- error name), `title` (String -- error description), and `detail` (String -- error details including affected contact IDs). Example: See example below

Request parameters

Parameter	Description
`files_id`	List of integers -- The IDs of the files you want to publish to contacts' portals. Required. Maximum of 500 files. Example: `[37,38,39]`
`portal_publishing`	String -- The scope of publishing the files to portal. Required. Supported values: `do_not_publish`, `use_contact_preference`, `publish` Example: `"publish"`
`contact_notification`	String -- The scope of notifying contacts about successful publishes. Required. Supported values: `do_not_notify`, `use_contact_preference`, `notify` Example: `"notify"`
`publish_override_contact_ids`	List of integers -- The IDs of contacts that will always have the files published to portal, regardless of `portal_publishing` value. Optional. Example: `[23,25]`

Publish to Portal

Requests to publish a file to the Client Portal.

POST /v1/portal/publish_files

📘
Authentication
All requests require a base64-encoded API key pair:
Authorization: Basic {base64(key_id:key_secret)}
See Access & Authentication for setup.

curl -X POST "https://{firm}.addepar.com/api/v1/portal/publish_files" \
  -H "Authorization: Basic {base64(key_id:key_secret)}" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
  "data": {
    "type": "publish_portal_files_request",
    "attributes": {
      "files_id": [37, 38, 39],
      "portal_publishing": "PUBLISH",
      "contact_notification": "DO_NOT_NOTIFY"
    }
  }
}'

{
  "data": [
    {
      "id": "37",
      "type": "publish_files_result",
      "attributes": {
        "file_id": 37,
        "notify_status": "success",
        "publish_status": "success"
      },
      "links": {
        "self": "/v1/publish_files_result/37"
      }
    },
    {
      "id": "38",
      "type": "publish_files_result",
      "attributes": {
        "file_id": 38,
        "notify_status": "success",
        "publish_status": "success"
      },
      "links": {
        "self": "/v1/publish_files_result/38"
      }
    },
    {
      "id": "39",
      "type": "publish_files_result",
      "attributes": {
        "file_id": 39,
        "notify_status": "success",
        "publish_status": "success"
      },
      "links": {
        "self": "/v1/publish_files_result/39"
      }
    }
  ],
  "included": [],
  "links": {
    "prev": null,
    "next": null
  }
}

{
  "errors": [
    {
      "id": "publish_files_error",
      "status": "400",
      "code": "bad_request",
      "title": "Bad Request",
      "detail": "Missing required field: portal_publishing"
    }
  ]
}

Response codes:

200 OK -- Success. This occurs even if failures during publish or notification occur.
400 Bad Request -- Missing required fields or too many files.
403 Forbidden -- Lacking file permission or client portal publish file permission.

Partial failure handling

When you request to publish files to the portal, if the publish or notification fails for one or more contacts, the job will still be processed. You will receive a notice of the failures along with the contact IDs.

{
  "data": [
    {
      "id": "37",
      "type": "publish_files_result",
      "attributes": {
        "file_id": 37,
        "notify_status": "fail",
        "publish_status": "success",
        "error": [
          {
            "code": "notification_failed",
            "title": "Notification failed for some contacts.",
            "detail": "Notification failed for contacts [1,2,3]."
          }
        ]
      },
      "links": {
        "self": "/v1/publish_files_result/37"
      }
    },
    {
      "id": "38",
      "type": "publish_files_result",
      "attributes": {
        "file_id": 38,
        "notify_status": "fail",
        "publish_status": "fail",
        "error": [
          {
            "code": "publish_failed",
            "title": "Publish failed for some contacts.",
            "detail": "Publish failed for contacts [4,5]."
          },
          {
            "code": "notification_failed",
            "title": "Notification failed for some contacts.",
            "detail": "Notification failed for contacts [1,2,3]."
          }
        ]
      },
      "links": {
        "self": "/v1/publish_files_result/38"
      }
    }
  ],
  "included": [],
  "links": {
    "prev": null,
    "next": null
  }
}

📘
Related resources

Files -- Upload and manage files

Report Generation -- Generate reports programmatically