Payout Recipients

A payout recipient represents an entity that can be apportioned some fraction of a bill's calculated fees. This could be a person, a firm or grouping. Use the payout recipient API to view and manage the recipients that are available for use when constructing payout rule structures.

Billing payouts is in closed beta
The ability to use and manage the payout features described herein is available only to a pre-selected group of Addepar clients within the Addepar Beta Program. All beta features described herein are provided “as is'” and “as available” with no warranty or guarantee of functionality and may be modified or removed at any time by Addepar.


Base route	`/v1/billing/payout/recipients`
Endpoints	GET `/v1/billing/payout/recipients` `/v1/billing/payout/recipients/:id` POST `/v1/billing/payout/recipients` PUT `/v1/billing/payout/recipients/:id` DELETE `/v1/billing/payout/recipients` `/v1/billing/payout/recipients/:id`
Produces	JSON
Pagination	Yes
Application permissions required	"Run and manage bills, include fee adjustment and payment tracking" or "Full access to Billing and billing data"
OAuth scopes	`BILLING_WRITE`

Resource overview

Arguments are described by the below resource object attributes and will appear in successful POST and PUT responses.

Attribute	Description	Example
`id`	The payout recipient's ID. Integer type	`1234`

Parameters

Parameter	Description	Example
`name`	The primary identifier for the recipient	`John Jackson` `Analysis team`
`type`	An optional descriptive string for the recipient	`Advisor` `Sales` `Team`

Get recipients

Get a paginated list of recipients (in name order) with:

GET /v1/billing/payout/recipients

The request supports name-search and result pagination via query parameters:

search - Only recipients whose names match (case insensitive) the search term will be returned
offset - How many recipients in the search result set to skip
limit - The maximum number of recipients to return

Example

GET https://examplefirm.addepar.com/api/v1/billing/payout/recipients

HTTP/1.1 200

{
  "data": [
    {
      "type": "payout_recipient",
      "id": "1",
      "attributes": {
        "name": "Jane Smith",
        "type": "Advisor"
      }
    },
    {
      "type": "payout_recipient",
      "id": "2",
      "attributes": {
        "name": "Bob Johnson",
        "type": "Analyst"
      }
    }
  ],
  "meta": {
    "page": {
      "total": 2,
      "cursor": 0,
      "limit": 500
    }
  }
}

Example

GET https://examplefirm.addepar.com/api/v1/billing/payout/recipients?search=jane

HTTP/1.1 200

{
  "data": [
    {
      "type": "payout_recipient",
      "id": "1",
      "attributes": {
        "name": "Jane Smith",
        "type": "Advisor"
      }
    }
  ],
  "meta": {
    "page": {
      "total": 1,
      "cursor": 0,
      "limit": 500
    }
  }
}

Response codes:

200 OK: Success
403 Forbidden: Insufficient application permissions or appropriate scope not granted

Get recipient

Single recipients can be retrieved by ID

GET /v1/billing/payout/recipients/:id

Example

GET https://examplefirm.addepar.com/api/v1/billing/payout/recipients/1

HTTP/1.1 200

{
  "data": {
    "type": "payout_recipient",
    "id": "1",
    "attributes": {
      "name": "Jane Smith",
      "type": "Advisor"
    }
  }
}

Response codes:

200 OK: Success
403 Forbidden: Insufficient application permissions or appropriate scope not granted
404 Not Found: Recipient does not exist

Create recipients

Recipients can be created individually or in bulk

POST /v1/billing/payout/recipients

Example

POST https://examplefirm.addepar.com/api/v1/billing/payout/recipients

{
  "data": {
    "type": "payout_recipient",
    "attributes": {
      "name": "Jane Smith",
      "type": "Advisor"
    }
  }
}

HTTP/1.1 201

{
  "data": {
    "type": "payout_recipient",
    "id": "1",
    "attributes": {
      "name": "Jane Smith",
      "type": "Advisor"
    }
  }
}

Example

POST https://examplefirm.addepar.com/api/v1/billing/payout/recipients

{
  "data": [
    {
      "type": "payout_recipient",
      "attributes": {
        "name": "Jane Smith",
        "type": "Advisor"
      }
    },
    {
      "type": "payout_recipient",
      "attributes": {
        "name": "Bob Johnson",
        "type": "Analyst"
      }
    }
  ]
}

HTTP/1.1 201

{
  "data": [
    {
      "type": "payout_recipient",
      "id": "1",
      "attributes": {
        "name": "Jane Smith",
        "type": "Advisor"
      }
    },
    {
      "type": "payout_recipient",
      "id": "2",
      "attributes": {
        "name": "Bob Johnson",
        "type": "Analyst"
      }
    }
  ],
}

Response codes:

201 Created: Success
400 Bad request: Failed during validation (e.g., missing required name attribute).
403 Forbidden: Insufficient application permissions or appropriate scope not granted

Update recipients

Existing recipients can be updated via their ID:

PUT /v1/billing/payout/recipients/:id

Example

PUT https://examplefirm.addepar.com/api/v1/billing/payout/recipients/1

{
  "data": {
    "type": "payout_recipient",
    "attributes": {
      "name": "Jane Smith",
      "type": "Senior Advisor"
    }
  }
}

HTTP/1.1 200

{
  "data": {
    "type": "payout_recipient",
    "id": "1",
    "attributes": {
      "name": "Jane Smith",
      "type": "Senior advisor"
    }
  }
}

Response codes:

200 OK: Success
400 Bad request: Failed during validation (e.g., missing required name attribute).
403 Forbidden: Insufficient application permissions or appropriate scope not granted
404 Not Found: Recipient does not exist

Delete recipients

Existing recipients can be deleted individually or in bulk via their ID. Recipients may not be deleted if they are being used in payout rules.

DELETE /v1/billing/payout/recipients/:id

DELETE /v1/billing/payout/recipients/

Example

DELETE https://examplefirm.addepar.com/api/v1/billing/payout/recipients/1

HTTP/1.1 204

EXAMPLE

DELETE https://examplefirm.addepar.com/api/v1/billing/payout/recipients

{
  "data": [
    {
      "type": "payout_recipient",
      "id": 1
    },
    {
      "type": "payout_recipient",
      "id": 2
    }
  ]
}

HTTP/1.1 204

Response codes:

204 No content: Success
400 Bad Request: Failed during validation (e.g.: if the recipient is still used in a rule)
403 Forbidden: Insufficient application permissions or appropriate scope not granted
404 Not Found: Recipient does not exist
409 Conflict: If the request body type is not payout_recipient.