Payout Recipients

A payout recipient represents an entity that can be apportioned some fraction of a bill's calculated fees. Use the Payout Recipients API to view and manage the recipients 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 are provided "as is" and "as available" with no warranty or guarantee of functionality and may be modified or removed at any time.


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`

📘 Access requirements

All operations require "Run and manage bills, include fee adjustment and payment tracking" or "Full access to Billing and billing data" application permissions, plus BILLING_WRITE OAuth scope.

Resource overview

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

Parameters

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

Get recipients

Get a paginated list of recipients (in name order).

GET /v1/billing/payout/recipients

🔒
Authentication
This endpoint requires a valid API key. Include your credentials in the header:
Authorization: Basic base64(key_id:key_secret)

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

curl -X GET https://{firm}.addepar.com/api/v1/billing/payout/recipients \
  -H "Authorization: Basic base64(key_id:key_secret)" \
  -H "Addepar-Firm: {firm}" \
  -H "Accept: application/vnd.api+json"

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
    }
  }
}

With search filter:

curl -X GET "https://{firm}.addepar.com/api/v1/billing/payout/recipients?search=jane" \
  -H "Authorization: Basic base64(key_id:key_secret)" \
  -H "Addepar-Firm: {firm}" \
  -H "Accept: application/vnd.api+json"

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

curl -X GET https://{firm}.addepar.com/api/v1/billing/payout/recipients/1 \
  -H "Authorization: Basic base64(key_id:key_secret)" \
  -H "Addepar-Firm: {firm}" \
  -H "Accept: application/vnd.api+json"

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

Single recipient:

curl -X POST https://{firm}.addepar.com/api/v1/billing/payout/recipients \
  -H "Authorization: Basic base64(key_id:key_secret)" \
  -H "Addepar-Firm: {firm}" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
    }
  }
}

Bulk creation:

curl -X POST https://{firm}.addepar.com/api/v1/billing/payout/recipients \
  -H "Authorization: Basic base64(key_id:key_secret)" \
  -H "Addepar-Firm: {firm}" \
  -H "Content-Type: application/json" \
  -d '{
    "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

curl -X PUT https://{firm}.addepar.com/api/v1/billing/payout/recipients/1 \
  -H "Authorization: Basic base64(key_id:key_secret)" \
  -H "Addepar-Firm: {firm}" \
  -H "Content-Type: application/json" \
  -d '{
    "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

curl -X DELETE https://{firm}.addepar.com/api/v1/billing/payout/recipients/1 \
  -H "Authorization: Basic base64(key_id:key_secret)" \
  -H "Addepar-Firm: {firm}"

HTTP/1.1 204

Bulk deletion:

DELETE /v1/billing/payout/recipients

curl -X DELETE https://{firm}.addepar.com/api/v1/billing/payout/recipients \
  -H "Authorization: Basic base64(key_id:key_secret)" \
  -H "Addepar-Firm: {firm}" \
  -H "Content-Type: application/json" \
  -d '{
    "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., 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 -- Request body type is not payout_recipient

📘 Related resources

Payout Rules | Billing | Fee Schedules