Rights

Rights

Creating/Editing Contracts

Use the /contract/save resource to add or edit contracts.

  • This endpoint requires a token for the parent account.

    This endpoint can be used to trigger the creation (or modification) of a contract in the parent account as the result of a user action. General creation of contracts is not an activity appropriate for child account users.

  • A default contract and payee are automatically created upon account creation; the contract automatically inherits all assets in the account (that are not explicitly covered by a more specific contract), and the default payee is named as the only payee.

Unless otherwise stated, the Revelator API does not support partial updates. When editing an object, the existing values of any omitted parameters will be deleted or overwritten, according to the designated behavior for a null value for that parameter. Consequently, we recommend you always query the object you want to edit and modify the JSON object to avoid partial update problems.

Contract Types

POST /accounting/contract/save

Request Body

ParameterTypeDescription
name
required
stringName of the contract.
contractId
optional
integerId of the 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.
contractTypeId
required
integer1 - specifies a Distribution Agreement.
startDate
required
stringDate from which the contract is effective, in the format YYYY-MM-DD.
This date is for reference only is not enforced when calculating royalties.
expirationDate
required
stringDate the contract becomes ineffective, in the format YYYY-MM-DD. If your contract is “in perpetuity”, please indicate 2099-12-31.
This date is for reference only is not enforced when calculating royalties.
isActive
optional
booleanWhether the contract is active. Inactive contracts are not used for royalty calculations.
  • Always set as true for new contracts.
  • Defaults to false when editing existing contracts.
contractPayees
required
array of objectsEach object represents a payee and details their royalty information.
The sum of every non-comission payee’s sharePercentage must equal 100.
See Contract Payee Object
contractLicensors
required
array including one object*Object represents a licensor (rights holder) and provides information for which of the licensor’s assets should be subject to the contract.
*Although contractLicensors is an array, the array should include only one object. For additional licensors, please create a separate contract.
See Contract Licensor Object
contractReleases
optional
array of objectsSpecifies which releases should be included in the contract when only some of the licensors assets are included in the contract.
Each object in the array includes a release ID:
{"releaseid": <integer>}
  • When all of the licensors assets are included in the contract (includeFutureAssets is true) this parameter is not relevant.
  • When a release is included in this array, every track in the release will automatically be subject to the contract. The release’s individual tracks should not additionally be included in the contractTracks array.
contractTracks
optional
array of objectsSpecifies which tracks should be included in the contract when only some of the licensors assets are included in the contract, and only when some of the tracks on releases are included in the contract.
Each object in the array includes a track ID: {"trackid": <integer>}
  • When all of the licensor’s assets are included in the contract (includeFutureAssets is true) or only complete releases are included in the contract, this parameter is not relevant.
contractTerms
required
array of objectsSpecifies 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 1
integerRate type for mechanicals:
  • 1 - % of Sales
  • 2 - Penny Rate
  • 3 - Copyright Law
1Mandatory when payMechanicals is true.
mechanicalsSalesPercentage
optional 2
integerSales percent.
2Mandatory when mechanicalsTypeId is 1.
mechanicalsFixedPennyRate
optional 3
integerPenny rate.
3Mandatory when mechanicalsTypeId is 2.
mechanicalsIsFullRate
optional 4
booleanRate basis:
  • true - Full
  • false - Minimum
4Mandatory when mechanicalsTypeId is 3.
mechanicalsRatePercentage
optional 4
integerRate percent. 4Mandatory when mechanicalsTypeId is 3.

Contract Payee Object

ParameterTypeDescription
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
sharePercentage
optional
integerThe payee’s startingBalance.
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
objectDetails of the payee.
See Payee Object
permission
optional
objectThe 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

ParameterTypeDescription
payeeId
optional
integerID for an existing payee to associate with the contract.
  • When set to 0, creates a new payee. (Default)
A default payee (and default contract) is automatically created upon account creation.
you should never create a new payee for a user for whom you have already created a child account.
companyName
required
stringName of the payee. When omitted, defaults to the name of the contact.
contact
required
objectContact information for the payee.
contact.contactId
optional
integerID for an existing contact.
  • When set to 0, creates a new contact **(Default) **
contact.name
optional
stringName of the contact.
Defaults to the companyName.
contact.email
optional
stringContact’s email address.
This email is used for sending statement notifications when automatic email notifications are enabled.
currencyCode
optional
integerCurrency 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.
paymentProviderId
optional
integer
  • 2 - paypal
Only necessary when using the Paypal integration for paying the payee.
paymentUserId
optional
stringPaypal email address for the payee.
Only necessary when using the Paypal integration for paying the payee.

Contract Licensor Object

ParameterTypeDescription
id
optional
GUIDID for an existing contract licensor entity.
Not relevant for new contracts. Should be provided when editing existing releases.
licensorType
required
integerType of licensor that will be used to specify the assets to include in the contract.
  • 1 - artist*
  • 2 - label
* For artist licensors, you can only specify assets where the artist is the primary artist on the release level. Therefore, compilations cannot be specified for artist licensors. Additionally, when includeFutureAssets is true, only the primary artist on the asset is considered; contributors are ignored, including contributors with the role “primary”.
licensorId
required
stringID of the licensor. Either an artistId or labelId, according 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

ParameterTypeDescription
contractTermsId
optional
GUIDID for an existing contract terms entity.
  • Not relevant for new contracts. Should be provided when editing existing releases.
contractTermsRate
optional
integerPercent 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 integersIDs for the countries included or excluded from the contract. See isCountriesIncluded.
Lookup country IDs using the GET /common/lookup/countries resource.
distributorStores
optional
array of integersIDs 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 integersTypes 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 integersDelivery 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)