Brutal Inconsistencies in API responses/documentation

Okay, there’s definitely a problem with Bank Transaction Explanations (BTE) in the API when transfering from 1 bank account to another.

Your docs say this:

“In general the explanation type is chosen by setting the category attribute. However, for paying an invoice, bill or transferring funds between bank accounts, the category is not required. To make a Smart User Payment, set the paid_user attribute, but omit the category attribute”

What does this mean? It means when creating a (BTE) for transferring money from 1 bank account to another I do NOT need to supply a category. That’s quite explicit.

But, when I post:

“{“bank_transaction”:“https://api.freeagent.com/v2/bank_transactions/ABCDEFG”,“dated_on”:“2017-06-02”,“transfer_bank_account”:“https://api.freeagent.com/v2/bank_accounts/HIJKLMN”,“description”:“Totally Unnecessary description for Bank Transaction Explanation.”}”

I get back a cryptic response that
HTTP 422 Error: Entry Type is invalid

Bonus points for anyone who can find any reference to “Entry Type” anywhere in the docs pertaining to BTEs

So I googled and here’s what I found:
https://groups.google.com/forum/#!topic/freeagent_api/JveQr2V33dU
https://groups.google.com/forum/#!topic/freeagent_api/t2Af7hj1juM
T8FTAWL5VFk
u2esPTjaPlo

So it would seem that this is a common-enough problem. I’ve tried throwing in a Category, for the craic, but it completely destroys the request and I get BS back.

Food for thought:

  • why do we need to provide a description for transfers? - you ignore it anyway and put in your own description
  • why do we need to provide a dated_on when the Bank Transaction itself has a date - can’t we default to that?
  • why do we need to provide a gross_value when the transaction has a value/unexplained_value? THIS was actually the original cause of the problem referring to Entry Type in Invalid. You were returning an error message that has absolutely nothing to do with gross value… which, one would assume, would default to the value of the original transaction.

This API makes me want to shoot my face off. I’m sorry, I don’t want to be rude or harsh, but these sorts of inconsistencies are SERIOUS hurdles to implementation and costs everyone time and money. Someone needs to take a few days and dig through the API and question consistency and error messages throughout.

If I spend 3hrs trying to get the API to work based on given error messages, which have nothing to do with the problem, it’s hugely frustrating. If the problem was gross_value, better to send back a response that says: “gross_value” isn’t specified. Even though specifying it is counter-intuitive. I’d rather have a counter-intuitive API over spurious errors.

1 Like

Hi Paul,

Thank you for keeping this discussion separate to Error with Bank Transaction Explanations - #2 by Paul_G1, and I’m sorry to hear that our API is causing frustration.

As you concluded, the issue with your first request was indeed omitting a gross_value. I agree that the error message returned when omitting a gross_value is very misleading, and I’ve written up an issue report so that fixing this can be prioritised.

For a little background (and for future Googler’s) entry_type is a field used internally while
mapping explanation types (invoice receipts, user payments or assignment directly to a category) to accounts. Often, seeing an error around this would indicate the lack of a category. As you pointed out, however, this is indeed not necessary while making certain types of requests (invoice receipts, bill payments etc), as the category can be inferred.

To answer your questions directly:

why do we need to provide a description for transfers? - you ignore it anyway and put in your own description

I’ve been able to create a transfer without a description using a POST body similar to that below:

{
  "bank_transaction_explanation": {
    "dated_on": "2017-06-07",
    "bank_transaction": "http://api.freeagent.com/v2/bank_transactions/502",
    "transfer_bank_account": "http://api.freeagent.com/v2/bank_accounts/81",
    "gross_value": 10
  }
}

I’ll log this as a documentation issue. The same also appears to be true of invoice receipts.

why do we need to provide a dated_on when the Bank Transaction itself has a date - can’t we default to that?

This is a good question, and I’ll log a further issue for discussion. It certainly feels like this shouldn’t be necessary.

why do we need to provide a gross_value when the transaction has a value/unexplained_value?

A transaction can have many explanations (each with different categories). As we’re dealing with accounts here, I feel it makes sense to be explicit about which portion of the transaction is assigned to which category.