Home / Marketing Operations / REST API / Routes / Working With Financial APIs

Marketing Operations

Working With Financial APIs

Disclaimer

NOTE: This page is a work-in-progress…

Financial Object State Transitions

Commitments – State Transitions

Super Scripts

  1. Activity, Fiscal Year, and Period CAN’T be edited anymore
  2. No Aprimo approval process configured. Submit with no approval
  3. Can be edited by users with Commitment Approval, Edit rights UNLESS authorization process is Authorization Rules
  4. Can not be deleted if any associated fiscal periods have a status that is “Closed.”
  5. If invoices are associated that are not Draft or Rejected:
    1. Can’t delete
    2. Supplier can’t change
    3. Supplier contact can’t change
  6. Approval process type affects the wording here
  7. If approved, commitment reflects the edits. If rejected, commitment is reverted back to its previously approved value
  8. A user with “edit” rights can re-open a commitment to “Approved”, also “you can re-open a commitment by creating new commitment items for an open fiscal year.”

 

Invoices – State Transitions

Super Scripts

  1. No Aprimo Approvals Configured
  2. External Accounting Integration Configured
  3. Can be edited by users with Invoices Approval, Edit rights UNLESS authorization process is AuthorizationRules​
  4. Can be edited directly by users with Invoices Edit, Paid right. Otherwise, users must used a JV
  5. Depending on configuration:
    1. No GL – Enter “Date Paid” and invoice will be set to Paid
    2. With GL – Date Paid field will be populated automatically
    3. “Set Paid on Invoice Approval” sys param will auto fill Date Paid when Invoice is approved
  6. Financial status of associated activity cannot be set to “Locked”

Journal Vouchers – State Transitions

 

Super Scripts

  1. If GL – Posted Date field is filled in automatically. If No GL – User must enter the Post Dated to continue past Draft status.
  2. External Account Integration Configured

 

GET api/activities/{activityID}/forecasts

Required Domain Rights (one of the following bullets)

  • System Administrator
  • Activity, View + API user is on the Activity Financial View/Edit Access List
  • Activity, View + Integration API, Access

PUT api/activities/{activityID}/forecasts

Required Domain Rights (one of the following bullets)

  • System Administrator
  • Activity, View + Activity, Edit + API user is on the Activity Financial Edit Access List
  • Activity, View + Activity, Edit + Integration API, Access

GET api/activities/{activityID}/proposed-forecasts

Required Domain Rights (one of the following bullets)

  • System Administrator
  • Activity, View + API user is on the Activity Financial View/Edit Access List
  • Activity, View + Integration API, Access

GET api/activity-forecasts{forecastID}

Required Domain Rights (one of the following bullets)

  • System Administrator
  • Activity, View + API user is on the Activity Financial View/Edit Access List
  • Activity, View + Integration API, Access

GET api/activity-proposals/{activityProposalID}/forecasts

Required Domain Rights (one of the following bullets)

  • System Administrator
  • Proposal, View + API user is on the Activity Proposal’s View/Edit Access List
  • Proposal, View + Integration API, Access

PUT api/activity-proposals/{activityProposalID}/forecasts

Required Domain Rights (one of the following bullets)

  • System Administrator
  • Proposal, View + Proposal, Edit + API user is on the Activity Proposal’s Edit Access List
  • Proposal, View + Proposal, Edit + Integration API, Access

GET api/commitments

Required Domain Rights (one of the following bullets)

  • System Administrator
  • Commitment, View + Commitment, Edit + API user is on the Activity Financial View Access List
  • Commitment, View + Commitment, Edit + API user is in the financial group
  • is an approver on the commitment

GET api/commitments/{commitmentID}

Required Domain Rights (one of the following bullets)

  • System Administrator
  • Commitment, View + Commitment, Edit + API user is on the Activity Financial View Access List
  • Commitment, View + Commitment, Edit + API user is in the financial group
  • is an approver on the commitment

POST api/commitments/{commitmentID}/search

Required Domain Rights (one of the following bullets)

  • System Administrator
  • Commitment, View + Commitment, Edit + API user is on the Activity Financial View Access List
  • Commitment, View + Commitment, Edit + API user is in the financial group
  • is an approver on the commitment

POST api/commitments

Required Domain Rights (one of the following bullets)

  • System Administrator
  • Commitment, Edit
  • Commitment, Mass Entry

POST api/commitments/{commitmentID}/cancel

Required Domain Rights (one of the following bullets)

  • System Administrator
  • Commitment, Edit + API user is on the Activity Financial Edit Access List
  • Commitment, Edit + API user is in the financial group
  • Commitment, Mass Entry + API user is on the Activity Financial Edit Access List
  • Commitment, Mass Entry + API user is in the financial group

The following user does NOT have the necessary rights to cancel a commitment:

  • Commitment, View + API user is on the Activity Financial Edit Access List

Errors

  • if commitment status is draft (1), closed (12), canceled (13)
  • if the commitment is related to an active invoice or journal voucher
  • if the commitment has an item in a closed period
  • if the ID in the URL does not exist

A commitment may be canceled in one of the following statuses

  • Pending Auth Tree Approval (2)
  • Pending Pooled Approval (3)
  • Pending Funding Account Approval (4)
  • Approved (5)
  • Pending_Auth_Tree_Reapproval (6)
  • Pending_Pooled_Reapproval (7)
  • Pending_Funding_Account_Reapproval (8)
  • Rejected Auth Tree Approval (9)
  • Rejected Pooled Approval (10)
  • Rejected Funding Account Approval (11)

POST api/commitments/{commitmentID}/retrieve

Required Domain Rights (one of the following bullets)

  • System Administrator
  • Commitment, View + Commitment, Edit + API user is on the Activity Financial Edit Access List
  • Commitment, View + Commitment, Edit + API user is in the financial group
  • Commitment, Mass Entry

The following users do NOT have the necessary rights to retrieve a commitment:

  • Commitment, View + API user is on the Activity Financial Edit Access List
  • Commitment, View + Commitment, Edit + API user is on the Activity Financial View Access List

A commitment may be retrieved in one of the following statuses. Attempting to retrieve in any status not listed will result in an error.

  • Pending Auth Tree Approval (2)
  • Pending Pooled Approval (3)
  • Pending Funding Account Approval (4)
  • Pending_Auth_Tree_Reapproval (6)
  • Pending_Pooled_Reapproval (7)
  • Pending_Funding_Account_Reapproval (8)

POST api/commitments/{commitmentID}/submit

Required Domain Rights (one of the following bullets)

  • System Administrator
  • Commitment, View + Commitment, Edit + API user is on the Activity Financial Edit Access List
  • Commitment, View + Commitment, Edit + API user is in the financial group
  • Commitment, Mass Entry + API user is on the Activity Financial Edit Access List
  • Commitment, Mass Entry + API user is in the financial group

The following users do NOT have the necessary rights to submit a commitment:

  • Commitment, View + API user is on the Activity Financial Edit Access List
  • Commitment, View + Commitment, Edit + API user is on the Activity Financial View Access List

Commitments with the following status may NOT be submitted:

  • Status not in Draft or Rejected
  • The accociated activity’s financial status is locked
  • Funding Account is forecast
  • Tied to closed fiscal periods

POST api/commitments/{commitmentid}/approve

Required Domain Rights

  • System Administrator
  • Commitment, View + Commitment, Edit + commitment approval, access,  API user is on the Activity Financial Edit Access List,  is in the financial group, API User is a designated approver
  • Commitment, View + Commitment, Edit + commitment approval, access, API user is on the Activity Financial Edit Access List, is in the financial group, Integration API Access –
    • Note the user no longer has to be the designated approver
    • User can approver in the Pooled Approval stage (after Commitment has been nominally approved)

Additional Requirements:  Commitment should be in Approval state e.g. Pending Auth tree approval, pending funding account approval, pending pooled approval

 

POST api/commitments/{commitmentid}/reject

Required Domain Rights

  • System Administrator
  • Commitment, View + Commitment, Edit + commitment approval, access, API user is on the Activity Financial Edit Access List,  is in the financial group, API User is a designated approver
  • Commitment, View + Commitment, Edit + commitment approval, access, API user is on the Activity Financial Edit Access List, ,  is in the financial group, Integration API Access –
    • Note the user no longer has to be the designated approver
    • User can approver in the Pooled Approval stage (after Commitment has been nominally approved)

Additional Requirements:  Commitment should be in Approval state e.g. Pending Auth tree approval, pending funding account approval, pending pooled approval

PUT api/commitments/{commitmentID}

Required Domain Rights (one of the following bullets)

  • System Administrator
  • Commitment, Edit + API user is on the Activity Financial Edit Access List
  • Commitment, Edit + API user is in the financial group
  • Commitment, Mass Entry + API user is on the Activity Financial Edit Access List
  • Commitment, Mass Entry + API user is in the financial group

The following user does NOT have the necessary rights to update a commitment:

  • Commitment, View + API user is on the Activity Financial Edit Access List

Commitment statuses are as follows:

  • Draft
  • Pending Auth Tree Approval (2)
  • Pending Pooled Approval (3)
  • Pending Funding Account Approval (4)
  • Approved (5)
  • Pending Auth Tree Reapproval (6)
  • Pending Pooled Reapproval (7)
  • Pending Funding Account_Reapproval (8)
  • Rejected Auth Tree Approval (9)
  • Rejected Pooled Approval (10)
  • Rejected Funding Account Approval (11)
  • Closed (12)
  • Canceled (13)

Errors

  • If commitment status is approved (5), currency code may not be updated
  • When the currency code equals $USD, the exchange rate of a commitment item may only be updated with the value “automatic”
  • The ‘closed’ field is only editable when in Approved/Closed. This may not be set to closed if there are open line items (don’t auto-close commitment items if set this to closed).
  • The ‘currency_code’ field is only updateable when the commitment is in Draft status
  • If updating a commitment item, the ‘committed_fund_item’ field must be populated. This is not required if it is a new line item.
  • If updating a commitment item, the ‘committed_fund_id’ field is required
  • In a commitment item, the ‘activity_id’ specified must exist in the system. This field may only be updated before the commitment is approved
  • If updating a commitment item, the ‘exp_cat_id’ specified must exist in the system
  • In a commitment item, the ‘exchange_rate_id’ field is only updateable if the user has the ‘Financial, Variable Line Item Exchange Rates’ + the ‘Exchange Rates Configureable by Line Item – Commitments’ system parameter is set to ‘Yes’
  • In a commitment item, the ‘closed’ field may only be updated if the commitment status is approved
  • In a commitment item, the ‘fiscal_year_id’ specified must exist in the system. This field is not updateable once the commitment has been approved
  • In a commitment item, the ‘fiscal_period_id’ specified must exist in the system. This field must contain a value associated with the fiscal year
  • In a commitment item, the ‘price’ and ‘value’ fields must validate as decimals
  • In order to edit secure EAs, the user must be a member of the secure EA group

DELETE api/commitments/{commitmentID}

Required Domain Rights (one of the following bullets)

  • System Administrator
  • Commitment, Edit
  • Commitment, Mass Entry

A commitment may only be deleted in one of the following statuses. Attempting to delete in any status not listed will result in an error.

  • Draft
  • Pending Approval

Commitments with the following status may NOT be deleted:

  • Tied to an active invoice or journal voucher
  • Tied to closed fiscal periods

GET api/invoices

Required Domain Rights (one of the following bullets)

  • System Administrator
  • Commitment, View + API user is on the Activity Financial View Access List
  • Commitment, View + API user is in the financial group

GET api/invoices/{invoiceID}

Required Domain Rights (one of the following bullets)

  • System Administrator
  • Commitment, View + API user is on the Activity Financial View Access List
  • Commitment, View + API user is in the financial group

POST api/invoices/search

Required Domain Rights (one of the following bullets)

  • System Administrator
  • Invoice, View + API user is on the Activity Financial View Access List
  • Invoice, View + API user is in the financial group
  • No rights required to search for Invoices in the User’s approval queue

POST api/invoices

Required Domain Rights (one of the following bullets):

  • System Administrator
  • Invoice, View + Invoice, Edit + API user is on the Activity Financial Edit Access List
  • Invoice, View + Invoice, Edit + API user is in the financial group
  • Invoice, View + Invoice, Mass Entry + API user is on the Activity Financial Edit Access List
  • Invoice, View + Invoice, Mass Entry + API user is in the financial group
  • If the input body contains the funding account id of the invoice-item, user should have System Administrator or Invoice and Journal Voucher, Override Funding Account

POST api/invoices/{invoiceID}/submit

Required Domain Rights (one of the following bullets):

  • System Administrator
  • Invoice, View + Invoice, Edit + API user is on the Activity Financial Edit Access List
  • Invoice, View + Invoice, Edit + API user is in the financial group
  • Invoice, View + Invoice, Mass Entry + API user is on the Activity Financial Edit Access List
  • Invoice, View + Invoice, Mass Entry + API user is in the financial group
  • If the invoice approval system parameter is set to ‘Yes – by invoice approval, access security right (pooled)’ or ‘Yes – by invoice authorization rules and pooled’, then the API user must have invoice aproval access + in the financial group

The following users do NOT have the necessary rights to submit an invoice:

  • Invoice, View + API user is on the Activity Financial Edit Access List
  • Invoice, View + Invoice, Edit + API user is on the Activity Financial View Access List

Invoices with the following status may be submitted*:

  • Draft
  • Rejected

* the API call will err if the invoice exceeds the value of the activity forecast and the ‘Invoices Threshold Check’ system parameter is set to ‘Yes-error’

Invoices with the following status may NOT be submitted:

  • isPendAuthTreeApproval = 1
  • isPendFundAcctOwnApp = 2
  • isPendPoolApproval = 3
  • isPendPayment = 4
  • isPendPayReady = 5
  • isPendPaySent = 6
  • isPaid = 7
  • isRejAuthTreeApproval = 8
  • isRejFundAcctOwnApp = 9
  • isRejPoolApproval = 10
  • isRejAcctPayable = 11
  • isCanceled = 12

POST api/invoices/{id}/cancel

Required Domain Rights (one of the following bullets):

  • System Administrator
  • Invoice, View + Invoice, Edit + API user is on the Activity Financial Edit Access List
  • Invoice, View + Invoice, Edit + API user is in the financial group
  • Invoice, View + Invoice, Mass Entry + API user is on the Activity Financial Edit Access List
  • Invoice, View + Invoice, Mass Entry + API user is in the financial group
  • If the invoice approval system parameter is set to ‘Yes – by invoice approval, access security right (pooled)’ or ‘Yes – by invoice authorization rules and pooled’, then the API user must have invoice aproval access + in the financial group

The following user does NOT have the necessary rights to cancel an invoice:

  • Invoice, View + API user is on the Activity Financial Edit Access List

Invoices with the following status may be canceled:

  • isPendAuthTreeApproval = 1
  • isPendFundAcctOwnApp = 2
  • isPendPoolApproval = 3
  • isPendPayment = 4
  • isPendPayReady = 5
  • isRejAuthTreeApproval = 8
  • isRejFundAcctOwnApp = 9
  • isRejPoolApproval = 10
  • isRejAcctPayable = 11

Invoices with the following status may NOT be canceled:

  • isDraft = 0
  • isPaid = 7
  • isCanceled = 12
  • isPendPaySent = 6

POST api/invoices/{invoiceID}/retrieve

Required Domain Rights (one of the following bullets):

  • System Administrator
  • Invoice, Edit
  • Invoice, Mass Entry

POST api/invoices/{invoiceID}/reject

Required Domain Rights (one of the following bullets):

  • User must be in the approval list
  • If the invoice is in the Pending Payment Sent status, System Admin is required, and the ‘Integrate With External Accounting System’ system parameter must be Yes

Invoices with the following status may be rejected:

  • Pending Authorization Tree Approval
  • Pending Funding Account Owner Approval
  • Pending Pooled Approval
  • Pending Payment Sent

POST api/invoices/{invoiceID}/sent

Required Domain Rights:

  • System Administrator and the systemparameter(IntegrateWithExternalAccountingSystem) should be set as 1

NOTE: The GL Integration system parameter must be enabled in order to use this route, and the invoice must be in the status of ‘Pending Payment (Ready)’

PUT api/invoices/{invoiceID}

Required Domain Rights (one of the following bullets):

  • System Administrator
  • Invoice, View + Invoice, Edit + API user is on the Activity Financial Edit Access List
  • Invoice, View + Invoice, Edit + API user is in the financial group
  • Invoice, View + Invoice, Mass Entry + API user is on the Activity Financial Edit Access List
  • Invoice, View + Invoice, Mass Entry + API user is in the financial group
  • If the current invoice’s status is Paid, user must have the InvoiceEditPaid permission
  • If the input body contains the funding account id of the invoice-item, user should have System Administrator or Invoice and Journal Voucher, Override Funding Account

DELETE api/invoices/{invoiceID}

Required Domain Rights (one of the following bullets):

  • System Administrator
  • Invoice, View + Invoice, Edit + API user is on the Activity Financial Edit Access List
  • Invoice, View + Invoice, Edit + API user is in the financial group
  • Invoice, Mass Entry + API user is on the Activity Financial Edit Access List
  • Invoice, Mass Entry + API user is in the financial group

The following users do NOT have the necessary rights to delete an invoice:

  • Invoice, View + API user is on the Activity Financial Edit Access List
  • Invoice, View + Invoice, Edit + API user is on the Activity Financial View Access List

Invoices with the following status may be deleted:

  • Draft (with an associated commitment)
  • Rejected (without an associated commitment or JV)
  • Pending Approval

Invoices with the following status may NOT be deleted:

  • Cancelled
  • Paid (without a JV and without a commitment)
  • Paid (with a JV)

GET api/journal-vouchers

Required Domain Rights (one of the following bullets):

  • System Administrator
  • Journal Voucher, View + API user is on the Activity Financial Edit Access List
  • Journal Voucher, View + API user is in the financial group

GET api/journal-vouchers/{voucherID}

Required Domain Rights (one of the following bullets):

  • Journal Voucher, View + API user is on the Activity Financial Edit Access List
  • Journal Voucher, View + API user is in the financial group

POST api/journal-vouchers/search

Required Domain Rights (one of the following bullets):

  • Journal Voucher, View + API user is on the Activity Financial Edit Access List
  • Journal Voucher, View + API user is in the financial group

POST api/journal-vouchers

Required Domain Rights (one of the following bullets):

  • System Administrator
  • Journal Voucher, View + Journal Voucher, Edit + API user is on the Activity Financial Edit Access List
  • Journal Voucher, View + Journal Voucher, Edit + API user is in the financial group

POST api/journal-vouchers/{voucherID}/submit

A JV in draft status can be submitted, and turns to:

  • ‘Pending Reconciliation’ – when the GL Integration system parameter is set to no
  • ‘Pending Reconciliation (Ready)’ – when the GL Integration system parameter is yes

Required Domain Rights (one of the following bullets):

  • System Administrator
  • Journal Voucher, View + Journal Voucher, Edit + API user is on the Activity Financial Edit Access List
  • Journal Voucher, View + Journal Voucher, Edit + API user is in the financial group

Error thrown when a JV is submitted from one of the following statuses:

  • PendingReconciledReady = 2
  • PendingReconciledSent = 3
  • PendingReconciliation = 4
  • Reconciled = 5
  • Canceled = 6
  • RejectedAtAccountsPayable = 7

POST api/journal-vouchers/{voucherID}/reject

Required Domain Rights (one of the following bullets):

  • System Administrator
  • Journal Voucher, View + Journal Voucher, Edit

A journal voucher can be reconciled from one of the following statuses:

  • PendingReconciledReady
  • PendingReconciledSent
  • PendingReconciled

POST api/journal-vouchers/{voucherID}/cancel

Required Domain Rights (one of the following bullets):

  • System Administrator
  • Journal Voucher, View + Journal Voucher, Edit + API user is on the Activity Financial Edit Access List
  • Journal Voucher, View + Journal Voucher, Edit + API user is in the financial group

The following user cannot cancel a journal voucher:

  • Journal Voucher, View + Journal Voucher, Edit + API user is on the Activity Financial View Access List

A journal voucher can be canceled from one of the following statuses:

  • PendingReconciledReady = 2
  • PendingReconciliation = 4
  • RejectedAtAccountsPayable = 7

A journal voucher may NOT be canceled from one of the following statuses:

  • Draft
  • Reconciled
  • Canceled
  • PendingRecondiledSent

POST api/journal-vouchers/{voucherID}/sent

Required Domain Rights:

  • System Administrator

POST api/journal-vouchers/{voucherID}/reconcile

Required Domain Rights (one of the following bullets):

  • System Administrator
  • Journal Voucher, Edit + Journal Voucher, Mass Reconcile

A journal voucher can be reconciled from one of the following statuses:

  • PendingReconciledReady
  • PendingReconciledSent

PUT api/journal-vouchers/{voucherID}

Required Domain Rights (one of the following bullets):

  • System Administrator
  • Journal Voucher, Edit + API user is on the Activity Financial Edit Access List
  • Journal Voucher, Edit + API user is in the financial group

Errors

  • if status is Pending
  • if status is Reconciled
  • if status is Canceled
  • if associated invoice status is Pending (invoice status must be Paid)
  • if associated commitment status is Draft or Rejected (commitment status must be Approved)
  • if the JV is associated with a commitment (no invoice), supplier_id and contact_id are not editable — they are taken from the commitment. All items must include a description. Error thrown if activity or expense category are specified in request
  • if the JV is associated with an invoice (no commitment), supplier_id and contact_id are not editable — they are taken from the invoice. All items must include a description. Error thrown if activity or expense category are specified in request
  • if the invoice is removed for a JV, at least one JV item (or invoiceID or commitmentID) is required. Expense category and funding account are editable
  • if funding account of the activity is not tied to the posting fiscal year
  • if there is no JV item in the request
  • if deleting a JV item results in no items on the JV
  • required fields on JV items are required, since the item collection is updated as flush-and-fill (all existing items are deleted, and replaced with items in the request)
  • if invalid JV ID is specified in the URL
  • if financial status for an associated activity is locked
  • if fiscal year or fiscal period has been closed via a closeout process

Additional Notes

  • if price or quantity are not specified on line items, they will default to zero
  • total and base total are ignored if input

DELETE api/journal-vouchers/{voucherID}

A JV can be deleted from any of the following statuses:

  • Draft = 1
  • Pending Reconciliation = 4
  • Pending Reconciled (Ready)
  • Canceled = 6
  • Rejected at Accounts Payable = 7

Required Domain Rights (one of the following bullets):

  • System Administrator
  • Journal Voucher, View + Journal Voucher, Edit + API user is on the Activity Financial View Access List
  • Journal Voucher, View + Journal Voucher, Edit + API user is in the financial group

Error thrown when a JV is deleted from one of the following statuses:

  • PendingReconciledSent = 3
  • Reconciled = 5