Rights

Creating/Editing Contracts

Use the /accounting/contract/save endpoint to create or modify contracts.

Authentication Requirements

This endpoint requires an access token from the parent account.

General creation or modification of contracts is not supported for child account users. However, parent accounts can trigger contract creation or modification as the result of a user action.

Default Contract and Payee

When a new account is created:

A default contract and default payee are automatically generated.
The default contract automatically inherits all assets in the account that are not covered by a more specific contract.
The default payee is assigned as the sole payee for that contract.

The Revelator API does not support partial updates. When editing an object:

Any omitted parameters will be deleted or overwritten.
Always retrieve the current object first, modify it, and then send the full object in your update request.

Failing to do so can result in unintended data loss or overwritten fields.

Contract Types

The Revelator system provides various contract types, each with a different scheme for specifying which assets are governed by the contract.

Account Level. Inherits all assets in an account. This is the default contract that is automatically created upon signup.
Label Level. Inherits all assets under a specified label. The contract licensor object has licensorType set to label and allFutureAssets set to true.
Artist Level. Inherits all assets for a specified artist; this includes both full releases and individual tracks. The contract licensor object has licensorType set to artist and allFutureAssets set to true.

Only the primary artist on the asset is used for contract allocation. Contributing artists are ignored, including contributors with the role “primary”.
Release Level. Includes releases (with all of their tracks) where all the releases are associated with either the same artist or the same label . The contract licensor object has licensorType set to either label or artist and allFutureAssets set to false.
Track Level. Includes specific tracks (with or without other full releases) where all of the releases and tracks are associated with either the same artist or the same label. The contract licensor object has licensorType set to either label or artist and allFutureAssets set to false.

When you create track level contracts, you must ensure that every track and the release itself is named on a contract. This means a minimum of 3 contracts for the release: a contract for the special track(s), a contract for the other track(s), and a contract for the release as a whole. The contract for the release itself should name every payee, and you must manually calculate and provide their prorated share of the release for each payee. (The release level contract is relevant when the whole release is downloaded.)

Note that even though track level contracts support including full releases, we do not recommend that you include the release itself on a contract when some but not all of the tracks are on a track specific contract. This would complicate the processes of calculating the prorated shares.

Assets will always be subject to the most specific contract that includes the asset. In other words, a track level contract will take precedence over a release level contract, a release level contract will take precedence over an artist level contract, etc.

POST `/accounting/contract/save`

Request Body

Parameter	Type	Description
`name` required	string	The name of the contract.
`contractId` optional	integer	The ID of an existing contract to edit. When set to 0, creates a new contract. (Default) Inline with the general behavior of this API, patching is not supported. Existing values for omitted parameters will be deleted or overwritten.
`startDate` required	string	The date from which the contract is effective, in the ISO format `YYYY-MM-DD`. This date is for reference only and is not enforced when calculating royalties.
`expirationDate` required	string	The date the contract becomes ineffective, in the ISO format `YYYY-MM-DD`. If the contract is “in perpetuity”, please specify `2099-12-31`. This date is for reference only and is not enforced when calculating royalties.
`isActive` optional	boolean	Indicates whether the contract is active. Inactive contracts are not used for royalty calculations. Defaults to `false` when omitted.
`contractPayees` required	array of objects	An array of objects, where each object represents a payee and details their royalty information. The sum of `sharePercentage` for all non-comission payees in the contract must equal `100`. See Contract Payee Object
`contractLicensors` required	array including one object*	An array where the single object represents a licensor (artist or label) and provides information for which of the licensor’s assets should be subject to the contract. *Although `contractLicensors` is an array, it should contain only one object. For additional licensors, please create a separate contract. See Contract Licensor Object
`contractReleases` required	array of objects	An array of objects specifying releases explicitly included in the contract. Each object must contain a `releaseId`: `{"releaseId": <integer>}`. Behavior based on `includeFutureAssets`: If `includeFutureAssets` is `true` (all future assets covered), this array must be provided as `null` or empty (`[]`), as all releases are implicitly covered. If `includeFutureAssets` is false (only specific assets covered), this array must contain the releaseId values of the releases to be included. Note on Tracks: When a release is included in this array, all its tracks are automatically subject to the contract. Its individual tracks should not be additionally listed in the `contractTracks` array.
`contractTracks` required	array of objects	An array of objects specifying individual tracks explicitly included in the contract. Each object must contain a `tracId`: `{"trackId": <integer>}`. Behavior based on `includeFutureAssets` and `contractReleases`: If `includeFutureAssets` is `true` (all future assets covered), this array must be provided as `null` or empty (`[]`), as all tracks are implicitly covered. If `includeFutureAssets` is `false` (only specific assets covered): This array must be provided as `null` or empty (`[]`) if all relevant tracks are covered by `contractReleases`. This array must contain the `trackId` values of individual tracks to be included, particularly those not part of a release listed in `contractReleases`.
`contractTerms` required	array of objects	Specifies the terms for the contract. See Contract Terms Object
`payMechanicals` optional	boolean	`true` - to pay digital mechanicals. Additional attributes are required. `false` - to not pay digital mechanicals (Default)
`mechanicalsTypeId` optional ¹	integer	Rate type for mechanicals: `1` - % of Sales `2` - Penny Rate `3` - Copyright Law ¹Mandatory when `payMechanicals` is true.
`mechanicalsSalesPercentage` optional ²	integer	Sales percent. ²Mandatory when `mechanicalsTypeId` is `1`.
`mechanicalsFixedPennyRate` optional ³	integer	Penny rate. ³Mandatory when `mechanicalsTypeId` is `2`.
`mechanicalsIsFullRate` optional ⁴	boolean	Rate basis: `true` - Full `false` - Minimum ⁴Mandatory when `mechanicalsTypeId` is `3`.
`mechanicalsRatePercentage` optional ⁴	integer	Rate percent. ⁴Mandatory when `mechanicalsTypeId` is `3`.

Although contractLicensors is technically an array, sending it as null or [] does not return a clean validation error — it fails with a 500 Internal Server Error ("Sequence contains no elements"). Always include exactly one licensor object.

Contract Payee Object

Parameter	Type	Description
`sharePercentage` optional	integer	For standard payees (non-commission), the percent of the payee revenue that will go to this payee. For commission payees, the percent of the payor revenue that will go to this payee. Defaults to `0`
`startingBalance` optional	integer	The payee’s starting balance. Defaults to `0` for new payees. Defaults to the current value for existing payees. Cannot be changed for existing payees; the request will fail if the provided value does not match the current value.
`isCommissionPayee` optional	boolean	`true` - the payee is a commission payee, and will be paid from the payor’s share of the revenue. `false` - the payee is a standard payee (Default)
`payee` required	object	Details of the payee. See Payee Object
`permission` optional	object	The permissions the payee has in their payee portal. This parameter sets permissions for the payee to log into the Revelator UI. It is not relevant for most API use cases, and is never relevant when the payee already has a user/child account that was created with the `signup` resource.

Payee Object

This is a condensed, contract-scoped view of the payee. Payees can also be managed directly, independent of any contract — see Creating/Editing Payees and Retrieving Payees for the full payee object and dedicated endpoints.

If contactId is non-zero, it takes precedence over contact.contactId: the existing contact record it points to is reused as-is, and any fields you send in the nested contact object are silently ignored (the contact is not updated to match them).

If contactId is 0 (or omitted) while the nested contact.contactId references a contact that already exists (e.g. one belonging to a different payee), the request does not return a clean validation error — it fails with an unhandled 500 Internal Server Error.

To avoid both problems, always keep contactId and contact.contactId in sync: both 0 for a new contact, or both set to the same existing ID for an update.

Parameter	Type	Description
`payeeId` optional	integer	ID for an existing payee to associate with the contract. When set to `0`, a new payee is created. (Default) A default payee (and default contract) is automatically created upon account creation. Note: You should never create a new payee for a user for whom you have already created a child account.
`companyName` required	string	The name of the payee. If omitted, defaults to the `name` of the associated `contact`.
`isCompany` optional	boolean	Whether the payee is a company (`true`) or an individual (`false`). Defaults to `false`.
`contactId` optional	integer	The ID for an existing contact. When set to `0`, a new contact is created. (Default) See the callout above for how this interacts with `contact.contactId`.
`contact` required	object	Contact information for the payee.
`contact.contactId` optional	integer	The ID for an existing contact. When set to 0, a new contact is created. (Default)
`contact.name` optional	string	The name of the contact. Defaults to the `companyName`.
`contact.email` optional	string	The contact’s email address. This email is used for sending statement notifications when automatic email notifications are enabled.
`currencyCode` optional	string	The currency code for the payee’s currency. Defaults to the parent account’s currency code. Look up currency codes using the `GET /common/lookup/currencies` resource.
`taxDomicileCountryId` optional	integer	The country ID for the payee’s tax domicile. Look up country IDs using the `GET /common/lookup/countries` resource. Optional when first creating the payee — see callout below.
`vatNumber` optional	string	The payee’s VAT number.
`taxIdNumber` optional	string	The payee’s tax ID number.
`vendorId` optional	string	An external/internal vendor identifier for the payee.
`minimumPayment` optional	number	The minimum balance the payee must accrue before being paid out.
`paymentProviderId` optional	integer	2 - paypal Only necessary when using the PayPal integration for paying the payee.
`paymentUserId` optional	string	The PayPal email address for the payee. Only necessary when using the PayPal integration for paying the payee.

Once a value has been saved for taxDomicileCountryId, it becomes permanently fixed for that payee. Any later contract/save request that sends a different value — or omits the field entirely — is rejected with 400 Bad Request:

"Tax Domicile Country cannot be updated once it is set."

Omitting the field counts as an attempted change to null, so once this field has a value you must resend that exact same value on every subsequent edit to the payee.

The API also returns several read-only fields on the payee object (e.g. balance, role, isBlocked, isLockedOut, enterpriseId, isPortalPayee, paymentProviderName, payeeProvider). These reflect system-managed state and are not meant to be set directly through contract/save.

Contract Licensor Object

Parameter	Type	Description
`id` optional	UUID	The ID for an existing contract licensor entity. Not relevant for new contracts. Should be provided when editing an existing contract — if omitted, the API creates a brand-new licensor entity (with a new `id`) to replace the old one, rather than updating it in place.
`licensorType` required	integer	The type of licensor that will be used to specify the assets to include in the contract. `1` - artist* `2` - label * For artist licensors(`licensorType = 1`), only assets where the artist is the primary artist on the release level can be specified. Therefore, compilations cannot be directly specified for artist licensors. Additionally, when `includeFutureAssets` is `true`, only the primary artist on the asset is considered; other contributors are ignored, including contributors with the role “primary”. Note: `3` (enterprise) also appears in responses for the account-level contract that is auto-created on signup, but this level is not something you create yourself — use `1` or `2` for contracts you create.
`licensorId` required	integer	The ID of the licensor. Either an `artistId` or `labelId`, corresponding to the `licensorType`.
`includeFutureAssets` optional	boolean	`true` - to include all of the licensor’s current and future assets. When this is true for a licensor, none of the licensor’s assets should be included in the `contractReleases` or `contractTracks` arrays. `false` - to not include all of the licensor’s current and future assets (Default)

Contract Terms Object

Parameter	Type	Description
`contractTermsId` optional	UUID	The ID for an existing contract terms entity. Not relevant for new contracts. Should be provided when editing an existing contract — if omitted, the API creates a brand-new terms entity (with a new `contractTermsId`) to replace the old one, rather than updating it in place.
`contractTermsRate` optional	integer	The percent of the revenue being paid out to payees. Defaults to `0`.
`contractTermsRateTypeId` required	integer	`1` - to calculate the payout with retail `2` - to calculate the payout with wholesale
`isCountriesIncluded` optional	boolean	`true` - the `countries` array provides the only territories included in the contract `false` - the `countries` array provides the only territories excluded by the contract, and all other countries are included (Default) To include all territories in the contract, set `isCountriesIncluded` to `false` and leave `countries` empty.
`isDistributorStoresIncluded` optional	boolean	`true` - the `distributorStores` array provides the only services included in the contract `false` - the distributorStores array provides the only DSPs excluded by the contract, and all other DSPs are included (Default) To include all DSPs in the contract, set `isDistributorStoresIncluded` to `false` and leave `distributorStores` empty.
`countries` optional	array of integers	IDs for the countries included or excluded from the contract. See `isCountriesIncluded`. Look up country IDs using the GET /common/lookup/countries resource.
`distributorStores` optional	array of integers	IDs for the services included or excluded from the contract. See `isDistributorStoresIncluded`. Look up DSP IDs using the GET `/common/lookup/stores` resource. Provide an access token to retrieve only the DSPs enabled for a specific account.
`releaseTypes` optional	array of integers	Types of releases to include in the contract terms: `1` - Album `2` - Single `4` - EP An empty array will cause all types to be included for the contract. (Default)
`deliveryTypes` optional	array of integers	Delivery channels to include in the contract terms. Each integer in the array is an ID that represents a delivery type; each channel includes multiple delivery types. Download: `101`,`106`, `123` Subscription: `102`,`104`,`105`,`107` Ad supported: `103`, `115`, `109`, `118` Physical: `110` Rental: `116` Digital Licensing: `117` UGC: `120` An empty array will cause all types to be included for the contract. (Default)

Example

Request body

{
  "contractId": 0,
  "name": "string",
  "startDate": "2021-10-26T18:19:07.921Z",
  "expirationDate": "2021-10-26T18:19:07.921Z",
  "mechanicalsTypeId": 0,
  "mechanicalsSalesPercentage": 0,
  "mechanicalsIsFullRate": true,
  "mechanicalsRatePercentage": 0,
  "mechanicalsFixedPennyRate": 0,
  "payMechanicals": true,
  "isActive": true,
  "contractTerms": [
    {
      "contractTermsId": "00000000-0000-0000-0000-000000000000",
      "contractTermsRateTypeId": 0,
      "contractTermsRate": 0,
      "isCountriesIncluded": true,
      "isDistributorStoresIncluded": true,
      "countries": [
        0
      ],
      "deliveryTypes": [
        0
      ],
      "releaseTypes": [
        0
      ],
      "distributorStores": [
        0
      ]
    }
  ],
  "contractReleases": [
    {
      "releaseId": 0
    }
  ],
  "contractTracks": [
    {
      "trackId": 0
    }
  ],
  "contractLicensors": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "licensorType": 0,
      "licensorId": 0,
      "includeFutureAssets": true
    }
  ],
  "contractPayees": [
    {
      "sharePercentage": 0,
      "startingBalance": 0,
      "isCommissionPayee": true,
      "permission": {
        "enterpriseId": 0,
        "enterpriseName": "string",
        "labelId": 0,
        "publisherId": 0,
        "artistId": 0,
        "payeeId": 0,
        "imageId": "00000000-0000-0000-0000-000000000000",
        "name": "string",
        "permissionsAccountId": "00000000-0000-0000-0000-000000000000",
        "isOwner": true,
        "readOnlyContent": true,
        "readOnlyContracts": true,
        "readOnlyFinance": true,
        "readOnlyDistribution": true,
        "readOnlyServices": true,
        "readOnlyTrustAndSafety": true,
        "readOnlyPromote": true,
        "readOnlyDaily": true,
        "permissionRolesId": 0,
        "viewAIDataAnalyst": true,
        "viewRevenueAnalytics": true,
        "isActive": true,
        "isDefault": true,
        "email": "string",
        "accountType": 0
      },
      "payee": {
        "payeeId": 0,
        "companyName": "string",
        "isCompany": false,
        "contactId": 0,
        "contact": {
          "contactId": 0,
          "name": "string",
          "currencyCode": "string",
          "email": "string",
          "contactRoleId": 0
          },
        "currencyCode": "string",
        "taxDomicileCountryId": 0,
        "vatNumber": "string",
        "taxIdNumber": "string",
        "vendorId": "string",
        "minimumPayment": 0,
        "paymentProviderId": 0,
        "paymentUserId": "string"
      }
    }
  ]
}

Retrieving Contracts

Authentication Requirements

These endpoints requires an access token from the parent account.

GET `/accounting/contracts`

Retrieves a paginated list of contracts in the account, with support for filtering, sorting, and searching.

When applying multiple filters of the same type, provide each value as a separate query parameter. Example:
payeeIds=2384320&payeeIds=1628168

Query params

Parameter	Type	Description
`pageNumber` optional	integer	The page number of the results to retrieve. Default is `50`.
`pageSize` optional	integer	The number of items to return per page.
`orderByProperty` optional	string	The property to sort the results by. Supported values: `name` `contractId` `contractLevel` `creationDate`
`orderByDescending` optional	boolean	If `true`, orders the results in descending order. If `false` or omitted, orders in ascending order.
`searchText` optional	string	A search term to filter contracts by name. The search is case-insensitive.
`isActive` optional	boolean	Filters contracts by active status. If omitted, both active and inactive contracts are returned.
`contractLevel` optional	integer	Filters contracts by the level at which they are applied: `0` - Account `10` - Label `20` - Artist `30` - Release `40` - Track `50` - YouTube Channel `60` - YouTube Video
`payeeIds` optional	array of integers	Filters contracts associated with one or more specific payees.

Example

Request

curl -X GET 'https://api.revelator.com/accounting/contracts?isActive=true&contractLevel=0'

Response

{
    "pageNumber": 1,
    "pageSize": 50,
    "totalItemsCount": 3627,
    "totalPagesCount": 73,
    "items": [
        {
            "contractId": 123567,
            "startDate": "2019-11-19T00:00:00",
            "expirationDate": "2999-12-31T00:00:00",
            "isActive": true,
            "mechanicalsFixedPennyRate": null,
            "mechanicalsIsFullRate": null,
            "mechanicalsRatePercentage": null,
            "mechanicalsSalesPercentage": null,
            "mechanicalsTypeId": null,
            "name": "Contract Name",
            "payMechanicals": false,
            "creationDate": "2019-11-19T15:20:24.987",
            "isRoyaltyTokenContract": false,
            "contractLevelId": 0,
            "contractPayees": [
                {
                    "payeeId": 123456,
                    "sharePercentage": 100.00,
                    "startingBalance": 0.00,
                    "isCommissionPayee": false,
                    "companyName": null,
                    "email": null
                }
            ]
        }
    ]
}

GET `/accounting/contracts/{contractId}`

Retrieves details for a specific contract.

Example

Request

curl -X GET 'https://api.revelator.com/accounting/contracts/123456'

Response

{
  "contractId": 0,
  "startDate": "2026-02-04T12:25:35.274Z",
  "expirationDate": "2026-02-04T12:25:35.274Z",
  "isActive": true,
  "mechanicalsFixedPennyRate": 0,
  "mechanicalsIsFullRate": true,
  "mechanicalsRatePercentage": 0,
  "mechanicalsSalesPercentage": 0,
  "mechanicalsTypeId": 0,
  "name": "string",
  "payMechanicals": true,
  "payorName": "string",
  "creationDate": "2026-02-04T12:25:35.274Z",
  "isRoyaltyTokenContract": true,
  "contractLevelId": 0,
  "contractTerms": [
    {
      "contractTermsId": "00000000-0000-0000-0000-000000000000",
      "contractTermsRate": 0,
      "isCountriesIncluded": true,
      "isDistributorStoresIncluded": true,
      "isAssetTypesIncluded": true,
      "countryIds": [
        0
      ],
      "deliveryTypeIds": [
        0
      ],
      "releaseTypeIds": [
        0
      ],
      "distributorStoreIds": [
        0
      ],
      "assetTypeIds": [
        0
      ]
    }
  ],
  "contractAssets": [
    {
      "assetId": 0,
      "assetTypeId": 0
    }
  ],
  "contractReleases": [
    {
      "releaseId": 0,
      "assetId": 0,
      "assetTypeId": 0,
      "name": "string",
      "releaseTypeId": 0,
      "artistName": "string",
      "upc": 0
    }
  ],
  "contractTracks": [
    {
      "trackId": 0,
      "assetId": 0,
      "assetTypeId": 0,
      "name": "string",
      "artistName": "string",
      "trackRecordingVersions": [
        {
          "isrc": "string",
          "recordingVersionType": 0,
          "audioFiles": [
            {
              "audioId": "00000000-0000-0000-0000-000000000000",
              "fileFormat": "Wav",
              "audioFilename": "string",
              "audioChannels": 0,
              "audioBitDepth": 0,
              "audioSampleRate": 0,
              "audioBitrate": 0,
              "audioSeconds": 0,
              "audioSize": 0
            }
          ]
        }
      ]
    }
  ],
  "contractYouTubeChannels": [
    {
      "youTubeChannelId": 0,
      "assetId": 0,
      "assetTypeId": 0,
      "title": "string",
      "handle": "string",
      "youTubeId": "string"
    }
  ],
  "contractYouTubeVideos": [
    {
      "youTubeVideoId": 0,
      "assetId": 0,
      "assetTypeId": 0,
      "title": "string",
      "youTubeId": "string",
      "imageDefaultUrl": "string",
      "imageMediumUrl": "string",
      "imageHighUrl": "string",
      "channelTitle": "string",
      "youTubeChannelId": 0,
      "duration": "string",
      "viewCount": 0
    }
  ],
  "contractLicensors": [
    {
      "licensorType": 0,
      "licensorId": 0,
      "includeFutureAssets": true,
      "licensorName": "string"
    }
  ],
  "contractPayees": [
    {
      "payeeId": 0,
      "sharePercentage": 0,
      "startingBalance": 0,
      "isCommissionPayee": true,
      "companyName": "string",
      "email": "string"
    }
  ]
}

Creating/Editing Payees

Use the /accounting/payee/save endpoint to create or modify a payee directly, independent of any contract.

This is the same underlying payee entity referenced by a contract’s contractPayees[].payee (see the condensed Payee Object documented under Creating/Editing Contracts) — but this endpoint exposes the full payee record, including fields that aren’t relevant when a payee is only being attached to a contract.

A payee created here is not automatically attached to any contract. To pay it out for specific assets, you still need to add it to a contract’s contractPayees array via /accounting/contract/save.

Authentication Requirements

Unlike contracts, this endpoint can be called with either:

An access token from the parent account, to manage any payee in the account, or
The payee’s own access token, to let a payee update their own record — this is how the Tipalti payee flow updates a payee’s payment method.

POST `/accounting/payee/save`

Request Body

Parameter	Type	Description
`payeeId` optional	integer	ID of an existing payee to edit. When set to `0` (or omitted), a new payee is created. (Default)
`companyName` required	string	The name of the payee. If omitted, defaults to the `name` of the associated `contact`.
`isCompany` optional	boolean	Whether the payee is a company (`true`) or an individual (`false`). Defaults to `false`.
`companyOrIndividualID` optional	string	A company or individual registration identifier for the payee.
`contactId` optional	integer	The ID for an existing contact. When set to `0`, a new contact is created. (Default) See the callout below for how this interacts with `contact.contactId`.
`contact` required	object	Contact information for the payee. See Contact Object
`currencyCode` optional	string	The currency code for the payee’s currency. Defaults to the parent account’s currency code. Look up currency codes using the `GET /common/lookup/currencies` resource.
`taxDomicileCountryId` optional	integer	The country ID for the payee’s tax domicile. Look up country IDs using the `GET /common/lookup/countries` resource. Optional when first creating the payee — see callout below.
`vatNumber` optional	string	The payee’s VAT number.
`taxIdNumber` optional	string	The payee’s tax ID number.
`vendorId` optional	string	An external/internal vendor identifier for the payee.
`minimumPayment` optional	number	The minimum balance the payee must accrue before being paid out.
`autoSendStatements` optional	boolean	Whether statements are automatically emailed to the payee’s contact when generated. Defaults to `false`.
`paymentProviderId` optional	integer	1 - Tipalti 2 - PayPal Only necessary when using a payment provider integration for paying the payee.
`paymentProviderName` optional	string	The name of the payment provider, e.g. `"Tipalti"` or `"PayPal"`. Should be set together with `paymentProviderId` when changing the payee’s payment provider — see the Tipalti payee flow for a worked example.
`paymentUserId` optional	string	The payment provider’s user identifier for the payee (e.g. the PayPal email address, or the pending Tipalti value). Only necessary when using a payment provider integration.
`isBlocked` optional	boolean	Whether the payee is blocked from receiving payments. Defaults to `false`. This can also be changed via the dedicated `/accounting/payee/block` and `/accounting/payee/unblock` endpoints, which may apply additional side effects beyond just this flag.

Once a value has been saved for taxDomicileCountryId, it becomes permanently fixed for that payee. Any later payee/save request that sends a different value — or omits the field entirely — is rejected with 400 Bad Request:

"Tax Domicile Country cannot be updated once it is set."

Omitting the field counts as an attempted change to null, so once this field has a value you must resend that exact same value on every subsequent edit to the payee. This behavior matches taxDomicileCountryId on the contract Payee Object — it’s the same underlying field.

If contactId is 0 (or omitted) while the nested contact.contactId references a contact that already exists (e.g. one belonging to a different payee), the request fails with an unhandled 500 Internal Server Error.

To avoid both problems, always keep contactId and contact.contactId in sync: both 0 for a new contact, or both set to the same existing ID for an update.

Contact Object

Parameter	Type	Description
`contactId` optional	integer	The ID for an existing contact. When set to `0`, a new contact is created. (Default)
`name` optional	string	The name of the contact. Defaults to the `companyName`.
`email` optional	string	The contact’s email address. Used for sending statement notifications when enabled.
`phone` optional	string	The contact’s phone number.
`address` optional	string	The contact’s street address.
`address2` optional	string	The contact’s secondary address line.
`city` optional	string	The contact’s city.
`state` optional	string	The contact’s state or region.
`zipcode` optional	string	The contact’s postal code.
`countryId` optional	integer	The contact’s country ID. Look up country IDs using the `GET /common/lookup/countries` resource.

Example

Request body

{
  "payeeId": 0,
  "companyName": "string",
  "isCompany": true,
  "companyOrIndividualID": "string",
  "contactId": 0,
  "contact": {
    "contactId": 0,
    "name": "string",
    "email": "string",
    "phone": "string",
    "address": "string",
    "address2": "string",
    "city": "string",
    "state": "string",
    "zipcode": "string",
    "countryId": 0
  },
  "currencyCode": "string",
  "taxDomicileCountryId": 0,
  "vatNumber": "string",
  "taxIdNumber": "string",
  "vendorId": "string",
  "minimumPayment": 0,
  "autoSendStatements": false,
  "paymentProviderId": 0,
  "paymentProviderName": "string",
  "paymentUserId": "string",
  "isBlocked": false
}

Response

{
  "isCompany": true,
  "companyOrIndividualID": "string",
  "balance": 0,
  "minimumPayment": 0,
  "autoSendStatements": false,
  "lastStatementSentDate": null,
  "lastStatementDate": null,
  "lastPayementDate": null,
  "paymentProviderId": 0,
  "paymentProviderName": "string",
  "paymentUserId": "string",
  "contactId": 0,
  "payorEnterpriseCurrencyCode": "string",
  "currencyCode": "string",
  "lastPaymentRequestedAt": null,
  "canRequestPayment": false,
  "contact": {
    "contactId": 0,
    "name": "string",
    "currencyCode": null,
    "phone": "string",
    "email": "string",
    "address": "string",
    "address2": "string",
    "zipcode": "string",
    "countryId": 0,
    "imageId": null,
    "image": null,
    "isActive": true,
    "labelId": null,
    "publisherId": null,
    "artistId": null,
    "city": "string",
    "state": "string",
    "location": null,
    "contactRoleId": null
  },
  "role": "string",
  "licensors": null,
  "isInvited": false,
  "isInvitationAccepted": null,
  "contractsNames": [],
  "kountStatusId": null,
  "kountStatusName": null,
  "isBlocked": false,
  "enterpriseId": 0,
  "isEnterpriseVip": false,
  "isEnterpriseWhiteListed": false,
  "notesCount": 0,
  "isLockedOut": false,
  "userId": null,
  "vatNumber": "string",
  "lastPaymentStatus": "",
  "vendorId": "string",
  "taxIdNumber": "string",
  "taxDomicileCountryId": 0,
  "paymentInfoRequestedAt": null,
  "isPortalPayee": true,
  "isRoyaltyTokenPayee": false,
  "status": 4,
  "payeeId": 0,
  "companyName": "string",
  "payeeProvider": null,
  "email": null
}

Retrieving Payees

Authentication Requirements

These endpoints require an access token from the parent account.

GET `/accounting/payee/all`

Retrieves a paginated list of payees in the account, with support for filtering, sorting, and searching.

Query params

Parameter	Type	Description
`pageNumber` optional	integer	The page number of the results to retrieve.
`pageSize` optional	integer	The number of items to return per page. Default 100.
`orderByProperty` optional	string	The property to sort the results by, e.g. `companyName`, `balance`, or `payeeId`. See callout below.
`orderByDescending` optional	boolean	If `true`, orders the results in descending order. If `false` or omitted, orders in ascending order.
`searchText` optional	string	A search term to filter payees by company name. The search is case-insensitive.
`isInvited` optional	boolean	Filters payees by whether they’ve been invited to the payee portal.
`isBlocked` optional	boolean	Filters payees by blocked status.
`isRoyaltyTokenPayee` optional	boolean	Filters payees by whether they hold royalty tokens.
`hasEnterprise` optional	boolean	Filters payees by whether they’re linked to a child enterprise.
`paymentProviderID` optional	integer	Filters payees by `paymentProviderId`.
`payeeStatus` optional	integer	Filters payees by the same numeric status code returned in the response body’s `status` field.
`releaseId` optional	integer	Filters payees associated with a specific release.

orderByProperty isn’t validated against a fixed list — it must match an actual property name on the response object (e.g. companyName, balance, payeeId, currencyCode). An unrecognized value doesn’t return a clean validation error — it fails with a 400 Bad Request: "Value cannot be null.\r\nParameter name: property".

Example

Request

curl -X GET 'https://api.revelator.com/accounting/payee/all?pageSize=2'

Response

{
  "totalItemsCount": 4339,
  "pageNumber": 1,
  "pageSize": 2,
  "items": [
    {
      "balance": 0,
      "companyName": "string",
      "contact": {
        "contactId": 0,
        "name": "string",
        "currencyCode": null,
        "phone": null,
        "email": "string",
        "address": null,
        "address2": null,
        "zipcode": null,
        "countryId": null,
        "imageId": null,
        "image": null,
        "isActive": true,
        "labelId": null,
        "publisherId": null,
        "artistId": null,
        "city": null,
        "state": null,
        "location": null,
        "contactRoleId": null
      },
      "currencyCode": "USD",
      "enterpriseId": 0,
      "isBlocked": false,
      "isEnterpriseVip": false,
      "isEnterpriseWhiteListed": false,
      "isInvited": true,
      "isInvitationAccepted": true,
      "isLockedOut": false,
      "lastPaymentDate": null,
      "lastPaymentStatus": 0,
      "lastPaymentStatusName": "",
      "lastStatementDate": null,
      "lastStatementSentDate": null,
      "minimumPayment": 50.0,
      "notesCount": 0,
      "payeeId": 0,
      "paymentInfoRequestedAt": null,
      "paymentProviderId": null,
      "paymentProviderName": null,
      "paymentUserId": null,
      "userId": "00000000-0000-0000-0000-000000000000",
      "isPortalPayee": false,
      "isRoyaltyTokenPayee": false,
      "payeeSettingsChangesAllowed": true,
      "status": 5
    }
  ],
  "additionalCounters": {
    "distribution": 3808.0,
    "portal": 531.0,
    "totalCount": 4339.0,
    "balance": 3960.16
  }
}

GET `/accounting/payee/{payeeId}`

Retrieves the full details for a specific payee — see the Payee and Contact objects documented under Creating/Editing Payees.

Example

Request

curl -X GET 'https://api.revelator.com/accounting/payee/123456'

Response

{
  "isCompany": true,
  "companyOrIndividualID": null,
  "balance": 0,
  "minimumPayment": 50.0,
  "autoSendStatements": false,
  "lastStatementSentDate": null,
  "lastStatementDate": null,
  "lastPayementDate": null,
  "paymentProviderId": null,
  "paymentProviderName": "",
  "paymentUserId": null,
  "contactId": 0,
  "payorEnterpriseCurrencyCode": "USD",
  "currencyCode": "USD",
  "lastPaymentRequestedAt": null,
  "canRequestPayment": false,
  "contact": {
    "contactId": 0,
    "name": "string",
    "currencyCode": null,
    "phone": null,
    "email": "string",
    "address": null,
    "address2": null,
    "zipcode": null,
    "countryId": null,
    "imageId": null,
    "image": null,
    "isActive": true,
    "labelId": null,
    "publisherId": null,
    "artistId": null,
    "city": null,
    "state": null,
    "location": null,
    "contactRoleId": null
  },
  "role": "string",
  "licensors": null,
  "isInvited": true,
  "isInvitationAccepted": null,
  "contractsNames": [],
  "kountStatusId": null,
  "kountStatusName": null,
  "isBlocked": false,
  "enterpriseId": 0,
  "isEnterpriseVip": false,
  "isEnterpriseWhiteListed": true,
  "notesCount": 0,
  "isLockedOut": false,
  "userId": "00000000-0000-0000-0000-000000000000",
  "vatNumber": null,
  "lastPaymentStatus": "",
  "vendorId": null,
  "taxIdNumber": null,
  "taxDomicileCountryId": null,
  "paymentInfoRequestedAt": null,
  "isPortalPayee": false,
  "isRoyaltyTokenPayee": false,
  "status": 5,
  "payeeId": 123456,
  "companyName": "string",
  "payeeProvider": null,
  "email": null
}

Analytics

Revenue

Rights

Creating/Editing Contracts

Authentication Requirements

Default Contract and Payee

POST /accounting/contract/save

Request Body

Contract Payee Object

Payee Object

Contract Licensor Object

Contract Terms Object

Request body

Retrieving Contracts

Authentication Requirements

GET /accounting/contracts

Query params

Request

Response

GET /accounting/contracts/{contractId}

Request

Response

Creating/Editing Payees

Authentication Requirements

POST /accounting/payee/save

Request Body

Contact Object

Request body

Response

Retrieving Payees

Authentication Requirements

GET /accounting/payee/all

Query params

Request

Response

GET /accounting/payee/{payeeId}

Request

Response

POST `/accounting/contract/save`

GET `/accounting/contracts`

GET `/accounting/contracts/{contractId}`

POST `/accounting/payee/save`

GET `/accounting/payee/all`

GET `/accounting/payee/{payeeId}`